给AI写一份“岗位操作手册”——Skill 编写的完整流程与模板
关注 霍格沃兹软件测试开发 公众号，回复「资料」, 领取人工智能测试开发技术合集
上次我写了篇《一个文件夹 + 一个 Markdown 文件 = 你的第一个 Skill》，后台直接炸了。一堆同行加我微信，劈头盖脸就是一句：“我的 Skill 怎么跟智障一样？”
我说你咋写的，他甩过来一段提示词，我一看，果然——“你是资深工程师，请帮我生成高质量代码”。就这一句话，没了。
哥们儿，你这不叫 Skill，这叫许愿。
今天咱们往深了聊。既然 Skill 本质上是给 AI 配了一本随身携带的项目手册，那你不妨换个思路——你就当 AI 是个刚入职的 P7，你作为他的技术主管，得给他写一份《岗位操作手册》。 什么时候干什么、怎么干、用啥工具、底线是什么，写得越清楚，他产出越靠谱。
下面这个完整流程和模板，是我在团队内部花了四个月、迭代了二十多个 Skill 之后沉淀下来的。照这个套路走，你的 AI 员工离“独当一面”就不远了。
一、先给岗位画个像：别让 AI 觉得自己啥都能干
很多 Skill 翻车，根儿就在第一步：职责边界不清。你写“帮我写代码”，AI 就会在写周报、写 SQL、写前端组件之间精神分裂。
正确的姿势是画一个极其明确的圈：
这个 Skill 负责什么场景？（比如“Java 后端 CRUD 接口开发”）
输入是什么？（产品需求描述 + 数据库表结构）
输出是什么？（符合项目规范的 Controller/Service/Mapper 代码 + 单元测试 + API 文档注释）
绝对不能干什么？（不能擅自引入新的依赖、不能修改已有接口的签名）
我写过一个 api-generator 的 Skill，第一版就是职责没锁死，它有一次自作主张把我一个老接口的返回值类型给改了，下游三个服务直接全红。后来我在 SKILL.md 里加了一条铁律：“若需修改已有接口，必须先输出告警并中止，严禁直接改动。” 后来它老实得跟被拉过黑的司机一样。
操作建议： 找一张纸，或者在 Notion 里列三个清单：必须做、可以做、严禁做。 这个清单，就是你 Skill 的宪法大纲。
二、收材料：AI 的行业知识，全靠你喂
想象一下，你那个 P7 空降到团队，你总得给他交接资料吧——代码规范、架构图、数据库字典、核心链路时序图、最常踩的坑列表。
Skill 也是一样。SKILL.md 里只有指令是不够的，你得把“公司内部资料”打包塞进文件夹。我现在的标准操作是建一个 references/ 子目录，里面扔这些东西：
code-style.md —— 团队编码规范（别扔个阿里巴巴手册 PDF 进去，把跟咱们切实相关的几条摘出来）
architecture.md —— 系统分层说明，哪个包放什么，别让他把 Service 写到 Controller 层去
db-dict.md —— 核心表的字段注释、索引说明，特别是那些命名鬼才起的字段名，比如 is_del 明明叫 deleted_at
pitfalls.md —— 历史故障复盘，哪些写法已经搞出过生产事故，禁止再次出现
examples/ —— 放两三个高质量的接口实现样例，正面案例比一百条规则都好使
这些资料一挂载，AI 就从一个通用大脑变成了你们项目的专用外挂。我曾经把支付模块历次因为“状态机并发”导致的故障复盘扔进去，后来让它生成新接口时，它自动在关键状态变更处加上了乐观锁注释和推荐写法，这意识已经超越了一半的组员。
人工智能技术学习交流群
伙伴们，对AI测试、大模型评测、质量保障感兴趣吗？我们建了一个 「人工智能测试开发交流群」，专门用来探讨相关技术、分享资料、互通有无。无论你是正在实践还是好奇探索，都欢迎扫码加入，一起抱团成长！期待与你交流！👇
三、动笔写手册：一套即插即用的模板
到了重头戏。下面这个模板是我打磨了很久的，你可以直接复制走，把方括号里的内容换成你的。
name: [skill-name]
description: [一句话精准描述，让调度器知道该何时激活，如：当用户请求生成 Java Spring Boot 后端接口代码时使用]
角色与使命
你是一名 [具体角色，如：资深 Java 后端工程师]，专精于 [领域，如：高并发电商交易系统]，遵循 [团队/公司规范名称]。
你的唯一任务：[一句话讲清楚产出，如：根据给定的接口需求描述和表结构，生成完整且可运行的 Controller/Service/DAO 代码及单元测试。]
工作守则（最高优先级）
以下规则违反任何一条，结果将被视为失败：
- [硬规则1，如：所有数据库操作必须包含事务注解 @Transactional，且只读操作标注 readOnly=true]
- [硬规则2，如：异常处理严禁吞掉原始异常，必须记录完整堆栈并抛出业务异常]
- [硬规则3，如：生成的代码必须通过 Checkstyle 和 Sonar 规则，圈复杂度不超过 10]
- [禁止项，如：严禁引入未在 pom.xml 中声明的第三方依赖]
上下文知识库
在生成任何输出前，务必完整阅读并理解以下参考资料：
references/code-style.md：编码规范references/architecture.md：系统分层和包结构约定references/db-dict.md：数据库表结构及字段说明references/pitfalls.md：历史故障及禁止写法列表references/examples/：优秀代码样例
输出规范
- 代码格式：严格按照
references/code-style.md执行 - 注释语言：所有注释使用中文
- 必须包含：[单元测试、Swagger 接口文档注解、关键逻辑的行内注释]
- 交付物结构：
- 改动文件清单及路径
- 每个文件完整代码块
- 自检清单（是否违反工作守则）
交互规则
- 如果需求不明确或缺少必要的表结构信息，必须先向我提问，禁止猜测。
- 当需要修改已有接口时，必须先给出影响分析和修改建议，等我确认后再执行。
这个模板骨架是通用的，你往里面填肉就行。诀窍：规则要细到可以无脑执行，避免使用“请尽量”“建议”这种模糊词，一律用“必须”“严禁”。
四、上岗培训：别急着让他干活，先考他一轮
手册写完了，你以为就完事了？新员工入职还得有个试用期呢。Skill 的测试，我分三步走，缺一步都可能埋雷。
第一步：历史案例回放。 拿出你项目中过去三个真实需求（包括那个搞出过事故的），让 Skill 重新生成方案或代码。拿他的产出跟当年人工写的、以及最终出问题的点一一比对。我那个支付 Skill 刚写出来时，在一个退款场景里漏了幂等性校验，我直接把那条规则补进 pitfalls.md 里：“退款接口必须在入口处做幂等判断，以业务流水号 + 退款批次号作为唯一键。”
第二步：边界试探。 故意给一些刁钻输入：字段为空、文件超长、一个需求里混了两个模块的改动。看 Skill 是硬着头皮瞎编，还是按交互规则主动提问。这能测出你规则里的漏洞。
第三步：同行评议。 把你认为调好的 Skill，让另一个同事加载，跑同样的任务，看他觉得输出质量如何。这会暴露很多“你自己习惯了但别人受不了”的隐性知识。有一回我写的 Skill 里习惯用 var 声明局部变量，同事测试时说团队规范里明令禁止，我羞愧地加了条规则。
只有跑完这三轮，这个 Skill 才算“转正”。
五、版本管理：把 SKILL.md 当生产代码看待
很多朋友把 Skill 写完就扔那儿了，结果三个月后项目技术栈升级，Skill 还在给你生成旧版本的代码，那就是定时炸弹。
我现在强制要求自己：
每个 Skill 文件夹用 Git 管理，SKILL.md 头部版本号手动 +1
任何一次项目规范、架构、依赖的变更，必须同步更新关联 Skill 的参考资料
每个月挑一个低峰期，用最新的业务需求跑一遍 Skill，检查产出是否仍然合格，不合格就拉分支迭代
你想想，你给新人的纸质手册如果一直不更新，这新人迟早变成技术债务。AI 员工没长腿，不会自己主动去了解项目变化，锅全在你这儿。
六、最常翻的四个跟头，提前告诉你
① 企图用一个 Skill 统治所有场景。 千万别。我拆了七八个 Skill：生成代码的、审查代码的、写单元测试的、生成 API 文档的、分析故障的。每个只做一个细分任务，准确度远超一个“全能神”。
② 提示词堆砌无害的废话。 “你是一个经验丰富的、细心的、负责的、有团队合作精神的……” 这种形容词一串，除了浪费 token 窗口毫无意义。把每一句话都换成可执行的指令。
③ 把 Skill 当成黑盒，不去看中间推理。 Claude 的 Skills 支持展示思考过程，如果产出不对，一定要打开看它引用了你给的哪条资料，推理链在哪里断了，然后去改手册，而不是反复生成碰运气。
④ 忽略了调度描述。 YAML 头里的 description 是给 AI 调度器看的索引。你写个“帮做事情”，AI 可能会在你让写诗的时候也激活这个 Skill。描述必须准确到场景，我那个代码审查 Skill 的描述是：“当用户要求审查或评审 Java 代码片段/PR 时使用”。
写在最后
写完第一个真正可用的 Skill 那天，我瘫在椅子上抽烟，心里冒出一个挺可怕的想法：“妈的，我现在是不是在给自己培养一个永远不会离职、还不用发工资的代码机器？”
后来想通了。我们这一行，经验这东西很容易烂在脑子里或者随着人离职流失。但写成一本又一本《岗位操作手册》，经验就成了组织的固定资产，能复制、能迭代、能传递。
别等了。现在打开你的编辑器，新建文件夹 my-team-skill，把模板粘进去，然后想想你带新人时重复最多的一句话是什么——把它写成第一条规则。你的 AI 员工，今天就该入职了。
推荐学习
测试智能体与智能化测试平台公开课，从Web/App/接口测试智能体，再到智能体工具Opencode，爱测智能化测试平台，手把手带你掌握AI智能体与智能化测试平台！
👉 扫码进群，报名学习！
关于我们
霍格沃兹测试开发学社，隶属于 测吧（北京）科技有限公司，是一个面向软件测试爱好者的技术交流社区。
学社围绕现代软件测试工程体系展开，内容涵盖软件测试入门、自动化测试、性能测试、接口测试、测试开发、全栈测试，以及人工智能测试与 AI 在测试工程中的应用实践。
我们关注测试工程能力的系统化建设，包括 Python 自动化测试、Java 自动化测试、Web 与 App 自动化、持续集成与质量体系建设，同时探索 AI 驱动的测试设计、用例生成、自动化执行与质量分析方法，沉淀可复用、可落地的测试开发工程经验。
在技术社区与工程实践之外，学社还参与测试工程人才培养体系建设，面向高校提供测试实训平台与实践支持，组织开展 “火焰杯” 软件测试相关技术赛事，并探索以能力为导向的人才培养模式，包括高校学员先学习、就业后付款的实践路径。
同时，学社结合真实行业需求，为在职测试工程师与高潜学员提供名企大厂 1v1 私教服务，用于个性化能力提升与工程实践指导。
浙公网安备 33010602011771号