给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_atpitfalls.md—— 历史故障复盘，哪些写法已经搞出过生产事故，禁止再次出现examples/—— 放两三个高质量的接口实现样例，正面案例比一百条规则都好使
这些资料一挂载，AI 就从一个通用大脑变成了你们项目的专用外挂。我曾经把支付模块历次因为“状态机并发”导致的故障复盘扔进去，后来让它生成新接口时，它自动在关键状态变更处加上了乐观锁注释和推荐写法，这意识已经超越了一半的组员。
三、动笔写手册：一套即插即用的模板
到了重头戏。下面这个模板是我打磨了很久的，你可以直接复制走，把方括号里的内容换成你的。
--- name: [skill-name] description: [一句话精准描述，让调度器知道该何时激活，如：当用户请求生成 Java Spring Boot 后端接口代码时使用] --- # 角色与使命 你是一名 [具体角色，如：资深 Java 后端工程师]，专精于 [领域，如：高并发电商交易系统]，遵循 [团队/公司规范名称]。 你的唯一任务：[一句话讲清楚产出，如：根据给定的接口需求描述和表结构，生成完整且可运行的 Controller/Service/DAO 代码及单元测试。] # 工作守则（最高优先级） 以下规则违反任何一条，结果将被视为失败： 1. [硬规则1，如：所有数据库操作必须包含事务注解 @Transactional，且只读操作标注 readOnly=true] 2. [硬规则2，如：异常处理严禁吞掉原始异常，必须记录完整堆栈并抛出业务异常] 3. [硬规则3，如：生成的代码必须通过 Checkstyle 和 Sonar 规则，圈复杂度不超过 10] 4. [禁止项，如：严禁引入未在 pom.xml 中声明的第三方依赖] # 上下文知识库 在生成任何输出前，务必完整阅读并理解以下参考资料： - `references/code-style.md`：编码规范 - `references/architecture.md`：系统分层和包结构约定 - `references/db-dict.md`：数据库表结构及字段说明 - `references/pitfalls.md`：历史故障及禁止写法列表 - `references/examples/`：优秀代码样例 # 输出规范 - 代码格式：严格按照 `references/code-style.md` 执行 - 注释语言：所有注释使用中文 - 必须包含：[单元测试、Swagger 接口文档注解、关键逻辑的行内注释] - 交付物结构： 1. 改动文件清单及路径 2. 每个文件完整代码块 3. 自检清单（是否违反工作守则） # 交互规则 - 如果需求不明确或缺少必要的表结构信息，必须先向我提问，禁止猜测。 - 当需要修改已有接口时，必须先给出影响分析和修改建议，等我确认后再执行。这个模板骨架是通用的，你往里面填肉就行。诀窍：规则要细到可以无脑执行，避免使用“请尽量”“建议”这种模糊词，一律用“必须”“严禁”。
四、上岗培训：别急着让他干活，先考他一轮
手册写完了，你以为就完事了？新员工入职还得有个试用期呢。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 员工，今天就该入职了。