1. 从"agent-skills"说起：为什么这个项目值得单独聊

第一次看到agent-skills这个标题，我脑子里蹦出来的不是某个具体工具，而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套"插件化的能力说明书"，让 Claude Code 这类命令行里的智能体，在写代码、跑测试、改配置、查日志的时候，不用每次从零开始摸索，而是直接调用已经沉淀好的技能模块。

我接触 Claude Code 有一段时间了，从最早的命令行版本到后来在 VS Code 里挂插件，中间踩过的坑不算少。最开始我以为它就是个"会写代码的终端助手"，用久了才发现，真正拉开效率差距的不是模型本身，而是你有没有给它准备好一套可复用的技能体系。agent-skills这个项目，本质上就是在解决这个问题：把零散的操作经验，抽象成 agent 能识别、能调用、能组合的 skill。

它适合谁？三类人最该关注。第一类是已经在用 Claude Code、但每次都要重复交代背景的开发者；第二类是想把团队内部的编码规范、测试流程固化下来的技术负责人；第三类是刚入门 AI coding agent、还在纠结"这东西到底能干嘛"的新手。不管你是哪一类，理解 skill 的组织方式，比记住某个具体命令重要得多。

这篇文章我不打算写成官方文档的复述，而是按我自己实际折腾的顺序，把agent-skills的设计思路、核心结构、落地步骤、以及那些文档里不会写的坑，一条条摊开讲。你看完至少能做到：知道 skill 该长什么样、怎么让 agent 正确加载、以及为什么 test-driven-development 这类流程特别适合做成 skill。

2. agent-skills 的整体设计与思路拆解

2.1 为什么是"技能"而不是"提示词"

很多人第一反应是：这不就是写一段更长的 prompt 吗？我一开始也这么想，直到我把同一段逻辑分别用 prompt 和 skill 实现了一遍，才发现差别很大。

Prompt 是一次性的，你这次对话里交代清楚了，下次开新会话，agent 又忘了。而 skill 是持久化的、可被检索的。它通常以文件形式存在项目目录里，agent 在需要的时候主动去读、去匹配。这就好比：prompt 是你临时口头交代同事一件事，skill 是你写进团队 wiki 的标准操作流程。前者靠记性，后者靠制度。

更关键的是，skill 有结构。一个合格的 skill 一般包含几个部分：触发条件（什么时候用）、输入输出约定、具体步骤、以及边界情况处理。这种结构让 agent 能判断"当前任务该不该调用这个 skill"，而不是无脑把所有上下文都塞进去。上下文窗口是有限的资源，skill 的按需加载机制，本质上是在做上下文管理。

2.2 核心设计原则：单一职责与可组合

我翻了不少同类项目的组织方式，发现做得好的agent-skills都有一个共同点：每个 skill 只干一件事。比如"运行单元测试"是一个 skill，"根据失败用例生成修复建议"是另一个 skill，"提交前检查代码风格"又是第三个。它们可以串联，但不会揉成一坨。

这个原则听起来简单，落地时特别容易违反。我自己就犯过错误：一开始写了个"大而全"的 skill，想让它同时处理测试、构建、部署。结果 agent 每次调用都要读一大堆无关内容，反而变慢、变笨。后来拆成三个独立 skill，命中率和执行准确度都上去了。

可组合性还带来一个好处：复用。测试相关的 skill 在多个项目里都能用，只要目录结构一致，直接拷过去就行。这也是为什么agent-skills这类项目往往配套一个 CLI——用命令行管理 skill 的安装、更新、启用禁用，比手动复制文件靠谱得多。

2.3 和 test-driven-development 的天然契合

热搜词里出现了test-driven-development，这不是巧合。TDD 的流程本身就是高度结构化的：先写失败测试、再写最小实现、再重构。这种"步骤明确、每步有明确输入输出"的流程，简直是为 skill 量身定做的。

我实测下来，把 TDD 做成 skill 之后，agent 的行为稳定了很多。以前它经常跳过测试直接写实现，现在只要任务描述里出现"新功能"或"修复 bug"，它就会先去找测试相关的 skill，按流程走。这不是模型变聪明了，而是流程被固化下来了。人也是一样，靠自觉容易偷懒，靠清单就稳得多。

提示：设计 skill 时，优先考虑那些"步骤固定、容易漏步骤"的流程。TDD、代码审查、发布检查清单，都是高价值场景。

3. 核心细节解析与实操要点

3.1 一个 skill 的最小结构长什么样

我不打算给你一个"标准答案"，因为不同项目组织方式不一样。但根据我的实践，一个能跑起来的 skill 至少要有这么几块内容，我用一个"运行测试并汇总结果"的例子来说明。

首先是元信息：skill 的名字、一句话描述、以及触发关键词。这部分决定了 agent 能不能在合适的时机找到它。名字要短，描述要准，关键词要覆盖用户可能的各种说法。比如"跑测试""执行用例""test""run tests"都该能命中。

其次是前置条件：执行这个 skill 需要什么。比如"项目根目录存在测试配置""依赖已安装"。写清楚前置条件，能避免 agent 在环境没准备好的时候瞎执行。

然后是执行步骤：这是主体，要写成 agent 能照着做的有序列表。每一步尽量具体，比如"在项目根目录执行npm test"而不是"运行测试"。模糊的指令会让 agent 自由发挥，结果不可控。

最后是输出约定：告诉 agent 执行完之后该怎么汇报。是只报通过/失败，还是要列出失败用例、附上错误摘要？这个约定直接决定了你后续能不能顺畅地接上下一个 skill。

3.2 触发机制：让 agent 在对的时候想起你

这是整个体系里最容易被低估的部分。我见过太多人把 skill 写得很好，但 agent 就是不用，原因几乎都出在触发机制上。

触发一般有两种思路。一种是关键词匹配：skill 描述里包含某些词，agent 扫描任务描述时命中就加载。这种方式简单直接，但容易误触发或漏触发。另一种是显式引用：在项目的主配置里列出可用 skill，agent 每次启动时先读一遍清单，再按需深入。这种方式更可控，但需要维护清单。

我的建议是两者结合。核心 skill 用显式清单保证一定被看到，边缘 skill 用关键词匹配按需加载。另外，触发描述里要写反例——明确说什么情况下不要用这个 skill。这一条特别有用，能大幅减少误调用。比如"本 skill 仅用于单元测试，不用于端到端测试"，一句话就能挡掉很多错误场景。

3.3 参数与上下文传递的坑

skill 之间要串联，就得传递数据。这里有个很现实的坑：agent 不会自动记住上一个 skill 的输出，除非你显式告诉它。

我的做法是在 skill 的输出约定里，明确要求把关键结果写成结构化格式，比如一个简短的 JSON 或者固定字段的文本块。下一个 skill 的前置条件里，就声明"需要上一个 skill 的输出作为输入"。这样 agent 在串联时，会主动去引用，而不是重新猜。

还有一个坑是路径问题。skill 里如果写死了绝对路径，换个环境就废了。统一用相对于项目根目录的路径，并且在前置条件里声明"假设当前工作目录为项目根目录"。这一条能省掉大量"为什么在我机器上跑不通"的排查时间。

注意：skill 里尽量避免依赖具体的人名、机器名、临时目录。任何环境相关的东西，都应该是参数或前置条件，而不是硬编码。

4. 实操过程与核心环节实现

4.1 环境准备与目录规划

先说环境。Claude Code 的安装方式在不同系统上略有差异，Mac 和 Ubuntu 都有对应的安装流程，VS Code 里也可以挂插件。这部分官方文档写得比较清楚，我就不逐条复述了。重点说目录规划，因为这是agent-skills能不能用好的地基。

我的习惯是在项目根目录下建一个专门的目录来放 skill，比如.agent/skills/。每个 skill 一个子目录，目录名就是 skill 名，里面放一个主文件（通常是 markdown 或 yaml）。这样结构清晰，agent 扫描的时候也容易定位。

为什么不把所有 skill 塞进一个文件？因为那样加载时无法按需读取，等于每次都把全部内容塞进上下文，浪费窗口。分目录之后，agent 可以先读目录列表，再决定深入读哪个。这个"先看目录再看内容"的两段式加载，是我实测下来最省上下文的方式。

4.2 用 CLI 管理 skill 的安装与更新

热搜里提到skills CLI，这类工具的价值在于批量管理。手动复制文件在单项目里还行，多项目就崩了。CLI 一般提供几个核心命令：安装（从某个源拉取 skill 到本地）、列出（看当前有哪些 skill）、启用/禁用（控制哪些生效）、更新（同步最新版本）。

我建议把 skill 源做成一个独立的仓库，团队共享。每个人本地用 CLI 拉取，需要改的时候改源仓库，再统一更新。这样避免了"张三的 skill 和李四的不一样"这种混乱。CLI 的具体命令各家实现不同，但思路是一致的：把 skill 当依赖管理，而不是当散落的文件。

4.3 手把手写一个 TDD skill

光说理论没意思，我带你走一遍我实际写 TDD skill 的过程。

第一步，定名字和描述。名字叫tdd-workflow，描述写"当需要实现新功能或修复 bug 时，按测试先行的流程推进"。关键词覆盖"新功能""修复""实现""feature""bugfix"。

第二步，写前置条件。声明需要项目已有测试框架配置，且当前工作目录为项目根目录。

第三步，写步骤。我把它拆成五步：先根据需求写一个会失败的测试；运行测试确认它确实失败（这一步很多人会跳过，但很重要，能验证测试本身有效）；写最小实现让测试通过；再运行测试确认通过；最后重构并再次运行测试。每一步都写清楚具体命令和预期结果。

第四步，写输出约定。要求 agent 在每步结束后汇报当前状态，并在最后给出一个总结：新增了哪些测试、修改了哪些文件、最终测试结果。

第五步，写边界情况。比如"如果测试框架未配置，先提示用户配置，不要自行安装"；"如果测试一直无法通过，最多重试三次后停下来汇报"。

写完这个 skill 之后，我拿一个真实的小需求测了一遍。以前 agent 经常直接写实现，现在它会先写测试，而且会主动运行确认失败。这个行为变化，就是 skill 带来的确定性。

4.4 参数计算与选择：上下文预算怎么估

这里补充一个很多人忽略的点：上下文预算。skill 不是越多越好，每个 skill 被加载都会占用窗口。我的经验是，单个 skill 的主文件控制在几百行以内，超过就该拆。

粗略估算：一个中等复杂度的 skill，加载后大概占用几百到一千多 token。如果你同时激活十几个 skill，光 skill 本身就可能吃掉上万 token，留给实际任务的空间就紧张了。所以我的原则是：常用 skill 常驻，冷门 skill 按需。CLI 的启用/禁用功能就是干这个的。

5. 常见问题与排查技巧实录

5.1 agent 不调用我的 skill 怎么办

这是最高频的问题。排查顺序我总结成一张表，按可能性从高到低排。

我踩过最典型的一个坑是：skill 文件放在了项目根目录，但 agent 的工作目录被设成了子目录，结果扫描不到。后来统一把 skill 放在工作目录能覆盖到的位置，问题就没了。所以路径一致性要反复确认。

5.2 skill 之间互相打架

当你 skill 多了，难免出现两个 skill 都想处理同一类任务的情况。比如一个"通用测试"skill 和一个"TDD"skill，都可能在"写测试"时被触发。

解决办法是明确优先级和适用边界。在描述里写清楚：TDD skill 用于新功能开发，通用测试 skill 用于已有代码的测试补充。如果还是冲突，就在主配置里给 skill 排个序，agent 按顺序匹配，命中即停。这个排序机制很多 CLI 都支持，值得用起来。

5.3 更新 skill 后行为没变

有时候你改了 skill 内容，但 agent 还是老样子。原因通常是缓存。有些实现会把 skill 内容缓存起来，改完需要重启会话或者手动刷新。我的习惯是改完 skill 后，开一个全新会话验证，避免被旧上下文干扰。

另外，如果你用的是共享源，改完记得推送到源仓库，本地再拉一次。我见过有人改了本地文件，以为团队都生效了，结果别人拉的是旧版本，白忙一场。

5.4 独家避坑技巧汇总

• 先写反例再写正例：描述里先说"什么时候不用"，能挡掉大部分误触发。
• 步骤里带命令：能写具体命令就别写"运行测试"，越具体越稳。
• 输出结构化：要求 agent 用固定格式汇报，方便后续 skill 引用。
• 小步验证：每加一个 skill 就单独测一次，别攒一堆再一起调。
• 版本化：skill 也要有版本概念，改之前先备份，出问题能回滚。

提示：把 skill 当成代码来管理——有版本、有测试、有审查。这样它的可靠性会高一个量级。

6. 我的实际体会与后续扩展方向

折腾agent-skills这段时间，我最大的感受是：AI coding agent 的上限，很大程度上取决于你给它搭的脚手架。模型能力是底座，但 skill 体系决定了它能不能稳定地、可复现地完成复杂任务。同样一个 Claude Code，有人用起来像个高级补全，有人用起来像个能独立推进任务的助手，差距往往就在这套技能体系上。

我现在的做法是，每完成一个重复性任务，就顺手把它抽象成一个 skill。日积月累，agent 越来越懂我的项目，我也越来越少重复交代背景。这个正循环一旦转起来，效率提升是肉眼可见的。

后续我打算往两个方向扩展。一是把 skill 和项目的 CI 流程打通，让 agent 在提交前自动跑一遍检查 skill；二是做一套 skill 的测试机制，确保改了 skill 之后行为符合预期，而不是靠人肉验证。这两块目前还在摸索，等有成熟经验了再单独写一篇。

如果你也在用 Claude Code 这类工具，我的建议是从一个小 skill 开始，别一上来就追求大而全。先让一个流程稳定下来，尝到甜头，再逐步铺开。踩坑是必然的，但每踩一个坑，你对这套体系的理解就深一层。