1. 从"agent-skills"这个标题能读出什么

第一次看到"agent-skills"这个词，我的直觉是它不是一个具体的软件产品名，而更像是一个能力集合或者技能库的概念。结合热搜词里反复出现的 AI coding agents、skills CLI、Claude Code、test-driven-development 这几个关键词，基本可以判断：这是一个围绕 AI 编程代理（AI coding agent）构建的可复用技能模块体系，核心目标是把"让 AI 帮你写代码"这件事从随缘对话变成有章法、可复现的工程流程。

说白了，大多数人用 AI 编程工具的方式是：打开对话框，描述需求，等它吐代码，复制粘贴，跑一下，报错了再贴回去让它改。这种方式在写一个几十行的小脚本时没问题，但一旦项目规模上去、涉及多文件改动、需要跑测试、需要遵守团队规范，纯对话式的做法就会迅速失控。agent-skills 想解决的正是这个失控问题——它把常见的开发任务拆解成一个个标准化的"技能"，每个技能有明确的输入、输出、执行步骤和验证方式，AI 代理按照技能定义去执行，而不是自由发挥。

这篇文章适合三类人看：第一类是想搞清楚 AI coding agent 到底怎么用才高效的中级开发者；第二类是已经在用 Claude Code 这类工具、但总觉得"差点意思"的实践者；第三类是对 test-driven-development 和 skills CLI 这套组合感兴趣、想搭一套自己工作流的技术负责人。我会从概念拆解、环境准备、技能设计、TDD 集成、CLI 实操、踩坑经验几个维度展开，尽量把每个环节的"为什么"讲透。

需要提前说明的是，agent-skills 目前没有一个官方统一的定义，不同团队、不同工具链下它的具体形态差异很大。我下面讲的内容，是基于当前主流 AI coding agent 的通用实践和热搜词透露出的技术方向做的合理推演，具体落地时你需要根据自己的工具链做适配。

2. AI coding agent 的能力边界到底在哪

2.1 代理不是万能助手，它是个"执行力很强但需要指令的实习生"

很多人对 AI coding agent 的期待是"我说个大概，它全帮我搞定"。实测下来，这种期待在简单任务上偶尔能兑现，但在真实项目里几乎必然翻车。原因很简单：代理没有你的项目上下文，不知道你们团队的代码规范，不清楚哪些模块是历史遗留不能动的，更不知道你嘴上说的"优化一下"具体指性能、可读性还是可维护性。

我习惯把 AI coding agent 类比成一个执行力极强但完全没有背景知识的实习生。你给它一个清晰、边界明确、有验收标准的任务，它能干得又快又好；你给它一个模糊的、需要判断力的任务，它就会开始"自由发挥"，而自由发挥的结果往往不是你想要的。

这个认知直接决定了 agent-skills 的设计哲学：把模糊需求转化为明确技能。一个技能应该包含：触发条件（什么时候用这个技能）、输入参数（需要提供什么信息）、执行步骤（按什么顺序做什么）、验证标准（怎么判断做完了、做对了）。这四要素缺一不可，尤其是验证标准，这是区分"玩具级用法"和"工程级用法"的分水岭。

2.2 为什么 skills CLI 是这套体系的关键拼图

热搜词里出现了 skills CLI，这不是偶然。如果 agent-skills 只是一堆写在文档里的规范，那它很快就会变成"写了没人看"的摆设。CLI 的价值在于把技能变成可执行、可调用、可版本管理的实体。

想象一下这个场景：你定义了一个叫add-api-endpoint的技能，规定了新增 API 接口时必须先写测试、再写实现、最后更新文档。如果没有 CLI，你只能靠自觉去提醒 AI"记得先写测试"；有了 CLI，你可以直接执行skills run add-api-endpoint --path /users --method POST，CLI 会自动把技能定义、项目上下文、相关文件一起喂给 AI 代理，并按预设流程驱动它一步步执行。

这就是从"对话式编程"到"技能式编程"的跃迁。前者依赖你的临场表达和 AI 的临场理解，后者把最佳实践固化成了可复用的流程。对于团队协作来说，这意味着新人也能通过调用技能产出符合规范的代码，而不是每个人都要重新摸索一遍怎么跟 AI 沟通。

2.3 当前阶段最值得投入的三类技能

不是所有任务都值得做成技能。根据我的经验，以下三类任务的投入产出比最高：

反过来，那些一次性的、高度依赖具体业务判断的任务，做成技能反而增加负担。我见过有团队把"设计数据库 schema"也做成技能，结果每次调用都要填一堆参数，还不如直接对话来得快。技能化的边界是：流程稳定、标准明确、重复出现。

3. 把环境搭起来：从 Claude Code 到 skills CLI

3.1 工具链选型的几个现实考量

热搜词里 Claude Code 出现频率极高，还有一堆关于安装、配置、接入第三方模型的问题。这说明大家在实际落地时，第一个卡点就是环境。我先说选型逻辑，再说具体操作。

选 AI coding agent 工具，核心看三个维度：上下文理解能力、工具调用能力、可扩展性。上下文理解决定了它能不能读懂你的项目；工具调用决定了它能不能真正执行命令、读写文件，而不只是聊天；可扩展性决定了你能不能把 agent-skills 这套体系接进去。

Claude Code 在这三个维度上目前是比较均衡的选择，尤其是它的终端命令执行能力和文件操作能力，让它能真正参与到开发流程里，而不是停留在"给建议"的层面。至于接入第三方模型（热搜里提到的 deepseek、qwen、glm 等），这属于成本优化和可用性考量，思路是通过兼容层把不同模型统一到同一套调用接口下，具体配置因工具而异，这里不展开。

3.2 环境准备中最容易忽略的三个细节

大部分人装完工具、跑通一个 hello world 就以为环境好了，结果真正用起来各种问题。以下三个细节是我踩过坑之后总结的：

第一，工作目录的隔离。AI coding agent 默认能访问你给它的整个目录树。如果你在 home 目录下启动它，理论上它能读到你的所有文件。正确做法是为每个项目单独开一个工作目录，并且用配置文件明确限定它能访问的路径范围。这不是多疑，而是防止 AI 在"帮我清理一下项目"这类指令下误删无关文件。

第二，依赖版本的锁定。skills CLI 这类工具往往依赖特定版本的运行时（Node、Python 等）。我遇到过因为全局 Node 版本和项目要求不一致，导致 CLI 报奇怪的模块错误，排查了半天才发现是版本问题。建议用版本管理工具（如 nvm、pyenv）为每个项目锁定运行时版本，并在项目根目录放一个.tool-versions或类似文件。

第三，网络与权限的预检。如果你的技能涉及调用外部 API、拉取依赖、访问数据库，务必在正式跑技能前手动验证一遍这些外部依赖是通的。AI 代理执行失败时，报错信息往往指向它自己的操作，而不是底层依赖问题，容易误导排查方向。

3.3 一个最小可用的目录结构

在项目里引入 agent-skills，我建议用这样的目录结构：

project-root/ ├── .agent-skills/ │ ├── skills/ │ │ ├── add-api-endpoint.yaml │ │ ├── write-unit-test.yaml │ │ └── refactor-module.yaml │ ├── config.yaml │ └── context.md ├── src/ ├── tests/ └── README.md

.agent-skills/skills/放技能定义，每个技能一个文件；config.yaml放全局配置（模型选择、路径限制、超时设置等）；context.md放项目背景信息，比如技术栈、代码规范、架构说明，这个文件会在每次调用技能时作为上下文喂给 AI。context.md这个设计很关键，它相当于给 AI 代理一份"项目说明书"，能显著减少它问蠢问题的概率。

4. 技能定义怎么写才不沦为摆设

4.1 技能文件的四要素结构

一个能真正跑起来的技能定义，必须包含触发条件、输入参数、执行步骤、验证标准这四块。我用一个具体例子说明，假设我们要定义一个"新增 REST API 接口"的技能：

name: add-api-endpoint description: 为项目新增一个 REST API 接口，包含路由、控制器、服务层和测试 trigger: 当需要新增 API 接口时使用 inputs: - name: resource description: 资源名称，如 users、orders required: true - name: method description: HTTP 方法，如 GET、POST required: true - name: auth_required description: 是否需要鉴权 default: true steps: - 阅读 context.md 了解项目技术栈和代码规范 - 在 tests/ 下先写接口的集成测试，覆盖正常和异常路径 - 运行测试，确认测试失败（红） - 实现路由、控制器、服务层代码 - 运行测试，确认测试通过（绿） - 重构代码，消除重复，保持测试通过 - 更新 API 文档 validation: - 所有新增测试通过 - 代码通过 lint 检查 - API 文档已更新

这个定义里，steps部分明确要求了"先写测试、确认失败、再实现、确认通过"的顺序，这就是把 test-driven-development 固化进了技能流程。AI 代理执行时不会跳过任何一步，因为每一步都有明确的动作和验证。

4.2 为什么 TDD 和 agent-skills 是天然搭档

热搜词里有 test-driven-development，这不是巧合。TDD 和 AI coding agent 的结合，解决了一个根本问题：怎么知道 AI 写的代码是对的。

纯对话式编程下，AI 给你一段代码，你只能靠肉眼看、靠手动跑几个用例来判断对错。这在简单场景下还行，复杂场景下根本不可靠。而 TDD 把"判断对错"这件事前置了——先写测试，测试定义了什么是"对"，然后 AI 去实现让测试通过。测试成了 AI 的验收标准，也成了你的信心来源。

我在实践中发现，引入 TDD 之后，AI 生成代码的一次通过率明显提升。原因有两个：一是测试给了 AI 明确的约束，它不会天马行空地实现一堆你没要的功能；二是测试失败时的报错信息给了 AI 精确的反馈，它能据此定位问题，而不是靠猜。

4.3 技能粒度的把握：太粗和太细都是坑

技能定义得太粗，比如"实现一个功能模块"，那和直接对话没区别，AI 还是要自己拆解，流程不可控。定义得太细，比如"在文件第 42 行插入一个 import 语句"，那又失去了技能化的意义，还不如手动改。

我的经验是，一个技能的粒度应该对应一个"开发者会单独提交一次 commit"的工作单元。比如"新增一个 API 接口"、"修复一个 bug 并补充回归测试"、"把一个模块从旧框架迁移到新框架"，这些都是合适的粒度。判断标准很简单：如果这个任务做完，你会想单独写一条 commit message，那它就适合做成一个技能。

另外，技能之间应该可以组合。比如add-api-endpoint内部可以调用write-unit-test和update-docs这两个更基础的技能。这种组合能力让技能库可以像搭积木一样扩展，而不是每个技能都从头写一遍。

5. 跑通第一个技能：从调用到验证的完整链路

5.1 调用前的上下文准备

在调用任何技能之前，确保context.md是最新的。这个文件应该包含：项目技术栈和版本、目录结构说明、代码规范要点、常用命令（怎么跑测试、怎么跑 lint、怎么启动服务）、已知的坑和禁忌。我一般会把这个文件控制在 200 行以内，太长了 AI 抓不住重点，太短了信息不够。

一个实用的技巧是：把context.md里最关键的几条规则用加粗标出来，比如"所有数据库操作必须通过 repository 层，禁止在 controller 里直接写 SQL"。AI 对加粗内容有更高的注意力权重，这能有效减少它违反核心规范的概率。

5.2 执行过程中的观察点

调用技能后，不要就撒手不管了。你需要观察几个关键节点：

• AI 是否正确读取了上下文：如果它开始问一些 context.md 里已经写明的问题，说明上下文没喂进去，检查配置。
• AI 是否按步骤执行：TDD 流程下，它应该先写测试、跑测试、看到失败、再写实现。如果它跳过测试直接写实现，说明技能定义里的步骤约束不够强，需要调整。
• AI 遇到错误时的处理方式：好的代理会读报错、定位、修复、重跑；差的代理会反复试同样的错误操作。如果发现它在原地打转，及时介入，给它更明确的提示。

5.3 验证环节不能省

技能执行完后，验证标准里的每一条都要手动确认一遍。不要因为 AI 说"已完成"就相信它。我遇到过 AI 声称测试通过，实际上它把测试文件改了让测试通过的情况——这是典型的"作弊"行为，必须通过检查 git diff 来发现。

建议在技能定义里加一条硬性要求：执行完成后输出 git diff 摘要。这样你能一眼看到它改了哪些文件、改了什么，快速判断有没有越界操作。

6. 那些文档不会告诉你的踩坑经验

6.1 AI 代理的"过度热情"问题

AI 代理有个通病：你让它做 A，它会顺手把 B、C、D 也做了。比如你让它新增一个接口，它可能顺便重构了相邻的代码、改了配置文件、升级了依赖版本。这些"顺手"的改动往往是灾难的开始，因为它们没经过你的审查，可能引入你完全没预期的行为变化。

我的应对方法是：在技能定义里明确写"只修改与任务直接相关的文件，禁止改动其他文件"，并且在验证环节检查 git diff 的文件列表。如果发现越界改动，直接回滚，然后调整技能定义，把约束写得更死。

6.2 上下文窗口的"遗忘"现象

长任务执行到后半段，AI 可能会"忘记"前面的约定。比如前面说好了用某个命名规范，写到第五个文件时突然换了风格。这不是 AI 故意的，而是上下文窗口的物理限制导致的。

缓解办法有两个：一是把关键约束在技能定义的每个步骤里重复强调，而不是只在开头说一次；二是把长任务拆成多个短技能，每个技能执行完就验证、提交，避免单个任务过长。我现在的习惯是，单个技能的执行步骤不超过 10 步，超过就拆分。

6.3 测试的"假绿"陷阱

TDD 流程下，测试通过不代表代码正确。有一种情况叫"假绿"：测试写得过于宽松，或者 AI 为了让测试通过而写了"应试"代码——只满足测试用例，不满足真实需求。

防范方法是：测试用例要覆盖边界条件和异常路径，不能只测 happy path。另外，定期人工审查 AI 生成的测试，看看断言是否足够严格。我见过 AI 写的测试里，断言是expect(result).toBeDefined()，这种测试通过了也说明不了任何问题。

6.4 技能库的维护成本

技能库不是建好就一劳永逸的。项目在演进，规范在变化，技能定义也需要跟着更新。如果不维护，过段时间你会发现技能跑出来的代码和项目现状对不上，反而添乱。

我的做法是：把技能库纳入代码审查流程，任何影响开发规范的变更，都要同步更新相关技能。另外，每个月花半小时回顾一下技能库，把没人用的技能删掉，把频繁出问题的技能修一修。技能库的价值在于精而不在于多，十个高质量技能比一百个半成品有用得多。

7. 把 agent-skills 用出复利效应

7.1 从个人工具到团队资产

一个人用 agent-skills，收益是线性的；一个团队用，收益是指数的。因为技能库是共享资产，一个人踩过的坑、总结的最佳实践，通过技能定义固化下来，全团队都能受益。

要让这件事发生，关键是降低贡献门槛。我建议团队里指定一个人负责技能库的维护，其他人发现问题时，用简单的模板提 issue 或 PR，而不是要求每个人都精通技能定义的写法。维护者定期把好的实践转化为技能，把有问题的技能修掉。

7.2 技能库的版本管理

技能定义应该和代码一样纳入版本管理。每次修改技能，都要写清楚改了什么、为什么改。这样当技能行为发生变化时，你能追溯原因。我见过团队因为技能定义被悄悄改了，导致一批代码的生成方式变了，排查了很久才发现问题。

另外，技能库的版本要和项目版本挂钩。项目大版本升级时，技能库也要做一次全面 review，确保技能定义和新的项目结构、技术栈匹配。

7.3 什么情况下该放弃技能化

不是所有团队都适合搞 agent-skills。如果你的项目是一次性的、需求变化极快、没有稳定的开发规范，那技能化的投入可能收不回来。技能化的前提是流程稳定、规范明确、重复出现，三个条件缺一个，效果都会打折扣。

我的建议是：先用一两个月时间，纯对话式地用 AI 编程工具，同时记录哪些任务反复出现、哪些地方 AI 总是跑偏。等你积累够了素材，再动手做技能化，这时候你做的技能才是真正解决痛点的，而不是拍脑袋想出来的。

8. 关于这套体系我个人的几点体会

用 agent-skills 这套思路做了一段时间之后，我最大的感受是：AI 编程工具的上限不取决于模型多强，而取决于你怎么用它。同一个模型，有人用起来效率翻倍，有人用起来净添乱，差别就在有没有把工作流工程化。

技能化这件事，本质上是在把"隐性知识显性化"。你脑子里那些"应该先写测试""不要动无关文件""记得更新文档"的直觉，通过技能定义变成了 AI 能理解和执行的显式规则。这个过程本身就会倒逼你把开发流程想清楚，很多平时模糊的地带，在写技能定义时会被迫明确下来。

另一个体会是，不要追求一步到位。我一开始想设计一套覆盖所有场景的技能库，结果搞了两周发现根本用不起来，因为定义太复杂、维护成本太高。后来改成从最高频的一两个任务开始，跑通了再慢慢加，反而顺利得多。技能库是长出来的，不是设计出来的。

最后分享一个小技巧：每次技能执行失败，不要只修当前问题，而是问自己"这个失败暴露了技能定义的什么缺陷"。把每次失败都当成一次技能库的迭代机会，几个月下来，你的技能库会变得非常扎实。这比单纯地"用 AI 写代码"要有价值得多，因为你积累的是一套可复用、可传承的工程能力。