1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词是在翻 Claude Code 的插件目录结构时。当时我的第一反应是这不就是把 prompt 拆成文件吗但真正动手把一套团队内部的编码规范、测试流程、代码审查清单塞进 skills 目录之后我才意识到这东西的价值远不止提示词管理这么简单。agent-skills本质上是一套面向 AI coding agents 的能力封装规范。它把原本散落在对话历史、系统提示、临时粘贴的上下文里的经验固化成一个个可复用、可版本控制、可组合的 skill 单元。你可以把它理解成给 AI 编程助手准备的技能包——每个 skill 描述一件事该怎么做、什么时候触发、遵循什么约束、产出什么结果。它解决的问题很具体同一个团队里每个人用 Claude Code 写代码的风格、测试习惯、提交规范都不一样AI 每次都要重新教一遍。有了 agent-skills这些规则变成仓库里的文件AI 在合适的时机自动加载新人拉下代码就自带全套规范。适合谁看三类人最该关注一是已经在用 Claude Code、Cursor 这类 AI coding agent 的开发者想让输出更稳定二是团队技术负责人想把工程规范沉淀下来三是想理解skills CLI这类工具链设计思路的工程师。哪怕你只是刚装完 Claude Code 在摸索阶段读完也能少走不少弯路。下面我按设计思路 → 核心细节 → 实操落地 → 踩坑排查的顺序把这段时间折腾 agent-skills 的经验完整摊开讲。2. 整体设计思路为什么是技能而不是提示词2.1 从提示词工程到技能工程的范式转变早期用 AI 写代码大家的做法是把要求一股脑塞进对话你要遵循 PEP8、要写单元测试、提交信息用 conventional commits……这套做法在单次会话里能用但一旦换会话、换人、换项目全部归零。这就是典型的提示词工程困境上下文是易失的经验无法沉淀。agent-skills 的设计思路是把提示词升级成技能。区别在哪提示词是一次性的指令技能是带触发条件的、可复用的能力单元。一个 skill 通常包含三部分信息元数据名称、描述、触发场景、指令正文具体怎么做、可选的辅助资源脚本、模板、参考文档。这个设计背后有个很关键的判断AI agent 的上下文窗口是稀缺资源。如果把所有规范都塞进系统提示会挤占真正用于理解代码的空间。而 skills 采用按需加载——只有当任务匹配某个 skill 的描述时才把它的完整内容注入上下文。这就像给 AI 装了一个技能书架平时只看到书脊需要时才抽出来翻。2.2 目录结构与加载机制的设计考量一个典型的 agent-skills 目录长这样.claude/skills/ ├── test-driven-development/ │ ├── SKILL.md │ └── references/ │ └── tdd-checklist.md ├── code-review/ │ └── SKILL.md └── commit-convention/ ├── SKILL.md └── scripts/ └── validate-commit.sh每个 skill 一个目录核心是SKILL.md。这个文件用 YAML frontmatter 声明元数据正文写指令。为什么用 Markdown 而不是 JSON 或 YAML因为指令正文是给模型读的自然语言Markdown 的标题、列表、代码块结构对模型理解层级关系最友好同时人也能直接读。元数据里最关键的是description字段。它决定了这个 skill 什么时候被激活。我踩过的第一个坑就是 description 写得太笼统比如写帮助写代码结果任何编码任务都会触发它反而干扰了其他更专门的 skill。后来改成当用户要求编写新功能或修复 bug 时指导先写失败测试再实现触发就精准多了。2.3 与 Claude Code 生态的契合点Claude Code 作为当前主流的 AI coding agent 之一它的 skills 机制有几个设计上的巧思值得说。一是渐进式披露skill 的元数据始终可见正文按需加载深层引用文件再按需读取形成三层信息密度。二是文件系统即接口不需要额外的注册中心或数据库目录结构本身就是配置。三是可组合性多个 skill 可以在一次任务中协同比如 TDD skill 和 commit skill 先后触发。这种设计让 agent-skills 天然适合放进 Git 仓库。团队可以像管理代码一样管理技能review、版本号、changelog 一应俱全。我现在的做法是把.claude/skills/直接提交到项目根目录配合 CI 检查 skill 文件的格式合法性。3. 核心细节解析一个高质量 skill 的解剖3.1 SKILL.md 的元数据字段怎么填先看一个我实际在用的 TDD skill 的头部--- name: test-driven-development description: 当需要实现新功能、修复 bug 或重构代码时使用。强制先编写失败的测试再编写最小实现使其通过最后重构。适用于所有生产代码变更。 ---name用 kebab-case和目录名保持一致方便引用。description是重中之重我的经验是遵循触发场景 核心动作 适用范围三段式。触发场景写清楚什么时候用核心动作写做什么适用范围写边界在哪。有个细节很多人忽略description 里要包含用户可能说的自然语言关键词。比如用户说帮我加个登录功能description 里如果有实现新功能这样的表述匹配度就高。这本质上是在做轻量的语义检索优化。3.2 指令正文的写法给模型看的操作手册正文部分我总结出一个四段式结构实测下来模型执行最稳定第一段是目标声明一句话说清这个 skill 要达成什么。第二段是步骤序列用有序列表写清楚先做什么后做什么。第三段是约束与禁忌明确哪些事绝对不能做。第四段是产出格式规定最终交付物长什么样。以 TDD skill 为例正文核心是这样组织的## 目标 确保所有代码变更都有测试覆盖且测试先于实现。 ## 步骤 1. 理解需求识别需要测试的行为边界 2. 编写一个会失败的测试运行并确认它确实失败 3. 编写最小实现让测试通过不追求优雅 4. 运行全部测试确认无回归 5. 重构代码保持测试绿灯 ## 约束 - 禁止在测试失败前编写实现代码 - 禁止一次编写多个测试 - 测试命名必须描述行为而非实现细节 ## 产出 - 测试文件路径与实现文件路径的对应关系 - 每个测试的失败→通过记录这里有个反直觉的点约束部分比步骤部分更重要。模型很容易抄近路比如跳过确认测试失败这一步直接写实现。把禁忌写死能显著降低这种偷懒行为。3.3 辅助资源的组织references 与 scriptsskill 目录下的references/和scripts/是两个容易被浪费的目录。我的用法是references 放查阅型内容scripts 放执行型内容。references 适合放那些篇幅长、但不是每次都需要全文加载的资料。比如一份完整的代码审查清单、某个框架的最佳实践汇总。在 SKILL.md 里用相对路径引用模型需要时会主动读取。scripts 则放可执行的校验脚本。比如我写过一个validate-commit.sh检查提交信息是否符合 conventional commits 格式。skill 正文里指示模型在提交前运行这个脚本把规范检查从靠模型自觉变成靠脚本强制。提示scripts 里的脚本要保证幂等和快速。我见过有人放了个跑全量测试的脚本结果每次提交都卡几分钟体验极差。校验类脚本控制在秒级完成。3.4 触发精度调优避免 skill 打架当 skills 数量超过五六个之后触发冲突就成了主要矛盾。典型症状是你只想让它写个测试结果 commit skill 和 review skill 也一起被激活输出一堆无关内容。我的调优方法是给每个 skill 划定专属动词。比如 TDD skill 绑定实现、修复、重构review skill 绑定审查、检查、评估commit skill 绑定提交、commit。description 里明确写出这些动词让模型在匹配时有清晰的信号。另一个技巧是设置优先级提示。在 description 末尾加一句此技能优先于通用的编码技能能在冲突时引导模型选择更专门的 skill。这不是硬性机制但实测对触发选择有明显影响。4. 实操落地从零搭一套 agent-skills4.1 环境准备与 skills CLI 的定位先说环境。Claude Code 的安装方式因平台而异Mac 和 Ubuntu 上流程略有差别核心是拿到 CLI 工具并完成账号配置。这里不展开安装细节重点说 skills 相关的部分。skills CLI这类工具的价值在于批量管理。当你有十几个 skill 时手动创建目录、检查格式、维护索引会很痛苦。CLI 通常提供init初始化 skill 模板、list列出所有 skill、validate校验格式这几个命令。我建议即使只有两三个 skill也用它来初始化因为模板里的 frontmatter 格式是经过验证的能避免手写 YAML 时的缩进错误。初始化一个 skill 的典型流程# 在项目根目录初始化 skills 目录 skills init # 创建一个新 skill skills create test-driven-development # 校验所有 skill 格式 skills validate注意不同版本的 CLI 命令可能有差异以你本地skills --help的输出为准。我遇到过命令改名的情况别死记硬背。4.2 编写第一个 skill以 TDD 为例的完整过程假设我们要落地一个 TDD skill。第一步是明确它的边界——它只管怎么写代码不管怎么提交。边界清晰是 skill 可维护的前提。第二步写 description。我反复打磨后的版本是当用户要求实现新功能、修复缺陷或重构现有代码时使用。强制采用测试先行的开发流程先写失败测试再写最小实现最后重构。不适用于纯配置修改、文档更新和依赖升级。最后那句不适用于很关键它主动排除了不该触发的场景减少误触发。第三步写正文。除了前面说的四段式我还加了一个示例区块放一段真实的失败测试 → 实现 → 通过的代码片段。模型对示例的模仿能力很强给一个好例子胜过写三段抽象描述。第四步是测试。找个真实的小需求让 Claude Code 在 skill 生效的情况下做一遍观察它是否真的先写测试。我第一次测试时发现它跳过了确认测试失败这一步于是在约束里加粗强调了这条第二次就正常了。skill 是需要迭代的别指望一次写对。4.3 多 skill 协同一次完整的功能开发流程单个 skill 好用但真正的威力在协同。我现在的项目里一次完整的功能开发会依次触发三个 skill阶段触发 skill核心动作产出编码test-driven-development先测试后实现测试文件 实现文件审查code-review检查边界、命名、复杂度审查意见清单提交commit-convention格式化提交信息规范化的 commit关键在于阶段之间的衔接。TDD skill 的产出格式里我规定了测试文件路径与实现文件路径的对应关系这样 review skill 触发时能直接拿到这个映射不用重新推断。commit skill 则依赖 review 通过作为前置条件。这种协同不是自动的需要你在 skill 正文里写清楚完成本技能后建议进入下一阶段。模型会据此判断是否继续。我试过完全不写衔接提示结果模型做完 TDD 就停了不会主动进入审查。加上衔接语句后流程顺畅很多。4.4 版本管理与团队协作agent-skills 最大的价值在团队场景。我的做法是把.claude/skills/提交到主仓库和代码同生命周期每个 skill 目录下维护一个CHANGELOG.md记录规则变更在 PR 模板里加一条检查项本次变更是否影响现有 skill定期比如每月review 一次 skill 内容清理过时规则有个坑要提醒skill 的变更会影响所有人的 AI 输出所以它应该走和代码一样的 review 流程。我见过有人直接往主分支推了个 skill 修改结果全组的 AI 突然开始用一套新的命名规范搞得大家一脸懵。把 skill 当代码管这个意识很重要。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么办这是最高频的问题。排查思路按顺序来先看 description 是否包含用户实际会说的词。我遇到过一次用户说帮我优化下这段逻辑但 skill 的 description 里只有重构没写优化结果没触发。补上同义词就好了。再看是否有其他 skill 抢了触发。用skills list看当前所有 skill 的 description找出语义重叠的给它们划定更清晰的边界。最后看 skill 数量。超过十个之后触发精度会下降。这时候要考虑合并同类项或者用目录分组比如skills/testing/、skills/review/来降低干扰。5.2 模型不遵守 skill 里的约束约束不被遵守通常有三个原因。一是约束写得太抽象比如写高质量的测试模型不知道什么叫高质量。改成每个测试只断言一个行为测试名用 should_when 格式就具体多了。二是约束和步骤混在一起模型读的时候没注意到。我的做法是把约束单独成段用加粗或引用块突出。三是约束太多模型顾此失彼。一个 skill 里的硬约束控制在五条以内超过就拆成两个 skill。5.3 常见问题速查表症状可能原因排查动作skill 完全不触发description 缺关键词补充用户常用表述多个 skill 同时触发边界重叠划定专属动词加优先级提示约束被忽略表述太抽象改成可验证的具体规则输出格式不稳定缺产出格式定义在正文末尾明确产出结构加载慢references 文件过大拆分文件按需引用团队规则不同步skill 未纳入版本控制提交到仓库走 review 流程5.4 几个我踩过的坑第一个坑是在 skill 里写死具体技术栈。我早期写了个 skill 里全是 React 的写法结果换个 Vue 项目就完全不能用。后来改成把技术栈相关的部分抽到 references 里SKILL.md 只写通用流程复用性大大提升。第二个坑是description 写成了功能说明书。比如写这个 skill 用于管理测试流程包含测试编写、运行、断言等能力这种描述模型很难判断何时触发。description 要写什么时候用不是这是什么。第三个坑是忽略 skill 的加载顺序。当多个 skill 同时激活时它们的注入顺序会影响模型的理解。我现在的做法是在 description 里用优先于这样的措辞显式声明优先级比依赖默认顺序可靠。提示每次修改 skill 后用同一个测试用例跑一遍对比修改前后的输出差异。这是验证 skill 改动是否有效的最直接方法比读文档靠谱得多。6. 关于 agent-skills 的一些延伸思考把 agent-skills 用熟之后我对AI 辅助开发这件事的理解有了变化。以前觉得重点是模型能力现在觉得工程化的封装能力同样关键。同一个模型配上精心设计的 skills产出质量能差出一个档次。这套思路其实可以迁移到很多场景。比如把团队的代码审查经验封装成 skill把新人 onboarding 的常见问题封装成 skill把某个复杂模块的修改注意事项封装成 skill。本质上agent-skills 是把隐性知识显性化的一个载体。我最近在尝试的一个方向是让 skill 之间形成依赖图比如 review skill 依赖 TDD skill 的产出格式commit skill 依赖 review 的通过状态。这样整个开发流程就像一条流水线每个环节都有明确的输入输出契约。这个方向还在摸索等有成熟经验了再单独写一篇。如果你刚开始接触我的建议是从一个小 skill 开始别贪多。先写一个你最常重复交代的规则跑通触发、执行、产出这条链路再逐步扩展。skills 的价值在于积累不在于一次写全。