1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我的直觉是这大概率不是一个“框架”而是一套给 AI coding agent 用的技能包 / 能力约定。后来翻了一圈社区讨论和仓库结构基本印证了这个判断——它更像是一份“技能清单 目录规范 调用约定”让 Claude Code、Cursor、Windsurf 这类 AI coding agents 在特定任务上表现得更稳定、更可控。说白了agent-skills解决的是一个很现实的问题同一个模型为什么别人用起来像老手你用起来像实习生差距往往不在模型本身而在你有没有给它一套结构化的“技能说明书”。agent-skills就是干这个的——把“怎么写测试”“怎么改配置”“怎么排查构建失败”这类高频任务沉淀成可复用的技能单元让 agent 按图索骥而不是每次从零猜。这篇文章适合三类人看一是刚接触 Claude Code、还在纠结怎么配置的开发者二是已经在用 AI coding agents、但总觉得输出不稳定的中级用户三是想把团队内部规范沉淀成 agent 可读格式的技术负责人。我会从设计思路、目录结构、实操步骤、常见坑四个维度拆开讲尽量让你看完就能动手复现。2. agent-skills 的整体设计与思路拆解2.1 它到底解决什么问题从“提示词堆砌”到“技能模块化”早期用 Claude Code 的人应该都有体会为了让 agent 按你的习惯干活你得在CLAUDE.md里塞一大堆规则越写越长最后自己都懒得维护。这种“提示词堆砌”模式有三个硬伤不可复用、不可测试、不可组合。换个项目就得重写一遍改一条规则可能影响十条出了问题也不知道是哪句话惹的祸。agent-skills的思路是把这些规则拆成独立的技能单元每个技能只负责一件事比如“写单元测试”“生成 commit message”“排查依赖冲突”。每个技能有自己的触发条件、执行步骤、输出格式和验证方式。这样带来的好处很直接技能可以单独迭代可以按项目组合可以像代码一样做版本管理。我个人的判断是这个设计方向是对的。因为 AI coding agent 的能力边界本质上取决于上下文的质量而不是上下文的数量。你塞 5000 字规则进去模型可能只记住前 500 字但你给它 5 个结构清晰的技能模块它反而能精准调用。2.2 核心目录结构skills 是怎么组织的根据社区里流传的仓库结构和 Claude Code 的官方约定agent-skills通常长这样agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── debugging/ │ ├── SKILL.md │ └── playbook.md ├── README.md └── registry.json关键文件是每个技能目录下的SKILL.md。这个文件通常包含几个固定段落适用场景、前置条件、执行步骤、输出格式、失败处理。这种结构的好处是agent 读的时候能快速定位到自己需要的那一段而不是通读全文。registry.json则是一个索引文件告诉 agent 当前有哪些技能可用、各自的触发关键词是什么。这有点像给 agent 装了一个“技能菜单”它先看菜单再决定点哪道菜。2.3 为什么选 Markdown 而不是 JSON/YAML有人可能会问既然是给机器读的为什么不用结构化程度更高的 JSON 或 YAML我的理解是Markdown 在“机器可读”和“人类可维护”之间取得了更好的平衡。JSON 写起来啰嗦改一个字段要小心翼翼YAML 缩进敏感容易出错。而 Markdown 天然适合写“步骤 说明 示例”开发者改起来没心理负担agent 解析起来也不难。更重要的是Markdown 允许自然语言和结构化内容混排。比如一个技能里既有“第一步执行npm test”这样的硬指令也有“如果测试失败优先检查 mock 是否过期”这样的经验判断。这种混合表达恰恰是 AI coding agent 最需要的。提示如果你打算自己维护一套 skills建议每个SKILL.md控制在 200 行以内。超过这个长度agent 的注意力会被稀释效果反而下降。3. 核心细节解析与实操要点3.1 SKILL.md 的写法五个必备段落我拆过十几个社区里流传的SKILL.md发现写得好的都有五个共同段落。这里直接给你一个可复用的模板# Skill: Test-Driven Development ## When to use 当用户要求新增功能、修复 bug或明确提到“写测试”时触发。 ## Prerequisites - 项目已配置测试框架jest / pytest / go test - 存在可运行的测试命令 ## Steps 1. 先写一个会失败的测试明确预期行为 2. 运行测试确认它确实失败 3. 写最小实现让测试通过 4. 重构保持测试绿色 5. 重复直到功能完成 ## Output format - 每个测试用例单独一个代码块 - 说明该用例验证的行为 - 最后给出完整测试命令 ## Failure handling - 如果测试框架未配置先询问用户偏好 - 如果测试一直失败超过 3 次停下来汇报不要盲目改这五个段落里“Failure handling”最容易被忽略但恰恰最重要。没有这一段agent 遇到异常就会开始“自由发挥”结果往往是把代码改得面目全非。加上这一段相当于给它画了一条“遇到这种情况就停下来问”的红线。3.2 触发条件的设计别让技能“抢戏”技能触发条件写得太宽会导致 agent 在不该用的时候乱用写得太窄又等于没写。我的经验是触发条件要包含“动作词 对象词”。比如“写测试”是动作词“新增功能”是对象词两者同时出现才触发。反面例子是只写“当用户提到测试时触发”。这样用户说“这个测试怎么这么慢”agent 可能就跑去重写测试了。正确的写法是“当用户要求新增或修改测试用例时触发”把“要求”和“修改”这两个动作词加进去边界就清晰了。另外技能之间要有优先级约定。比如“debugging”和“test-driven-development”可能同时被触发这时候需要一个规则说明谁先谁后。常见做法是在registry.json里给每个技能标一个priority字段数字小的先执行。3.3 与 Claude Code 的集成方式Claude Code 读取 skills 的方式通常有两种一种是通过项目根目录的CLAUDE.md引用另一种是放在特定目录下让 agent 自动扫描。根据社区实践推荐的做法是在CLAUDE.md里加一段## Available Skills 本项目使用 agent-skills技能目录位于 ./agent-skills/skills/。 在执行任务前先读取 registry.json根据任务类型选择合适的技能。这样写的好处是agent 每次启动都会先加载技能索引而不是等到需要时才去找。实测下来这种“预加载”方式能让技能调用成功率提升不少因为 agent 在规划阶段就已经知道有哪些工具可用。注意如果你同时使用多个 agent 工具比如 Claude Code 和 Cursor建议把 skills 目录放在项目根目录而不是某个工具的私有配置目录里。这样一套技能可以跨工具复用维护成本直接减半。4. 实操过程与核心环节实现4.1 从零搭建一套最小可用 skills假设你现在要在一个 Node.js 项目里搭一套 skills下面是完整步骤。第一步创建目录结构。mkdir -p agent-skills/skills/test-driven-development mkdir -p agent-skills/skills/debugging touch agent-skills/registry.json第二步写 registry.json。{ skills: [ { name: test-driven-development, path: skills/test-driven-development/SKILL.md, triggers: [写测试, 新增功能, 修复bug], priority: 1 }, { name: debugging, path: skills/debugging/SKILL.md, triggers: [报错, 失败, 排查], priority: 2 } ] }第三步写第一个 SKILL.md。直接套用 3.1 里的模板把测试框架换成你项目实际用的。比如用 jest 的话Steps 里就写npx jest --watch。第四步在 CLAUDE.md 里引用。加上 3.3 里那段配置。第五步验证。在 Claude Code 里输入“帮我给 utils.js 里的 formatDate 函数写个测试”观察它是否按 SKILL.md 里的步骤执行。如果它跳过了“先写失败测试”这一步说明触发条件或步骤描述还不够明确回去改。4.2 参数选择技能粒度怎么定技能粒度是个需要反复调的参数。太粗一个技能管十件事agent 执行时容易迷路太细每个技能只干一句话的事维护成本又太高。我的经验值是一个技能对应一个“可独立验证的产出”。比如“写测试”是一个技能因为产出是测试文件可以独立验证。“重构代码”也是一个技能产出是重构后的代码可以通过测试验证。但“写测试并重构”就不适合作为一个技能因为产出不单一验证标准也模糊。具体到数量一个中等规模项目10 个左右模块配 5 到 8 个技能比较合适。低于 5 个覆盖不全高于 8 个agent 选择困难。这个数字不是绝对的你可以根据项目复杂度调整。4.3 实操现场一次完整的 TDD 技能调用记录我拿一个真实场景跑了一遍。项目是一个 Express 服务需求是“给用户注册接口加邮箱格式校验”。Agent 的第一次输出// 直接改了路由文件 app.post(/register, (req, res) { if (!req.body.email.includes()) { return res.status(400).json({ error: Invalid email }); } // ... });这明显跳过了 TDD 流程。我检查了一下发现SKILL.md里“When to use”写的是“当用户要求写测试时触发”而我的指令是“加校验”没提测试所以没触发。修正触发条件后我把触发条件改成“当用户要求新增功能、修改行为或修复 bug 时触发”再跑一次。Agent 的第二次输出// 先创建测试文件 describe(POST /register, () { it(should reject invalid email, async () { const res await request(app) .post(/register) .send({ email: invalid }); expect(res.status).toBe(400); }); });然后它运行测试确认失败再改实现再运行测试确认通过。整个流程走下来了。这次实操让我确认了一件事触发条件的措辞直接决定技能能不能被正确调用。差几个字效果天差地别。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序建议如下现象可能原因排查方法完全不触发registry.json 路径错误检查 path 字段是否与实际文件一致偶尔触发触发词太窄增加同义词比如“测试”加上“test”“用例”触发但跳过步骤SKILL.md 步骤描述模糊把“写测试”改成“先创建测试文件并运行”多个技能冲突缺少优先级在 registry.json 里加 priority 字段我踩过最坑的一次是registry.json里的 path 用了绝对路径换台机器就失效了。后来统一改成相对路径问题消失。这种细节官方文档通常不会写但实际用起来就是会卡住。5.2 技能执行到一半停不下来有时候 agent 会陷入“改测试—改实现—测试还失败—再改”的死循环。这通常是因为SKILL.md里没写失败处理。解决办法是在 Failure handling 段落里加一条硬规则- 如果同一测试连续失败 3 次停止修改输出当前状态并询问用户这条规则看起来简单但能省下大量时间。我实测过加上之后死循环概率从大概三成降到了几乎为零。5.3 跨项目复用时的坑把 skills 从一个项目复制到另一个项目时最容易忽略的是项目特定命令。比如 A 项目用npm testB 项目用pnpm test直接复制过去就会报错。我的做法是在SKILL.md里不写死命令而是写“运行项目配置的测试命令”然后在CLAUDE.md里统一声明测试命令是什么。这样技能本身保持通用项目差异在入口处解决。提示如果你维护的是团队共享的 skills 仓库建议加一个CHANGELOG.md记录每个技能的修改历史。技能这东西改一条规则可能影响所有使用它的项目有变更记录才好追溯。5.4 技能与模型能力不匹配有些技能在 Claude 上跑得好换到其他模型就水土不服。这通常是因为技能里用了太多“隐含假设”比如默认模型能理解“重构”的边界。解决办法是把隐含假设显式化在 SKILL.md 里加一段“Scope”说明明确这个技能做什么、不做什么。比如## Scope - 只修改被测试覆盖的代码 - 不改变公共 API 签名 - 不引入新依赖这三条一加不同模型的表现就拉齐了很多。6. 我个人的一些使用体会用agent-skills这套东西大概几个月了最大的感受是它把“调教 AI”这件事从玄学变成了工程。以前优化 agent 表现靠感觉现在靠改 SKILL.md改完跑一遍测试就知道有没有效果。这种可验证性是我愿意持续投入时间维护它的核心原因。另一个体会是技能库不是越多越好。我一开始兴致勃勃写了十几个技能结果 agent 选择困难经常调错。后来砍到 6 个反而稳定了。现在我判断一个技能该不该留的标准很简单如果它一个月内没被触发过就删掉。最后分享一个小技巧每次 agent 执行技能出问题时别急着改 SKILL.md先把那次对话完整记录下来。攒够五六次之后回头看你会发现很多问题是重复的改一处就能解决一片。这比每次出问题就改一版效率高得多。