1. 从“agent-skills”说起为什么这个项目值得你花时间第一次看到agent-skills这个标题很多人会以为它又是一个“提示词合集”或者“技能包仓库”。但真正上手之后你会发现它解决的是一个更底层的问题如何让 AI coding agent 在真实项目里稳定地执行复杂任务而不是每次都靠人肉把上下文、规范、测试流程重新讲一遍。我接触 AI coding agent 这条线有一段时间了从最早的对话式补全到后来能直接读写文件、跑终端命令的 agent 形态最大的痛点从来不是“模型够不够聪明”而是“它记不记得住规矩”。你让它改一个函数它可能顺手把测试删了你让它加一个接口它可能不写边界校验你让它重构它可能把命名风格全带偏。agent-skills这类项目的核心价值就是把这些“规矩”沉淀成可复用、可版本管理、可被 agent 自动加载的技能单元。它适合谁三类人最该关注。第一类是已经在用 Claude Code、Cursor、各类 CLI agent 做日常开发的工程师你们会直接受益于技能复用带来的效率提升第二类是在团队里负责搭建 AI 辅助开发流程的技术负责人你们需要一套可落地的规范载体第三类是刚入门 AI coding agent 的新手理解 skills 的组织方式比死记某个工具的快捷键有价值得多。这篇文章我会按“设计思路 → 核心细节 → 实操落地 → 问题排查”的顺序展开中间会穿插我自己踩过的坑和实测有效的配置。全文围绕agent-skills这个主题但不会只讲概念重点放在你能直接抄作业的部分。2. 内容整体设计与思路拆解2.1 为什么是“技能”而不是“提示词”提示词prompt和技能skill最大的区别在于生命周期。提示词通常是一次性的写在对话框里用完就散了技能是持久化的它有自己的目录结构、元数据、触发条件和执行逻辑可以被 agent 在合适的时机自动检索并加载。我举个实际场景。假设你的项目要求“所有新增的 API 路由必须配套集成测试且测试文件命名遵循*.spec.ts”。如果你只靠提示词每次开新会话都得重复一遍模型还可能理解偏差。但如果你把它写成一个 skill比如api-route-with-test里面明确规定了文件路径模板、测试框架、断言风格那么 agent 在识别到“新增路由”这个意图时就会自动套用这套流程。agent-skills的设计思路本质上是把领域知识和执行规范从人的脑子里、从散落的文档里抽离成机器可读的结构化资产。这背后有一个很现实的考量AI coding agent 的能力上限往往不取决于模型本身而取决于你给它喂了多少“项目专属的上下文”。2.2 技能单元应该包含哪些要素一个合格的 skill我总结下来至少要包含四块内容缺一块都会导致 agent 执行时“跑偏”。第一块是触发描述trigger。这是给 agent 看的“什么时候该用我”。描述要具体不能写“处理代码相关任务”这种废话。好的触发描述长这样“当用户要求新增 React 组件、且项目使用 TypeScript Vitest 时触发”。关键词越精准误触发率越低。第二块是执行步骤procedure。这是技能的主体要写成 agent 能逐步执行的有序列表。每一步最好包含“做什么”和“产出什么”。比如“第一步在src/components/下创建组件文件导出为具名导出第二步在同目录创建*.test.tsx至少覆盖渲染和交互两个用例”。第三块是约束条件constraints。这是最容易被忽略但最重要的部分。约束包括禁止事项比如“不要修改package.json的依赖版本”、边界条件比如“单文件不超过 300 行”、以及必须遵守的项目规范比如“使用项目已有的logger工具不要引入新依赖”。第四块是验证方式verification。技能执行完怎么确认它做对了可以是运行测试命令、可以是 lint 检查、也可以是人工确认清单。没有验证环节的技能等于没有闭环。2.3 目录结构怎么设计才合理我试过好几种组织方式最后稳定下来的结构是这样的agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── api-route-with-test/ │ │ ├── SKILL.md │ │ └── templates/ │ └── refactor-safe/ │ ├── SKILL.md │ └── checklist.md ├── registry.json └── README.md每个技能一个独立目录核心是SKILL.md里面用固定的 frontmatter 写元数据名称、触发条件、适用技术栈正文写执行步骤和约束。examples/放正例和反例scripts/放可执行的辅助脚本templates/放代码模板。registry.json是索引文件记录所有技能的清单和版本。这个文件很关键因为 agent 在启动时只需要读这一个文件就能知道有哪些技能可用不用遍历整个目录树加载速度会快很多。注意技能目录的命名建议用 kebab-case且名称要能自解释。我见过有人用skill-01、skill-02这种命名过两周自己都忘了哪个是哪个。2.4 和 test-driven-development 的关系热搜词里出现了test-driven-development这不是巧合。TDD 是agent-skills里最典型、也最值得优先落地的一类技能。原因很简单测试是 agent 最容易验证、也最容易出错的环节。在 TDD 技能里执行流程通常是“先写失败测试 → 再写实现 → 跑测试确认通过 → 重构”。这个流程对 agent 来说有天然优势因为每一步都有明确的成功判据测试红/绿。我实测下来把 TDD 写成 skill 之后agent 擅自删测试、跳过断言、写空实现的情况明显减少。但这里有个坑TDD 技能必须明确指定测试框架和运行命令。如果你的项目用 Vitest但技能里没写清楚agent 可能默认用 Jest 的语法结果跑不起来。所以技能里的“验证方式”一定要写死具体命令比如npx vitest run --reporterverbose。3. 核心细节解析与实操要点3.1 SKILL.md 的写法从模糊到可执行很多人写 SKILL.md 容易犯一个错误写成了“说明书”而不是“操作手册”。说明书是给人看的操作手册是给 agent 执行用的。区别在于操作手册的每一步都应该是可判定完成的。我拿一个真实例子对比。模糊写法“优化代码结构提高可读性。”这种描述 agent 没法执行因为“可读性”没有量化标准。可执行写法“将utils.ts中超过 50 行的函数拆分为多个小函数每个函数只做一件事拆分后运行npm run lint确认无新增警告。”再比如约束条件也要写成可判定的。模糊写法“注意代码风格。”可执行写法“使用项目根目录.prettierrc的配置缩进 2 空格字符串用单引号行尾不加分号。”我自己的经验是写完一个 SKILL.md 之后可以做一个“盲测”把技能内容给一个不了解项目的人看问他能不能照着做出来。如果他有疑问说明技能里还有模糊地带需要补细节。3.2 触发条件的精准度控制触发条件写得太宽agent 会频繁误触发干扰正常开发写得太窄又会在该用的时候用不上。这个平衡点怎么找我的做法是用“技术栈 动作 对象”三要素来限定。比如技术栈React TypeScript Vitest动作新增组件对象带交互的表单组件组合起来就是“当在 React TypeScript Vitest 项目中新增带交互的表单组件时触发”。这样既不会在写纯展示组件时误触发也不会在写表单时漏掉。另外触发条件里可以加“排除项”。比如某个技能只适用于新文件创建不适用于修改已有文件那就明确写“仅当目标文件不存在时触发”。这个细节能省掉很多麻烦。实操心得触发条件里的技术栈关键词建议和package.json里的依赖名保持一致。比如项目里装的是vitest就不要在技能里写“测试框架”直接写vitest这样 agent 匹配时更准。3.3 技能之间的依赖与组合真实项目里一个任务往往需要多个技能配合。比如“新增一个 API 路由”可能涉及api-route-with-test路由和测试、error-handling错误处理规范、logging日志规范三个技能。这时候有两种处理方式。一种是组合技能把多个技能串成一个大的执行流程另一种是技能引用在技能 A 里声明“本技能依赖技能 B执行前先加载 B”。我倾向于后者因为组合技能一旦某个环节变了整个大技能都要改维护成本高。而技能引用是松耦合的改 B 不影响 A 的结构。具体做法是在 SKILL.md 的 frontmatter 里加一个depends_on字段列出依赖的技能名。不过要注意依赖链不能太长。我建议最多两层超过两层就该考虑是不是该拆成独立技能了。依赖太深agent 加载时容易乱排查问题也麻烦。3.4 版本管理与团队协作agent-skills既然是资产就得有版本管理。我的做法是给每个技能在 frontmatter 里加version字段遵循语义化版本。技能内容有破坏性变更时升主版本新增步骤升次版本修正错别字升补丁版本。团队协作方面技能库应该和代码库一样走 PR 流程。谁改了技能要说明改了什么、为什么改、影响哪些项目。我见过团队把技能库放在共享盘里谁都能直接改结果同一个技能在不同人手里行为不一致排查起来非常痛苦。另外技能库最好和项目代码放在同一个仓库里或者至少用 git submodule 关联。这样技能变更和代码变更能一起 review不会出现“技能更新了但项目没跟上”的情况。4. 实操过程与核心环节实现4.1 从零搭建一个技能库假设你现在要在一个已有的 TypeScript 项目里搭建agent-skills下面是完整的操作流程。第一步创建目录结构。在项目根目录执行mkdir -p agent-skills/skills touch agent-skills/registry.json touch agent-skills/README.md第二步编写第一个技能。以 TDD 为例创建agent-skills/skills/test-driven-development/SKILL.md--- name: test-driven-development version: 1.0.0 trigger: 当用户要求新增功能或修复 bug且项目使用 Vitest 作为测试框架时触发 depends_on: [] --- # TDD 执行流程 ## 步骤 1. 在 src/ 下找到或创建对应的测试文件命名遵循 *.test.ts 2. 编写至少一个失败测试覆盖目标行为 3. 运行 npx vitest run 测试文件路径确认测试失败 4. 编写最小实现使测试通过 5. 再次运行测试确认通过 6. 运行 npx vitest run 确认全量测试无回归 ## 约束 - 禁止在测试通过前编写超出测试范围的实现代码 - 禁止删除或跳过已有测试 - 测试文件必须包含至少一个断言 ## 验证 - 所有测试通过 - 无新增 lint 警告第三步生成索引。在registry.json里登记{ skills: [ { name: test-driven-development, version: 1.0.0, path: skills/test-driven-development/SKILL.md, trigger: 新增功能或修复 bugVitest 项目 } ] }第四步接入 agent。不同工具的接入方式不一样。以 Claude Code 为例可以在项目根目录的配置里指定技能库路径agent 启动时会自动读取registry.json。如果是自己写的 CLI agent就在启动脚本里加一段加载逻辑读取 registry 并注入到系统提示里。4.2 参数选择技能粒度怎么定技能粒度是个需要反复调优的参数。太粗一个技能管太多事agent 执行时容易顾此失彼太细技能数量爆炸加载和维护都累。我的经验值是一个技能对应一个“可独立验证的交付物”。比如“新增 API 路由”是一个交付物“写单元测试”也是一个交付物但“优化代码”不是因为它没有明确的交付边界。具体判断标准有三条判断维度适合独立成技能适合合并进其他技能有独立验证方式是否可跨项目复用是否步骤数在 3-8 步之间是否太少或太多步骤数少于 3 步的通常不值得单独成技能合并到相关技能里更合适。超过 8 步的建议拆成两个技能用依赖关系串联。4.3 实测记录一个技能从编写到生效我拿一个真实项目做过完整测试。项目是一个 Next.js 应用用 Vitest Testing Library。我写了一个component-with-test技能要求新增组件时必须配套测试。编写阶段花了大约 20 分钟主要是把项目里的组件规范命名、导出方式、样式方案整理成可执行步骤。接入 agent 后我让它“新增一个用户卡片组件”。第一次执行agent 创建了UserCard.tsx和UserCard.test.tsx但测试文件里只写了一个渲染断言没有覆盖 props 传递。我检查技能内容发现约束里没写“测试需覆盖所有 props”。补上这条约束后第二次执行就正常了。这个案例说明一个问题技能不是一次写完就完事的它需要在实际执行中迭代。我建议每执行 3-5 次就回顾一下技能内容把新发现的边界情况补进去。4.4 与 CLI 工具的配合热搜词里提到了skills CLI这类工具的作用是让技能库的管理更自动化。常见功能包括初始化技能库、校验 SKILL.md 格式、生成 registry、检查技能依赖是否有环。我自己常用的几个命令模式# 校验所有技能文件的 frontmatter 是否完整 skills validate ./agent-skills # 根据 skills 目录重新生成 registry.json skills build-registry ./agent-skills # 检查技能依赖是否有循环 skills check-deps ./agent-skills这些命令建议加到 CI 里每次技能库有变更就自动跑一遍。我踩过的坑是有人改了技能名但忘了更新 registry导致 agent 加载时找不到技能排查了半天才发现是索引没同步。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。agent 该用技能的时候没用通常有三个原因。原因一触发条件太窄。比如技能里写的是“当用户说‘新增组件’时触发”但用户实际说的是“帮我写个卡片”。解决办法是把触发条件写成意图描述而不是关键词匹配。可以写“当用户要求创建新的 UI 组件时触发”覆盖面更广。原因二registry 没更新。新增技能后忘了重新生成索引agent 读不到。排查方法是直接看 registry.json 里有没有这个技能。原因三技能加载顺序问题。如果多个技能触发条件重叠agent 可能选了另一个。这时候需要调整触发条件的优先级或者在技能里加priority字段。5.2 技能执行到一半卡住这种情况通常是某一步的指令不够明确agent 不知道该做什么。比如“运行测试”这一步如果没写具体命令agent 可能尝试npm test但项目实际用的是npx vitest结果报错卡住。排查技巧把技能里的每一步都当成“给新人的指令”来检查。如果新人看了会问“具体怎么操作”那这一步就需要补细节。我自己的标准是每一步都要包含具体命令或具体文件路径。5.3 技能之间冲突两个技能对同一件事有不同要求agent 执行时会矛盾。比如技能 A 要求“组件用默认导出”技能 B 要求“组件用具名导出”。解决办法是在技能库层面做一次全局审查把所有技能里的约束条件列出来找出冲突项。冲突的解决原则是项目级规范优先于通用规范。如果项目本身要求具名导出那所有技能都得遵守不能有例外。下面是我整理的一份常见问题速查表问题现象可能原因排查动作解决方式技能不触发触发条件太窄检查 trigger 字段改为意图描述技能不触发registry 未更新查看 registry.json重新生成索引执行卡住步骤缺具体命令逐步检查 SKILL.md补全命令和路径执行结果不符预期约束条件缺失对比预期与实际补充约束条款技能冲突约束矛盾全局审查约束统一为项目规范加载慢技能数量过多统计技能总数合并低复用技能5.4 独家避坑技巧说几个文档里不会写、但实际很管用的技巧。技巧一给技能加“反例”。在examples/目录里放一个bad-example.md写明“不要这样做”。agent 对反例的敏感度往往比正例高看到反例后会主动避开。技巧二技能描述里加“完成标志”。比如“当测试文件创建完成且测试通过时本技能执行结束”。这能帮 agent 判断什么时候该停避免过度执行。技巧三定期做“技能体检”。每季度过一遍技能库把三个月内没被触发过的技能标记出来评估是删除还是修改触发条件。我见过技能库膨胀到上百个技能结果 agent 加载慢、误触发多反而拖累效率。技巧四技能命名加前缀。如果技能库很大建议按领域加前缀比如fe-前端、be-后端、infra-基础设施。这样在 registry 里排序和检索都方便。6. 技能库的扩展方向与个人体会agent-skills这套东西跑通之后扩展方向其实很多。我目前在做的一件事是把技能和项目的 CI 流程打通技能执行完后自动触发对应的 CI 检查检查不通过就把结果反馈给 agent让它自己修。这个闭环一旦建立agent 的自主性会明显提升。另一个方向是技能的市场化。团队之间可以共享技能库比如前端团队维护一套 UI 相关技能后端团队维护一套 API 相关技能通过 registry 的source字段引用远程技能。这样不用每个项目都从零写技能。最后分享一个我自己的体会技能库的质量取决于你对项目规范的理解深度。如果你自己都说不清楚“什么样的代码是好代码”那写出来的技能也是模糊的。所以搭建技能库的过程其实也是倒逼团队把隐性规范显性化的过程。这件事的价值远不止让 agent 好用一点。