在 Claude Code 里把团队规范写成可版本化的 Skill

这篇文章讲的是把 AI 编码代理的工作说明当成代码来管理：写成 SKILL.md、进仓库、走 PR、随代码分发。核心机制是渐进式披露，代理平时只加载名称和描述，任务匹配时才读完整指令，因此几十个 Skill 也不会撑爆上下文。

为什么提示词撑不住

• 好用的提示词是一次性产物，随对话消失，没有变更历史，新同事也找不到。
• 重复：每天做代码审查的人要反复敲同样的要求，比如检查空值处理、标记缺失测试、忽略自动生成的迁移文件、按严重程度排序。
• 不一致：十个开发者写十个提示词，模型会用看似合理的默认假设填补空白，结果系统性偏离。
• 知识流失：资深工程师打磨过的审查提示词最多躺在群聊里，慢慢烂掉。

Skill 是什么

• 一个文件夹，里面是 SKILL.md，可附带模板、参考文档和可执行脚本。
• 文件结构为 YAML frontmatter 加 Markdown 指令，只有 name 和 description 两个必填字段。
• 示例 adr-writer：从 docs/adr/ 取下一个空号、用本 Skill 文件夹里的 template.md、从代码核实受影响模块而不是猜；规则包括没有两个被否决的备选方案就不写决策、状态只用 proposed / accepted / superseded。
• 本质是文本文件，可审查、可 diff、可提交，和普通源码一样。

渐进式披露与脚本

• 会话开始时 Claude Code 只知道所有 Skill 的元数据，每个约几十个 token。
• 任务匹配描述后才加载完整 SKILL.md，被引用的附加文件更晚加载，所以团队可以放三十个 Skill 而不拖累上下文。
• description 因此是最重要的字段：它不是给人看的文档，而是代理的路由条件。“帮助处理文档”几乎不会触发，写清具体触发场景和关键词才可靠。
• Skill 里可以放脚本让代理通过 shell 执行，把确定性的子步骤从模型手里拿走，grep 能精确回答的事不该让模型猜。

和 CLAUDE.md、斜杠命令的分工

• CLAUDE.md 常驻上下文，适合技术栈、构建命令这类少量通用事实。
• 斜杠命令必须有人主动调用，前提是有人知道它存在。
• Skill 由代理根据情境自行选择。经验法则：每次会话都适用的放项目指令，只在特定情境适用的放 Skill。
• 个人 Skill 放在用户配置里，跨项目跟随开发者；项目级 Skill 放在仓库的 .claude/skills/ 下随代码走；组织级分发用来自 Git 仓库的 marketplace 插件。

三个落地案例

• 统一代码审查：十二名开发者结果不一致，有的盯格式细节，有的漏掉权限校验。Skill 固定审查顺序、严重度逻辑和输出格式，指向一份安全相关检查点文件，并带一个脚本算出相对目标分支的改动文件。生产事故的教训以 PR 形式写进 Skill，下次合并起对所有人生效。
• 架构文档：文档落后六个月，因为梳理模块边界很枯燥。Skill 规定代理如何推导现状：找入口点、评估项目引用、按分层规则检查依赖方向、把偏离标为违规。副作用往往更有价值——对比过程会暴露悄悄发生的分层破坏。
• 技术写作：术语和结构因人而异，编辑总在改同样的地方。Skill 固定目标读者、大纲网格、必须的译法、陈词滥调黑名单，再附两篇参考文本做校准，初稿就能贴合文风。

边界与推行方式

• Skill 解决的是规范问题，不是判断问题；模块该不该拆分这类真正的权衡，规则手册帮不上忙。
• 三个实际风险：过时的指令有害，会稳定产出错误结果，所以 Skill 需要负责人和定期复审；描述写得差会导致 Skill 静默失效，结果看着合理但不合标准；四十个互相重叠的 Skill 只会带来选择困难。
• 推行建议：从两三个每天都要做的工作流开始，拿现有提示词当素材，在仓库里审查 Skill，并抽查结果是否真的符合规则。

今天就能做

• 找出你今天重复解释最多的那个工作流，把它写成第一个 SKILL.md，description 里写清具体触发场景和关键词。
• 把 Skill 提交进仓库的 .claude/skills/，走 PR 审查，并指定一名负责人定期复审过时内容。
• 把能用 grep 或脚本精确完成的子步骤从指令里拆出来，做成 Skill 附带的脚本。