上次我写了篇《一个文件夹 一个 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且只读操作标注 readOnlytrue] 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 员工今天就该入职了。