1. 从agent-skills说起为什么这个项目值得单独聊第一次看到agent-skills这个标题我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套插件化的能力说明书让 Claude Code、Cursor、Windsurf 这类 AI 编程代理在特定任务上表现得更像一位有经验的工程师而不是一个只会补全代码的自动机。我接触 AI coding agents 有一段时间了从最早的代码补全到后来的对话式改代码再到现在能自己跑终端、读文件、写测试、提交 commit 的代理式工作流。这个演进过程中最大的痛点其实不是模型不够聪明而是模型不知道在这个项目里应该怎么做。比如同样是写一个 React 组件有的团队要求必须写 Storybook有的团队要求必须配单元测试有的团队连命名规范都不一样。这些隐性知识以前只能靠人肉 review 来兜底而agent-skills这类项目的核心价值就是把这些隐性知识显式化、结构化变成 agent 可以直接读取和执行的技能定义。所以这篇文章我想聊的不是agent-skills 是什么这种百科式介绍而是如果你手上有一个类似 agent-skills 的项目或者你想给自己的团队搭一套 agent 技能体系应该怎么设计、怎么落地、怎么避坑。内容会覆盖技能的组织结构、CLI 的设计思路、和 Claude Code 这类工具的集成方式、TDD 工作流怎么嵌进去以及我在实操中踩过的那些坑。适合已经用过 Claude Code 或者类似工具、想进一步把 agent 能力工程化的同学也适合刚入门想搞清楚skills CLI 到底解决什么问题的朋友。2. agent-skills 的整体设计与思路拆解2.1 为什么不是写个 prompt 就完事很多人第一反应是技能不就是一段 prompt 吗我写个 markdown 文件里面写清楚你要先写测试再写实现然后让 agent 读一下不就行了这个思路在小规模场景下确实能用但一旦技能数量超过十个、团队超过三个人就会立刻崩掉。原因有三个第一prompt 是扁平的技能是有层级的。一个写 React 组件的技能可能依赖项目代码规范、测试框架约定、组件目录结构这三个基础技能。如果全靠 prompt 拼接每次都要手动组装维护成本极高。第二prompt 没有版本和依赖管理。技能会迭代今天要求用 Jest明天换成 Vitest如果没有版本控制agent 读到的可能是过期的技能定义。第三prompt 无法被程序化调用。skills CLI 存在的意义就是让技能可以被list、install、run、validate像 npm 包一样被管理。这是从文档到工具的关键跨越。所以agent-skills这类项目的设计核心我总结成一句话把 agent 的能力从临时对话变成可复用、可组合、可版本化的资产。2.2 技能的三层结构元数据、指令、验证我在设计自己的技能包时最终收敛到一个三层结构这里分享出来供参考元数据层metadata技能名、版本、适用场景、依赖的其他技能、触发条件。这一层是给 CLI 和 agent 的路由系统看的决定什么时候加载这个技能。指令层instructions具体的操作步骤、代码规范、注意事项。这一层是给模型看的自然语言内容但要求写得像 SOP 而不是散文。验证层validation怎么判断技能被执行成功了。比如测试必须全部通过、lint 不能有 error、生成的组件必须包含 props 类型定义。这一层是给自动化流程看的也是 TDD 能嵌进来的关键。这个三层结构的好处是职责分离。元数据变了不影响指令指令变了不影响验证逻辑。我见过太多项目把这三样东西混在一个 markdown 文件里结果改一个测试框架要动五个地方。2.3 和 Claude Code 的关系宿主与插件Claude Code 本身是一个 agent 运行时它能读文件、跑命令、改代码。但它默认不知道你团队的规范。agent-skills扮演的角色就是给这个运行时注入领域知识。具体来说Claude Code 在启动时会读取项目根目录下的配置文件比如CLAUDE.md这个文件里可以引用技能包。当 agent 遇到特定任务时它会根据元数据里的触发条件去加载对应的技能指令。这个过程有点像 IDE 的 language server平时不占资源需要时才激活。我实测下来这种按需加载的设计比把所有规范塞进一个巨大的 system prompt要稳得多。后者会导致上下文爆炸模型注意力被稀释反而容易忽略关键指令。2.4 方案选型为什么用 CLI 而不是纯配置文件有人会问既然技能最终是给 agent 读的为什么不直接放一堆 markdown 文件让 agent 自己去找答案是可发现性和可组合性。纯文件方案下agent 需要遍历目录、猜测哪个文件相关这个过程既慢又不准。而 CLI 提供了明确的接口skills list # 列出所有可用技能 skills install name # 安装某个技能到当前项目 skills run name # 执行某个技能 skills validate # 验证技能定义是否合法这套接口让技能从一堆文档变成了一个有 API 的系统。更重要的是CLI 可以在安装时做依赖解析、版本检查、冲突检测这些是纯文件方案做不到的。3. 核心细节解析与实操要点3.1 技能定义文件长什么样一个典型的技能定义我建议用 YAML frontmatter Markdown body 的格式。这样既能被程序解析又能被人阅读。举个例子--- name: react-component-with-test version: 1.2.0 triggers: - 创建 React 组件 - 新建组件 depends_on: - project-code-style - testing-convention validation: - command: npm test -- --testPathPattern{{component}} expect: exit_code 0 - command: npx eslint {{component_path}} expect: no_errors --- ## 操作步骤 1. 在 src/components/ 下创建组件目录目录名用 PascalCase。 2. 创建 index.tsx导出函数式组件必须显式声明 props 类型。 3. 创建 index.test.tsx至少覆盖三个场景正常渲染、边界 props、事件回调。 4. 运行验证命令确保测试和 lint 都通过。这里有几个细节值得展开triggers 的写法。不要写太宽泛的词比如组件否则 agent 在任何涉及组件的对话里都会加载这个技能浪费上下文。我一般要求 triggers 至少包含一个动词明确是创建还是重构还是审查。depends_on 的作用。它让技能可以复用。project-code-style里定义了命名规范、import 顺序、注释风格所有涉及写代码的技能都依赖它。这样改规范只需要改一个地方。validation 的 command 模板。{{component}}这种占位符在执行时会被替换成实际值。这是让技能可参数化的关键否则每个组件都要写一个技能那就失去意义了。3.2 技能加载的优先级与冲突处理当多个技能同时被触发时谁先谁后这个问题在实际项目里非常容易出问题。我的处理原则是优先级技能类型说明1最高安全与合规类比如禁止提交密钥、必须脱敏日志2项目基础规范代码风格、目录结构、命名约定3任务特定技能写组件、写 API、写测试4最低个人偏好类比如优先用 async/await高优先级技能的指令会覆盖低优先级的。比如基础规范说用单引号个人偏好说用双引号最终以基础规范为准。注意冲突处理一定要在 CLI 层面做不要指望模型自己判断。模型在上下文里看到两条矛盾指令时行为是不确定的。我踩过这个坑同一个项目里两个技能对 import 顺序的要求相反结果 agent 每次生成的代码风格都不一样。3.3 和 TDD 工作流的嵌合方式test-driven-development是这个项目里最值得单独说的一个技能。TDD 的核心是红-绿-重构但 agent 执行 TDD 时有个天然优势它不会像人一样偷懒跳过测试。我的做法是把 TDD 拆成三个子技能串成一个 pipelinewrite-failing-test根据需求描述先写一个会失败的测试。验证条件是测试确实失败了而不是测试通过了。这一步很关键很多 agent 会直接写一个通过的测试那就不是 TDD 了。implement-to-pass写最小实现让测试通过。验证条件是测试通过且没有新增 lint 错误。refactor-with-test-guard在测试保护下重构。验证条件是重构前后测试都通过。这三个子技能通过depends_on串起来形成一个有序的技能链。CLI 在执行时会按顺序加载前一个的验证不通过就不进入下一个。skills run tdd-pipeline --feature 用户登录这条命令背后CLI 会依次执行三个子技能每个子技能执行完都跑一遍验证。我实测下来这种强制验证的机制能显著降低 agent 写出看起来对但实际跑不通的代码的概率。3.4 技能的可测试性怎么验证技能本身是对的技能也是代码也需要测试。但技能的测试比较特殊因为它测的是agent 在给定技能下的行为。我的做法是维护一组黄金用例golden cases每个技能配 3-5 个输入输出对。比如react-component-with-test技能输入是创建一个显示用户名的组件期望输出是生成了 index.tsx 和 index.test.tsx且测试通过。验证方式是让 agent 在隔离环境里跑一遍然后检查产物是否符合预期。这个过程可以自动化但成本不低所以我一般只在技能版本升级时跑全量日常开发只跑受影响的技能。提示黄金用例不要写得太具体比如不要断言生成的代码第 5 行是 xxx。要断言结构性特征比如文件存在、测试通过、导出了默认组件。否则技能稍微优化一下用例就全挂了。4. 实操过程与核心环节实现4.1 从零搭建一个 agent-skills 项目假设你现在要从零开始搭一套我按实际操作顺序走一遍。第一步初始化项目结构。mkdir agent-skills cd agent-skills npm init -y mkdir -p skills packages/cli目录结构建议这样组织agent-skills/ ├── skills/ # 技能定义 │ ├── base/ # 基础规范类 │ ├── workflow/ # 工作流类如 TDD │ └── domain/ # 领域特定技能 ├── packages/ │ └── cli/ # CLI 实现 ├── golden-cases/ # 黄金用例 └── package.json第二步实现 CLI 的核心命令。CLI 不需要一开始就做得很复杂先实现四个命令list、install、run、validate。用 Node.js 写的话核心逻辑大概是这样// packages/cli/index.js import { readdir, readFile } from fs/promises; import { parse } from yaml; import { join } from path; async function loadSkills(skillsDir) { const categories await readdir(skillsDir); const skills []; for (const category of categories) { const files await readdir(join(skillsDir, category)); for (const file of files) { if (!file.endsWith(.md)) continue; const content await readFile(join(skillsDir, category, file), utf-8); const [_, frontmatter] content.split(---); const meta parse(frontmatter); skills.push({ ...meta, category, path: join(skillsDir, category, file) }); } } return skills; }这段代码的关键点是解析 frontmatter。我用yaml库而不是自己写正则因为技能定义里的 triggers 和 validation 都是结构化数据正则解析容易出错。第三步实现依赖解析。install命令需要处理depends_on。这是一个典型的拓扑排序问题function resolveDependencies(skill, allSkills, resolved new Set()) { if (resolved.has(skill.name)) return resolved; for (const dep of skill.depends_on || []) { const depSkill allSkills.find(s s.name dep); if (!depSkill) throw new Error(Missing dependency: ${dep}); resolveDependencies(depSkill, allSkills, resolved); } resolved.add(skill.name); return resolved; }这里有个坑循环依赖。A 依赖 BB 又依赖 A拓扑排序会死循环。我的处理方式是加一个visiting集合检测到环就报错并打印出环的路径方便排查。第四步实现验证执行器。run命令执行完技能后要跑 validation。validation 里的 command 是 shell 命令需要做占位符替换function renderCommand(template, context) { return template.replace(/\{\{(\w)\}\}/g, (_, key) { if (!(key in context)) throw new Error(Missing context: ${key}); return context[key]; }); }替换完用child_process.exec执行检查 exit code 和输出。这里要注意超时控制测试命令可能卡住我一般设 60 秒超时超时就判定失败。4.2 和 Claude Code 的集成配置技能包搭好之后怎么让 Claude Code 用上核心是在项目根目录的CLAUDE.md里声明技能包的路径和加载规则。## 技能包 本项目使用 agent-skills 技能包路径为 ./agent-skills/skills。 当遇到以下任务时请先加载对应技能 - 创建组件加载 react-component-with-test - 写测试加载 tdd-pipeline - 提交代码前加载 pre-commit-check 加载方式读取技能文件的 frontmatter 和 body按 body 中的步骤执行。然后在 Claude Code 的配置里把 skills CLI 加到允许执行的命令白名单里。这样 agent 就能自己调用skills run来执行技能。我实测下来这种集成方式比把所有技能内容塞进 CLAUDE.md要清爽得多。CLAUDE.md 只负责路由具体内容按需加载。4.3 一个完整的 TDD 实操记录我拿一个真实场景走一遍给一个 Express 项目加一个/health接口。技能触发我在 Claude Code 里输入给项目加一个健康检查接口。技能加载agent 识别到加接口这个触发词加载tdd-pipeline技能。第一步写失败测试。agent 生成tests/health.test.jsimport request from supertest; import app from ../src/app.js; describe(GET /health, () { it(returns 200 with status ok, async () { const res await request(app).get(/health); expect(res.status).toBe(200); expect(res.body.status).toBe(ok); }); });跑测试失败因为/health还没实现。验证通过进入下一步。第二步写最小实现。agent 在src/app.js里加app.get(/health, (req, res) { res.json({ status: ok }); });跑测试通过。验证通过进入下一步。第三步重构。agent 检查代码发现路由可以直接定义在 app 里不需要额外抽象。没有重构必要跳过。验证通过流程结束。整个过程大概 40 秒比我手动写快不少而且测试覆盖率是 100%——因为测试是先写的。4.4 技能包的版本管理与分发技能包会迭代怎么管理版本我的做法是语义化版本 changelog。修改指令措辞、修正错别字patch 版本新增技能、新增 validationminor 版本修改技能接口、删除技能、改变依赖关系major 版本分发方式有两种一种是作为 npm 包发布团队通过npm install获取另一种是作为 git submodule 挂在项目里。前者适合多项目复用后者适合单项目定制。我倾向于混合方案基础技能代码规范、TDD 流程发 npm 包项目特定技能放项目仓库里。这样基础技能升级时所有项目都能受益项目特定技能又不会被污染。5. 常见问题与排查技巧实录5.1 技能不生效的排查路径这是最高频的问题。agent 明明加载了技能但行为不符合预期。我整理了一个排查清单现象可能原因排查方法技能完全没被加载triggers 不匹配打印 agent 的加载日志看触发了哪些技能技能加载了但没执行指令层写得太模糊检查指令是否有明确的动词和步骤编号执行了但验证没跑validation 配置错误手动跑一遍 validation command验证跑了但结果不对占位符没替换检查 context 里是否有对应的 key多个技能冲突优先级没定义检查是否有重叠的 triggers我踩过最坑的一次是 triggers 写成了组件结果 agent 在讨论组件设计时也加载了创建组件的技能导致它一直想写代码而不是讨论。后来我把 triggers 改成创建组件、新建组件文件这种带动词的短语问题就解决了。5.2 上下文爆炸的处理技能多了之后agent 的上下文会被塞满导致它忽略关键指令。我的处理原则是分层加载基础规范类技能常驻但压缩成要点列表不超过 500 字任务特定技能按需加载执行完就卸载验证类技能只在验证阶段加载另外技能指令要写得紧凑。我见过有人把技能写成一篇教程几千字agent 读完前面的就忘了后面的。正确做法是写成 checklist每条不超过两行。5.3 技能和模型能力不匹配怎么办有些技能依赖模型的高级能力比如理解业务逻辑后自动生成测试用例。如果模型能力不够技能就会执行失败。我的建议是技能设计要匹配模型能力。对于能力不足的场景把技能拆成人机协作模式agent 生成草稿人补充关键部分agent 再验证。不要指望 agent 一步到位。提示技能包里可以标注min_model_capability比如reasoning: high。CLI 在加载时检查当前模型是否满足不满足就降级到简化版技能。这个机制在多模型环境下特别有用。5.4 技能测试的成本控制黄金用例跑全量很慢尤其是涉及真实文件操作的技能。我的优化方式并行执行不同技能的用例可以并行跑用 worker 池控制并发数增量测试只跑受影响的技能通过依赖图计算影响范围缓存技能定义没变、模型没变的情况下复用上次结果实测下来全量测试从 15 分钟压到 3 分钟左右日常开发基本可以接受。5.5 团队协作中的技能治理技能是团队资产需要治理。我建议设一个技能评审流程新增技能需要至少一人 review修改基础规范类技能需要两人 review每个技能必须有 owner负责维护和答疑每季度清理一次僵尸技能半年没人用的这套流程听起来重但实际执行下来一个月也就几次评审成本可控。关键是避免了技能包变成垃圾场——我见过一个团队积累了 80 多个技能一半没人维护agent 加载时经常被过时技能干扰。6. 技能包的扩展方向与个人体会聊完核心实现再说说这个项目后续可以怎么扩展。我自己在用的几个方向技能市场。把技能包做成可分享的仓库团队之间可以互相安装。类似 npm 的生态但规模小很多。这个方向的关键是质量把关否则市场里全是低质量技能反而增加选择成本。技能组合 DSL。现在技能链是靠depends_on硬编码的未来可以做一个简单的 DSL让用户用声明式的方式定义工作流。比如workflow: feature-development steps: - skill: write-failing-test - skill: implement-to-pass - skill: refactor-with-test-guard - skill: pre-commit-check这样工作流本身也变成了可版本化、可复用的资产。和 CI 集成。技能验证目前是本地跑的未来可以接到 CI 里每次 PR 都跑一遍受影响的技能确保 agent 生成的代码符合规范。这个方向我还在探索主要难点是 CI 环境里跑 agent 的成本和稳定性。最后分享一个我个人的体会技能包的价值不在于技能数量而在于技能的命中率。我见过团队堆了上百个技能但 agent 实际用到的就那几个。与其追求大而全不如先把最高频的三五个场景做扎实让 agent 在这些场景下的表现稳定超过人肉操作然后再逐步扩展。技能包这东西本质上是把团队的工程经验沉淀下来沉淀的前提是经验本身足够成熟——如果流程还在天天变那先别急着写技能等流程稳定了再说。