1. agent-skills 到底在解决什么问题
第一次看到agent-skills这个词，很多人会以为它又是一个新的 AI 框架或者某个大模型的插件市场。实际上，它更像是一套给 AI coding agent 用的“技能说明书”集合——把常见的开发任务拆成可复用、可组合、可测试的技能单元，让 agent 在写代码时不是靠瞎猜，而是按照明确的流程和约束去执行。
我最初接触这个概念是在折腾 Claude Code 的时候。当时我让它帮我改一个 Node.js 项目的接口，结果它上来就改了三四个文件，跑都没跑就告诉我“已完成”。后来我才意识到，问题不在于模型能力不够，而在于我没有给它一套明确的“技能”——比如“先读测试文件、再改实现、最后跑测试验证”这样的固定动作。agent-skills要做的，就是把这些动作标准化。
它适合谁？如果你正在用 Claude Code、Cursor、Windsurf 这类 AI coding agent 做日常开发，或者你正在搭建自己的 agent 工作流，那这套东西值得花时间研究。它不要求你会训练模型，但要求你理解“任务拆解”和“验证闭环”这两个核心思路。简单说，agent-skills是把“让 AI 写代码”从碰运气变成可重复工程实践的一层薄薄的规范。
关键词里提到的test-driven-development其实是理解agent-skills的一把钥匙。因为大多数 agent 默认的行为是“生成代码然后声称完成”，而 skills 的核心价值在于强制 agent 进入“先定义验证标准，再执行，再验证”的循环。这个思路和 TDD 几乎一模一样，只不过测试的执行者从人变成了 agent 自己。
2. 从 Claude Code 的安装到 skills 的落地路径
2.1 先把 Claude Code 跑起来，再谈 skills
不管你用的是 Mac、Ubuntu 还是 Windows，Claude Code 的安装方式基本一致。官方推荐的是通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code安装完成后，在项目目录下直接运行claude就能进入交互模式。如果你用的是 VS Code，可以装官方插件，这样 agent 能直接读取你当前打开的文件和终端输出，省去很多复制粘贴的麻烦。
Ubuntu 用户需要注意 Node.js 版本，建议用 18 以上。我遇到过 Node 16 环境下安装成功但运行时报模块解析错误的情况，升级到 Node 20 后问题消失。Mac 用户如果用 Homebrew 装的 Node，记得检查npm prefix -g的路径是否在 PATH 里，否则全局命令会找不到。
提示：安装完成后先跑一次
claude --version，确认版本号正常输出。如果提示命令不存在，大概率是 npm 全局路径没配好。
2.2 skills CLI 的定位和基本用法
skills CLI是管理 agent skills 的命令行工具。它的作用类似于包管理器，但管理的不是代码依赖，而是“技能包”。你可以把它理解成一个技能仓库的客户端：从远程拉取技能定义、在本地注册、在 agent 运行时按需加载。
基本流程是这样的：
- 初始化技能目录：
skills init会在项目根目录创建.skills/文件夹 - 安装技能：
skills add <skill-name>从注册表拉取技能定义 - 列出已安装技能：
skills list查看当前项目可用的技能 - 在 agent 配置中引用技能：通常在
CLAUDE.md或 agent 的配置文件中声明
这里有个容易踩的坑：很多人以为装了 skills 就自动生效，实际上你需要在 agent 的上下文配置文件里显式引用。Claude Code 读取的是项目根目录的CLAUDE.md，你需要在里面写上类似“本项目使用以下 skills：test-driven-development、code-review”这样的声明，agent 才会在对应场景下调用。
2.3 为什么 skills 要用“文件”而不是“提示词”
我一开始也觉得奇怪，为什么不直接把技能写成一段 prompt 塞给模型？后来在实际项目中对比了两种做法，差距很明显。
把技能写成 prompt 的问题是：每次对话都要重复注入，token 消耗大；而且 prompt 是纯文本，没有结构，agent 很难判断“当前任务是否匹配这个技能”。而 skills 用结构化文件（通常是 Markdown 加 YAML frontmatter）定义，包含技能名称、触发条件、执行步骤、验证标准。agent 可以先扫描技能列表，判断当前任务该用哪个技能，再加载完整内容。
这就像你给一个新员工培训：你可以每天在他耳边重复“改代码要先跑测试”，也可以给他一本操作手册，让他遇到对应场景时自己翻。后者显然更可持续。
3. test-driven-development 技能的内部结构拆解
3.1 一个 skill 文件长什么样
以test-driven-development这个技能为例，它的文件结构通常包含几个部分：
--- name: test-driven-development description: 在修改或新增功能时，先编写测试再实现代码 trigger: 当任务涉及功能变更、bug修复、接口调整时 --- ## 执行步骤 1. 阅读现有测试文件，理解测试框架和断言风格 2. 根据需求编写或修改测试用例 3. 运行测试，确认新测试失败（红） 4. 编写最小实现使测试通过（绿） 5. 重构代码，保持测试通过 6. 运行完整测试套件，确认无回归 ## 验证标准 - 新增测试必须覆盖需求中的每个行为 - 测试运行结果必须从失败变为通过 - 不允许跳过测试直接改实现这个结构的关键在于trigger字段。agent 在接到任务后，会先匹配 trigger，如果当前任务符合“功能变更”或“bug修复”，就会自动加载这个技能并按照步骤执行。
3.2 为什么“先写测试”对 agent 特别重要
人类开发者跳过测试直接写实现，后果通常是技术债。但 agent 跳过测试直接写实现，后果是“它以为自己写对了”。因为 agent 没有运行时反馈，它只能根据训练数据里的模式生成代码。如果没有测试作为验证手段，它生成的代码可能语法正确、逻辑看似合理，但实际跑起来完全不是那么回事。
我实测过一个场景：让 agent 给一个 Express 接口加参数校验。不加 skills 的情况下，它直接在路由处理函数里加了几行 if 判断，看起来没问题。但跑起来发现它把req.body和req.query搞混了，参数根本取不到。后来我给它加载了 TDD 技能，它先写了一个测试用例，用 supertest 发请求断言返回 400，然后跑测试看到失败，再改实现，最后测试通过。整个过程它自己完成了验证闭环。
这就是 skills 的核心价值：不是让 agent 更聪明，而是让 agent 更可验证。
3.3 技能之间的组合与优先级
实际项目中，一个任务往往需要多个技能配合。比如“修复一个 bug”可能同时触发test-driven-development和code-review。这时候就需要定义优先级和组合规则。
常见的做法是在技能文件里加一个priority字段，或者在项目的 agent 配置里指定技能执行顺序。我的经验是：验证类技能（TDD、lint）优先级最高，因为它们决定代码能不能跑；审查类技能（code-review、security-check）次之；格式化类技能（prettier、eslint --fix）最后。
如果顺序搞反了，会出现“先格式化再审查”的尴尬情况——审查时看到的代码格式和最终提交的不一致，审查意见可能失效。
4. 把 skills 接入日常开发流的实操细节
4.1 在 VS Code 里配置 agent 读取 skills
VS Code 的 Claude Code 插件默认会读取工作区根目录的CLAUDE.md。你需要在这个文件里声明技能目录和启用列表。一个可用的配置示例：
# 项目 Agent 配置 ## 技能目录 .skills/ ## 启用技能 - test-driven-development - code-review - commit-message ## 执行约束 - 修改代码前必须先运行相关测试 - 提交前必须通过 lint 检查配置完成后，重启 VS Code 或者重新加载窗口，agent 就会在启动时加载这些技能。你可以在对话里问它“当前启用了哪些技能”来验证。
注意：如果你用的是远程开发或者 WSL 环境，确保
.skills/目录在 workspace 范围内，否则 agent 可能读不到。
4.2 用 cc switch 切换模型时的技能兼容性
很多人会用cc switch这类工具在 Claude Code 里切换不同的模型后端，比如 DeepSeek、Qwen、GLM 等。这里有个实际问题：不同模型对结构化技能文件的解析能力不一样。
我实测下来，Claude 系列对 YAML frontmatter 和 Markdown 步骤的遵循度最高，基本能按步骤执行。DeepSeek 和 Qwen 在简单技能上表现不错，但遇到多步骤、带条件分支的技能时，偶尔会跳步。GLM 的表现介于两者之间。
应对策略是：如果你用第三方模型，尽量把技能步骤写得更线性、更明确，减少“如果……则……”这样的分支描述。另外，可以在技能文件里加一个model_hint字段，提示 agent 在当前模型下应该简化哪些步骤。
4.3 技能文件的版本管理和团队共享
.skills/目录应该纳入 Git 版本管理。这样团队成员拉取代码后，agent 的行为是一致的。但要注意两点：
第一，技能文件里不要硬编码个人路径或密钥。我见过有人在技能里写了本地绝对路径，结果同事拉下来后 agent 一直报文件找不到。
第二，技能更新要有 changelog。因为技能变了，agent 的行为就变了。如果某次提交改了 TDD 技能的验证标准，团队里每个人的 agent 都会受影响。建议在技能目录下放一个CHANGELOG.md，记录每次修改的原因和影响范围。
5. 踩坑记录：skills 不生效的几种典型情况
5.1 技能加载了但 agent 不执行
这是最常见的问题。表现是：skills list能看到技能，但 agent 接到任务后还是按自己的方式写代码，完全不参考技能步骤。
排查链路是这样的：
- 先确认
CLAUDE.md里的技能名称和.skills/目录下的文件名一致。大小写、连字符都要对上。 - 检查技能的
trigger字段是否覆盖了当前任务类型。如果 trigger 写的是“功能开发”，而你让它修 bug，它可能不触发。 - 看 agent 的上下文窗口是否被占满。如果项目很大，
CLAUDE.md和技能文件可能被截断。这时候需要精简配置，或者把技能拆成更小的单元。 - 最后检查模型本身是否支持结构化指令跟随。有些轻量模型对 Markdown 格式的指令遵循度很差。
我遇到过一次，排查了半天发现是技能文件名用了下划线test_driven_development.md，而配置里写的是连字符test-driven-development。改过来就正常了。
5.2 技能执行到一半卡住
另一种情况是 agent 开始按技能步骤执行了，但中途停下来，比如写完测试后不跑，或者跑完测试不继续改实现。
这通常是因为技能步骤里缺少明确的“下一步”指令。Agent 在每一步结束后需要知道接下来做什么。如果步骤之间是并列关系而不是顺序关系，它可能会犹豫。
解决办法是在每个步骤末尾加上明确的过渡语句，比如“完成本步后，立即进入第 3 步”。另外，可以在技能文件末尾加一个completion_criteria字段，告诉 agent 什么条件下才算完成整个技能。
5.3 多个技能冲突导致行为混乱
当 TDD 技能和 code-review 技能同时触发时，agent 可能一会儿写测试一会儿审查代码，来回切换。这是因为两个技能的优先级没有定义清楚。
我的做法是在项目配置里显式指定技能执行顺序：
skill_order: - test-driven-development - code-review - commit-message这样 agent 会先完成 TDD 流程，再进入审查，最后生成提交信息。顺序明确了，行为就稳定了。
6. 让 skills 真正提升效率的几个经验
6.1 技能粒度要适中
技能太粗，比如一个“全栈开发”技能包含从数据库到前端的全部步骤，agent 执行起来容易迷失。技能太细，比如“添加一个 import 语句”也做成技能，管理成本又太高。
我的经验是：一个技能对应一个可验证的交付物。比如“新增 API 接口”是一个合适的粒度，因为它有明确的输入（接口定义）和输出（通过的测试）。而“优化代码”就太模糊，不适合做成技能。
6.2 技能文件要像代码一样 review
很多人把技能文件当成一次性配置，写完就不管了。但实际上，技能文件直接影响 agent 的输出质量。我们团队的做法是：技能文件的修改走和代码一样的 PR 流程，至少一个人 review。
Review 的重点是：步骤是否可执行、验证标准是否明确、trigger 是否覆盖了目标场景。我见过一个技能写的是“确保代码质量良好”，这种描述 agent 根本没法执行，因为它不知道“良好”的标准是什么。
6.3 定期清理失效技能
项目在演进，有些技能可能不再适用。比如早期为了迁移数据库写的技能，迁移完成后就没用了。这些技能留在目录里，会增加 agent 的匹配负担，甚至误触发。
建议每个迭代周期检查一次.skills/目录，把不再使用的技能归档或删除。删除前确认没有其他技能依赖它。
6.4 用真实任务验证技能效果
技能写完后，不要只看它“能不能跑”，要用真实任务验证。我的做法是准备一组基准任务，比如“给现有接口加一个字段”“修复一个已知 bug”“重构一个函数”，然后对比启用技能前后的 agent 表现。
对比维度包括：首次生成代码的正确率、需要人工干预的次数、最终提交的代码是否符合项目规范。实测下来，启用 TDD 技能后，首次正确率能从大概五成提升到八成以上，人工干预次数减少一半左右。
这个数据因项目和模型而异，但趋势是一致的：有明确验证闭环的技能，效果远好于纯提示词。
6.5 技能不是越复杂越好
最后说一个反直觉的经验：技能文件越复杂，agent 执行成功率越低。因为 agent 的上下文理解能力有限，步骤太多、条件太复杂时，它容易漏掉或混淆。
一个好的技能文件，核心步骤控制在 5 到 7 步，每步一句话说清楚做什么、怎么验证。超过这个复杂度，就应该拆成多个技能，通过组合来完成。
我在实际项目里把 TDD 技能从最初的 12 步精简到 6 步后，agent 的完成率明显提升。精简掉的主要是解释性文字和边缘情况的处理，这些可以放到技能的附录里，让 agent 按需查阅，而不是每次都加载。
如果你也在用 Claude Code 或者其他 AI coding agent，建议从test-driven-development这一个技能开始试。把它写清楚、跑通、验证效果，然后再逐步扩展其他技能。这个顺序比一上来就搭一套完整的技能体系要靠谱得多。
