1. 从“agent-skills”说起：为什么我们需要给AI编码代理装上一套技能系统
第一次看到agent-skills这个项目名的时候，我脑子里蹦出来的第一个念头是：这不就是给 AI coding agents 做的一套“技能包”吗？后来翻了一圈资料、自己动手跑了一遍，发现这个理解只对了一半。它更像是一套面向 AI 编码代理的技能描述规范 + CLI 工具链，核心目标是让 Claude Code、Cursor、Windsurf 这类工具在接到任务时，能按需加载对应的“技能说明书”，而不是把所有上下文一股脑塞进 prompt 里。
这件事为什么重要？因为只要你用过 Claude Code 或者类似的 AI coding agent，就一定遇到过两个极端：要么是模型不知道你的项目约定，写出来的代码风格完全不对路；要么是你把一大堆规范、文档、示例全塞进上下文，结果 token 烧得飞快，模型反而抓不住重点。agent-skills想解决的就是这个矛盾——把“技能”做成可发现、可加载、可组合的模块，让代理在需要的时候才去读对应的技能文件。
我自己的使用场景很典型：手头有几个长期维护的项目，每个项目都有自己的测试规范、提交信息格式、目录结构约定。以前每次开新会话都要重新交代一遍，现在把这些约定写成 skill 文件放在项目里，代理自己就能找到并遵守。这套东西适合谁？如果你已经在用 Claude Code、Cursor 这类工具做日常开发，或者正在搭建团队内部的 AI 编码工作流，那agent-skills值得花时间研究。如果你还没接触过 AI coding agent，建议先跑通 Claude Code 的基本流程再回来看，不然会有点抽象。
2. agent-skills 的整体设计与核心思路拆解
2.1 技能即文件：为什么选择 Markdown + 目录约定
agent-skills最核心的设计决策，是把“技能”定义成文件系统里的 Markdown 文件，而不是数据库记录、API 接口或者某种二进制格式。这个选择乍看很朴素，但仔细想想非常合理。
第一，Markdown 对人类和模型都友好。你写技能的时候是在写文档，模型读技能的时候也是在读文档，不需要任何中间转换层。第二，文件系统天然支持版本控制，技能可以跟着代码一起提交、一起 review、一起回滚。第三，目录约定让技能可以被自动发现，不需要额外的注册中心。
典型的技能目录结构长这样：
.claude/ skills/ test-driven-development/ SKILL.md examples/ red-green-refactor.md commit-convention/ SKILL.md api-design/ SKILL.md references/ rest-checklist.md每个技能一个目录，目录名就是技能标识，SKILL.md是技能的主文件。这种结构的好处是技能可以带附属资源，比如示例、检查清单、参考文档，代理在加载技能时可以按需读取这些附属文件，而不是一次性全读进来。
注意：技能目录的命名建议用 kebab-case，不要用空格或下划线。我试过用下划线命名，在某些工具链里会被当成非法标识符，排查了半天才发现是命名问题。
2.2 渐进式披露：解决上下文膨胀的关键机制
agent-skills最值得说的设计是渐进式披露（progressive disclosure）。这个概念在文档里可能一笔带过，但它是整个系统能跑起来的关键。
传统做法是把所有规范写进一个巨大的CLAUDE.md或者 system prompt，代理每次启动都全量加载。问题是项目一大，这个文件就膨胀到几千行，token 成本高不说，模型注意力还被稀释了。agent-skills的做法是分三层：
- 第一层：技能索引。代理启动时只加载所有技能的
name和description，通常几十个技能加起来也就几百 token。 - 第二层：技能主体。当代理判断某个技能和当前任务相关时，才去读对应的
SKILL.md全文。 - 第三层：附属资源。技能主体里如果引用了
examples/或references/下的文件，代理在需要细节时才进一步读取。
这个机制的效果非常明显。我实测过一个有 20 多个技能的项目，索引层大概 800 token，单次任务通常只会触发 1 到 3 个技能，实际加载量在 2000 到 4000 token 之间。如果全量加载，轻松突破 20000 token。
2.3 与 Claude Code 的集成方式
agent-skills和 Claude Code 的集成走的是约定优于配置的路线。Claude Code 本身支持读取项目根目录下的.claude/目录，agent-skills就把技能放在.claude/skills/下，Claude Code 启动时会自动扫描这个目录。
如果你用的是其他工具，比如 Cursor 或者自己搭的 agent 框架，agent-skills提供的 CLI 可以把技能索引导出成不同格式，方便接入。CLI 的基本用法：
# 列出当前项目所有技能 npx agent-skills list # 导出技能索引为 JSON npx agent-skills export --format json # 校验技能文件格式 npx agent-skills validatevalidate这个命令我强烈建议加到 CI 里。技能文件格式错了，代理加载时会静默失败，你根本不知道发生了什么。我踩过一次坑：SKILL.md的 frontmatter 里description字段写成了desc，结果那个技能从来没被触发过，查了两天才发现是字段名写错了。
3. 核心细节解析与实操要点
3.1 SKILL.md 的 frontmatter 怎么写才有效
每个SKILL.md开头都有一段 YAML frontmatter，这是技能能被正确索引的关键。最小可用版本长这样：
--- name: test-driven-development description: 当用户要求编写新功能、修复 bug 或重构代码时使用。指导代理遵循红-绿-重构循环，先写失败测试再写实现。 ---这里有两个字段必须认真对待。name是技能的唯一标识，建议和目录名保持一致。description是代理判断“要不要加载这个技能”的唯一依据，所以它必须同时说清楚什么时候用和做什么。
我见过很多写得不好的 description，比如“测试相关技能”或者“帮助写测试”。这种描述代理根本没法判断触发时机。好的 description 应该包含触发条件，比如“当用户要求编写新功能时”“当代码涉及数据库迁移时”“当需要生成 API 文档时”。
提示：description 建议控制在 50 到 150 字之间。太短信息不足，太长会占用索引层 token。我一般会写两句话，第一句说触发场景，第二句说技能内容。
3.2 技能主体的组织原则
frontmatter 之后就是技能主体，也就是代理真正会读到的内容。这部分怎么写，直接决定了技能好不好用。我的经验是遵循三个原则：
原则一：先给判断标准，再给操作步骤。代理需要知道“什么情况下该用这个技能”，而不是一上来就罗列步骤。比如 TDD 技能的开头应该是“当你准备写新功能时，先写一个会失败的测试”，而不是“第一步，创建测试文件”。
原则二：用具体例子代替抽象描述。“遵循良好的测试实践”这种话对代理没用。“测试函数名用should_xxx_when_yyy格式”才有用。我通常会在技能里放一两个正例和反例，代理模仿能力很强，看到例子就能照着做。
原则三：把长内容拆到附属文件。如果某个技能需要一份很长的检查清单，不要全塞进SKILL.md，而是放到references/checklist.md，在主体里用相对路径引用。代理需要时才会去读。
3.3 技能之间的组合与优先级
一个任务往往涉及多个技能。比如“给用户模块加一个导出功能”，可能同时触发test-driven-development、api-design、commit-convention三个技能。agent-skills本身不强制规定优先级，但实践中需要处理技能冲突。
我的做法是在技能主体里显式声明依赖和冲突。比如 TDD 技能里写一句“本技能优先于quick-fix技能，除非用户明确要求跳过测试”。这种声明不是给机器解析的，而是给代理读的，代理会根据自然语言描述来协调。
另外，技能数量多了之后，索引层的 description 质量就特别重要。我建议定期跑一次agent-skills list，看看有没有技能从来没被触发过。如果有，要么是 description 写得不好，要么是这个技能根本不需要存在。
4. 实操过程与核心环节实现
4.1 从零搭建一个技能：以 TDD 技能为例
下面完整走一遍创建一个技能的过程。假设我们要为项目添加一个test-driven-development技能。
第一步，创建目录和文件：
mkdir -p .claude/skills/test-driven-development touch .claude/skills/test-driven-development/SKILL.md第二步，写 frontmatter：
--- name: test-driven-development description: 当用户要求实现新功能、修复 bug 或重构现有代码时使用。指导代理遵循红-绿-重构循环，确保每次代码变更都有对应的测试覆盖。 ---第三步，写技能主体。我的模板通常是这样的结构：
## 何时使用 当任务涉及以下任一情况时，加载本技能： - 实现新的业务逻辑 - 修复已报告的 bug - 重构现有函数或模块 ## 核心循环 1. 红：先写一个测试，运行它，确认它失败。失败信息必须是因为功能未实现，而不是语法错误。 2. 绿：写最少的代码让测试通过。不要提前优化，不要添加测试未覆盖的功能。 3. 重构：在测试保持通过的前提下，清理代码结构。 ## 测试命名约定 - 使用 `should_<预期行为>_when_<条件>` 格式 - 每个测试只验证一个行为 - 测试文件放在与被测文件相同的目录下，命名为 `<模块名>.test.<扩展名>` ## 反例 不要这样写测试： def test_user(): user = create_user() assert user is not None 这个测试没有验证任何具体行为，无法在功能回归时提供保护。 ## 参考 详细的红-绿-重构示例见 `examples/red-green-refactor.md`。第四步，添加附属示例文件：
mkdir -p .claude/skills/test-driven-development/examples在examples/red-green-refactor.md里放一个完整的代码示例，展示从失败测试到通过测试的完整过程。
第五步，校验：
npx agent-skills validate如果输出没有报错，说明技能格式正确。然后启动 Claude Code，让它做一个需要写测试的任务，观察它是否加载了这个技能。
4.2 技能索引的生成与调试
agent-skills的 CLI 可以生成技能索引，方便你检查代理实际看到的内容：
npx agent-skills export --format markdown输出大概是这样：
Available skills: - test-driven-development: 当用户要求实现新功能、修复 bug 或重构现有代码时使用... - commit-convention: 当用户要求提交代码或编写提交信息时使用... - api-design: 当任务涉及设计或修改 HTTP API 时使用...这个输出就是代理启动时看到的索引层。如果你发现某个技能没出现在这里，说明 frontmatter 有问题。如果出现了但代理从来不加载，说明 description 的触发条件写得不够明确。
我调试技能触发时有个小技巧：在 Claude Code 里直接问“你现在有哪些技能可用”，它会列出当前加载的技能索引。然后给它一个任务，看它实际加载了哪些技能。如果加载的技能和你预期不符，就回去改 description。
4.3 把技能接入 CI 流程
技能文件也是代码，应该纳入版本控制和 CI 检查。我在项目里加了这么一段 CI 配置：
- name: Validate agent skills run: npx agent-skills validate - name: Check skill index size run: | SIZE=$(npx agent-skills export --format json | wc -c) if [ "$SIZE" -gt 8000 ]; then echo "技能索引过大，请精简 description" exit 1 fi第一个检查保证技能格式正确，第二个检查防止索引层膨胀。索引层超过 8000 字符（大约 2000 token）就该考虑合并或精简技能了。
注意：
agent-skills validate默认只检查 frontmatter 格式，不检查 Markdown 内容。如果你在技能里引用了附属文件，最好自己写个脚本检查文件是否存在，否则代理加载时会遇到死链。
5. 常见问题与排查技巧实录
5.1 技能不触发怎么办
这是最常见的问题。代理明明在做相关任务，但就是不加载对应的技能。排查顺序如下：
| 排查项 | 检查方法 | 常见原因 |
|---|---|---|
| 技能是否被索引 | 运行agent-skills list | frontmatter 格式错误或目录位置不对 |
| description 是否明确 | 读一遍 description | 触发条件太模糊，代理无法判断 |
| 技能名是否冲突 | 检查是否有重名技能 | 目录名重复导致覆盖 |
| 代理是否支持技能 | 查看工具文档 | 部分工具需要显式开启技能功能 |
我遇到最多的情况是 description 写得太泛。比如“帮助编写代码”这种描述，代理根本不知道什么时候该用。改成“当用户要求实现新功能时使用”之后，触发率立刻上来了。
5.2 技能加载了但代理不遵守
有时候技能被正确加载了，但代理的行为还是不符合技能里的约定。这通常是因为技能主体写得太抽象，或者和 system prompt 里的指令冲突。
解决办法有两个。第一，在技能里加具体例子，代理对例子的遵循度远高于抽象规则。第二，检查是否有更高优先级的指令覆盖了技能。比如 system prompt 里写了“优先保证代码简洁”，而技能里要求“先写测试”，代理可能会选择跳过测试。
我的经验是，技能里的规则要写得足够具体，具体到代理没有解释空间。比如不要写“写清晰的提交信息”，而是写“提交信息第一行不超过 50 字符，使用祈使句，例如add user export endpoint”。
5.3 技能太多导致索引膨胀
项目跑久了，技能会越加越多。索引层膨胀到一定程度，代理的判断准确率反而会下降。我的做法是定期做技能审计：
- 合并功能重叠的技能。比如
unit-testing和integration-testing可以合并成testing。 - 删除长期不触发的技能。如果一个技能三个月没被加载过，大概率是不需要的。
- 把低频技能移到
optional/子目录，默认不索引，需要时手动启用。
提示：索引层控制在 1500 token 以内比较理想。超过这个量，代理在判断该加载哪个技能时就开始犹豫了。
5.4 跨工具兼容性问题
agent-skills虽然主要面向 Claude Code，但技能文件本身是纯 Markdown，理论上任何 agent 都能读。实际接入其他工具时，主要差异在索引生成和加载机制上。
如果你用的是自建 agent 框架，可以直接读.claude/skills/目录，解析 frontmatter 生成索引。agent-skills的 CLI 也支持导出 JSON 格式，方便程序化处理：
npx agent-skills export --format json > skills-index.json然后在你的 agent 启动逻辑里加载这个 JSON，把索引注入 system prompt，把技能主体读取逻辑接到工具调用上。这套流程我帮朋友接过一次，大概半天就能跑通。
6. 我踩过的坑和几条实用建议
技能文件里的路径引用要用相对路径，不要用绝对路径。我一开始写了绝对路径，换台机器就全挂了。相对路径的基准是技能目录本身，比如examples/foo.md指的是技能目录下的examples/foo.md。
description 里不要用“等”“之类”“相关”这种模糊词。代理对这类词的处理很不稳定，有时候会过度触发，有时候完全不触发。把触发条件写死，比如“当用户提到测试、spec、覆盖率时使用”。
技能主体尽量控制在 500 行以内。超过这个长度，代理读取时可能会截断，或者注意力分散到不重要的细节上。长内容拆到附属文件，主体只保留核心规则和判断标准。
定期用agent-skills validate检查，并且把这个命令加到 pre-commit hook 里。技能文件格式错误是静默失败，不检查的话你可能几个月都发现不了。
最后分享一个我最近在用的技巧：给每个技能加一个last-reviewed字段在 frontmatter 里，记录最后一次人工审查的日期。超过半年没审查的技能，要么更新要么删除。技能和代码一样，会腐烂，需要维护。
