1. 从 agent-skills 说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agents 装“技能包”的标准化方案。过去大半年我一直在用 Claude Code 做日常开发从最初的新鲜感到后来被它“什么都想自己写一遍”的毛病折磨再到慢慢摸索出一套让它听话的方法。这个过程里agent-skills这类东西出现的时机刚刚好。简单说agent-skills解决的是一个很具体的问题AI coding agent 默认什么都会一点但什么都不精。你让它写个 React 组件它能写你让它按你们团队的规范写它就开始自由发挥你让它先写测试再写实现它经常忘。这不是模型能力不够而是缺少一套可复用、可组合、可版本管理的“技能定义”。agent-skills就是把这套东西标准化配合skills CLI做安装、分发和管理让 agent 在不同项目里能快速加载对应的能力。它适合谁三类人最该关注。第一类是已经在用 Claude Code、Cursor、Windsurf 这类 AI coding agent 的开发者你肯定遇到过“每次都要重新解释一遍项目规范”的痛点。第二类是团队里负责工程效能的人你需要一套机制让所有成员的 agent 行为一致。第三类是对 test-driven-development 有执念的人因为agent-skills里最典型的一类技能就是 TDD 工作流强制 agent 先写测试。我自己的使用场景很直接一个中型 TypeScript 项目三个人协作用 Claude Code 做主力开发工具。没有agent-skills之前每个人跟 agent 的对话风格不一样产出的代码风格也不一样code review 时经常要返工。引入这套东西之后至少“先写测试、再写实现、最后重构”这个流程被固化下来了。2. agent-skills 到底解决了什么问题核心思路拆解2.1 从“提示词工程”到“技能工程”的转变大部分人用 AI coding agent 的方式还停留在“提示词工程”阶段每次遇到问题临时想一段话描述需求然后祈祷 agent 理解对了。这种方式的问题很明显——不可复用、不可测试、不可协作。你今天写了一段很精妙的提示词让 agent 按 TDD 流程走明天换个项目又得重写一遍。agent-skills的思路是把这些提示词升级成“技能”。一个技能就是一个结构化的定义包含这个技能叫什么、什么时候触发、具体步骤是什么、有哪些约束条件、输出格式是什么。它不再是散落在对话历史里的几句话而是一个可以放进 Git 仓库、可以 code review、可以版本管理的文件。这个转变的意义在于agent 的行为从“个人经验”变成了“团队资产”。你踩过的坑、总结的最佳实践不再只存在于你的脑子里而是变成了一个可以被其他人安装、使用、改进的技能包。2.2 skills CLI 的角色安装、分发、组合skills CLI是这个体系里的基础设施。它的作用类似于 npm 之于 JavaScript 包或者 brew 之于 macOS 软件。你可以用它来从远程仓库安装一个技能包列出当前项目已安装的技能更新某个技能到最新版本移除不再需要的技能在本地创建一个新技能的脚手架我实测下来skills CLI的设计哲学是“轻量、组合优先”。它不试图做一个大而全的平台而是让技能包像乐高积木一样可以自由拼装。比如你可以装一个tdd-workflow技能再装一个typescript-strict-mode技能两个技能会同时生效agent 在写代码时会同时遵守 TDD 流程和 TypeScript 严格模式规范。2.3 与 Claude Code 的集成方式agent-skills和 Claude Code 的集成是我最关心的部分。Claude Code 本身支持通过配置文件比如CLAUDE.md来注入项目级指令但这种方式有两个局限一是所有指令混在一个文件里难以维护二是没有版本管理和分发机制。agent-skills的做法是在项目根目录下创建一个.agent-skills目录每个技能一个子目录里面包含技能定义文件。Claude Code 启动时会自动读取这个目录把技能加载进上下文。这样你既保留了 Claude Code 的原生能力又获得了模块化的技能管理。注意不同版本的 Claude Code 对技能目录的读取方式可能有差异建议先确认你使用的版本是否支持自动加载如果不支持可以通过CLAUDE.md里的引用指令手动引入。3. 核心细节解析一个技能包到底长什么样3.1 技能定义文件的结构一个典型的技能包目录结构是这样的.agent-skills/ tdd-workflow/ skill.yaml prompts/ write-test.md write-impl.md refactor.md README.md typescript-strict/ skill.yaml rules.md核心是skill.yaml它定义了技能的元信息和触发条件。我拿一个简化版的 TDD 技能举例name: tdd-workflow version: 1.2.0 description: 强制 agent 按测试驱动开发流程工作 triggers: - pattern: 实现.*功能 - pattern: 添加.*方法 - command: /tdd constraints: - 必须先写测试测试失败后才能写实现 - 每次只实现一个测试用例 - 实现完成后必须运行全部测试 output_format: markdown这个文件里triggers定义了什么时候激活这个技能constraints定义了 agent 必须遵守的硬性规则output_format定义了输出格式。我特别喜欢constraints这个设计因为它把“软提示”变成了“硬约束”agent 违反约束时你可以明确指出来。3.2 触发机制的设计考量触发机制是技能包好不好用的关键。设计得太宽泛技能会在不合适的场景下被激活干扰正常对话设计得太窄又需要用户频繁手动调用。agent-skills支持三种触发方式模式匹配根据用户输入的文字内容匹配正则表达式命令触发用户输入特定命令如/tdd时激活文件触发当操作涉及特定类型文件时激活如编辑.test.ts文件时我自己的经验是模式匹配适合高频、通用的技能命令触发适合低频、需要显式调用的技能。比如 TDD 工作流适合模式匹配因为写代码时经常需要而“生成 API 文档”这种技能适合命令触发因为不是每次都需要。3.3 技能之间的优先级与冲突处理当你同时安装了多个技能它们之间可能会冲突。比如一个技能说“先写测试”另一个技能说“先写类型定义”agent 到底听谁的agent-skills的解决方案是给每个技能一个priority字段数值越大优先级越高。当多个技能同时触发时agent 会按优先级顺序处理。如果两个技能优先级相同且约束冲突agent 会暂停并询问用户。这个设计很务实因为实际项目中技能冲突是常态。我建议在团队里约定一个优先级规范比如安全相关技能优先级最高100流程相关技能次之50风格相关技能最低10。4. 实操过程从零搭建一套可用的技能体系4.1 环境准备与 skills CLI 安装假设你已经在用 Claude Code并且项目是一个 Node.js 项目。第一步是安装skills CLI。根据我的实测最稳妥的方式是通过 npm 全局安装npm install -g agent-skills/cli安装完成后验证skills --version如果输出版本号说明安装成功。这里有个小坑如果你用的是 nvm 管理 Node 版本全局安装的 CLI 可能在不同 Node 版本间不共享。我的做法是在项目里用npx skills代替全局命令这样每个项目锁定自己的版本。提示如果你在 Ubuntu 或 macOS 上遇到权限问题不要用sudo npm install -g而是配置 npm 的全局目录到用户目录下避免污染系统环境。4.2 初始化项目技能目录进入你的项目根目录执行skills init这个命令会创建.agent-skills目录和一个默认的skill.yaml模板。我建议立刻把这个目录加入 Git 版本控制因为技能定义是团队资产应该像代码一样被管理。初始化完成后目录结构如下.agent-skills/ skill.yaml README.mdREADME.md里会自动生成一段说明告诉你如何添加新技能。我通常会把它改写成团队内部的技能使用规范比如“所有新技能必须包含至少一个测试用例”。4.3 安装第一个技能TDD 工作流现在安装一个现成的 TDD 技能包skills install tdd-workflow这个命令会从默认仓库拉取技能包并解压到.agent-skills/tdd-workflow/。安装完成后你可以用skills list查看已安装的技能skills list输出类似Installed skills: tdd-workflow1.2.0 - 强制 agent 按测试驱动开发流程工作这时候打开 Claude Code试着输入“帮我实现一个用户注册功能”agent 应该会自动激活 TDD 技能先问你测试用例怎么写而不是直接开始写实现代码。4.4 自定义技能以“API 响应格式规范”为例现成的技能包不一定完全符合你的项目需求所以自定义技能是必备能力。我拿一个实际例子演示我们团队的 API 响应格式统一为{ code, data, message }我希望 agent 在写接口时自动遵守这个格式。首先创建技能脚手架skills create api-response-format然后在生成的skill.yaml里填写name: api-response-format version: 1.0.0 description: 统一 API 响应格式为 code/data/message triggers: - pattern: 接口|API|endpoint - file: **/controllers/**/*.ts constraints: - 所有响应必须包含 code、data、message 三个字段 - code 为 0 表示成功非 0 表示错误 - data 在错误时可以为 null - message 在成功时可以为空字符串 priority: 50然后在rules.md里写详细说明和示例代码。这样 agent 在写控制器代码时就会自动遵守这个格式。4.5 验证技能是否生效技能装好了怎么确认它真的生效了我的方法是设计一个“探针测试”故意给 agent 一个会触发技能的场景看它的行为是否符合预期。比如对于 TDD 技能我会输入“实现一个函数计算两个数的和”。如果技能生效agent 应该先写测试文件运行测试看到失败然后再写实现。如果它直接写了实现说明技能没生效。排查步骤检查.agent-skills目录是否存在且技能文件完整检查skill.yaml里的triggers是否匹配你的输入检查 Claude Code 的版本是否支持技能自动加载查看 Claude Code 的日志确认技能是否被读取5. 常见问题与排查技巧实录5.1 技能不生效的几种典型情况我踩过的坑里技能不生效占了大多数。整理成一张速查表现象可能原因解决方法技能完全没反应目录位置不对确认.agent-skills在项目根目录技能偶尔生效触发模式太窄放宽triggers的正则表达式技能冲突多个技能优先级相同调整priority字段技能加载报错YAML 格式错误用 YAML 校验工具检查技能生效但行为不对约束描述模糊把constraints写得更具体5.2 技能与 Claude Code 原生指令的冲突Claude Code 本身支持CLAUDE.md文件注入项目指令。如果你同时用了CLAUDE.md和agent-skills可能会出现指令冲突。我的经验是把通用规范放在CLAUDE.md把流程性、可复用的技能放在agent-skills。两者分工明确冲突就少了。如果确实冲突了Claude Code 的优先级是agent-skills的约束 CLAUDE.md的指令。因为技能是显式安装的被认为更具体。5.3 技能版本管理与团队协作技能包应该像代码一样做版本管理。我建议每个技能包独立版本号遵循语义化版本技能变更走 code review 流程在README.md里记录变更日志定期用skills update更新技能包团队协作时新成员只需要git clone项目然后skills install安装所有依赖技能就能获得一致的 agent 行为。这比口头传达规范靠谱得多。5.4 性能与上下文窗口的权衡技能装多了会占用 Claude Code 的上下文窗口。我实测下来每个技能大约占用 200-500 token装 10 个技能就是 2000-5000 token。对于大多数项目来说可以接受但如果你用的是上下文窗口较小的模型就需要精简。我的做法是按项目类型分组技能。比如前端项目只装前端相关技能后端项目只装后端相关技能。不要把所有技能都装到一个项目里。6. 进阶玩法把 agent-skills 用出花来6.1 技能组合TDD 代码审查 提交规范单个技能威力有限组合起来才厉害。我现在的标配是三个技能组合tdd-workflow强制先写测试code-review-checklist每次提交前自动检查代码质量commit-convention按约定式提交规范生成 commit message这三个技能串起来agent 的工作流就变成了写测试 → 写实现 → 自检 → 生成规范 commit。整个过程不需要我反复提醒效率提升非常明显。6.2 动态技能根据文件类型自动切换agent-skills支持基于文件类型的触发。这意味着你可以让 agent 在编辑不同文件时自动切换技能。比如编辑.test.ts文件时激活测试编写技能编辑.tsx文件时激活 React 组件规范技能编辑.sql文件时激活 SQL 安全审查技能这个功能特别适合全栈项目因为前后端规范差异很大动态切换能避免“一刀切”的规范。6.3 技能的市场化与共享agent-skills生态里已经有一些公开的技能包可以安装。我建议先从公开技能包开始理解技能的设计模式然后再写自己的。公开技能包的质量参差不齐安装前先看 README 和最近更新时间。如果你写了一个好用的技能包也可以发布出去。发布流程和 npm 包类似需要注册账号、填写元信息、推送版本。我还没发布过但看过流程不算复杂。7. 我个人的使用体会用agent-skills这几个月最大的感受是它把 AI coding agent 从“聪明的实习生”变成了“遵守规范的团队成员”。实习生很聪明但你需要反复交代规范团队成员可能没那么聪明但你知道他会按规矩办事。当然它也不是银弹。技能定义写得不好agent 照样跑偏技能装太多上下文窗口吃不消团队不统一技能版本协作时还是会乱。但这些问题都有解而且解决成本不高。最后分享一个小技巧每次 agent 行为不符合预期时不要急着改提示词先想想是不是该加一个技能约束。把临时提示词沉淀成技能是长期收益最高的做法。我现在项目里的技能包已经积累了十几个新项目直接复制过去开箱即用。