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-workflow@1.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 行为不符合预期时，不要急着改提示词，先想想是不是该加一个技能约束。把临时提示词沉淀成技能，是长期收益最高的做法。我现在项目里的技能包已经积累了十几个，新项目直接复制过去，开箱即用。
