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 listfrontmatter 格式错误或目录位置不对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 里记录最后一次人工审查的日期。超过半年没审查的技能要么更新要么删除。技能和代码一样会腐烂需要维护。