1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 当可训练员工来管理的技能体系。标题里的agent指向的是执行主体——AI 编码代理skills指向的是它被赋予的能力集合。两者拼在一起本质上回答了一个很实际的问题当 AI 已经能写代码、能跑终端命令之后我们到底该用什么方式把人的工程经验喂给它让它稳定地按团队规范干活这个问题的背景是最近一年 AI coding agent 从补全工具进化成了能自己开终端、自己跑测试、自己改文件的协作角色。以 Claude Code 为代表的命令行代理已经可以在项目目录里读文件、执行命令、跑测试、提交改动。但很多人上手之后会发现一个尴尬的现实模型本身很聪明可一旦进入真实项目它就开始自由发挥——命名风格不统一、测试写得敷衍、改完不跑验证、遇到报错就绕路。这不是模型不行而是缺少一套结构化的技能约束。agent-skills要解决的正是这个断层。它把一个合格的工程师在这个项目里应该怎么做拆成一条条可复用的技能单元让 agent 在特定场景下加载特定技能从而把行为收敛到可预期的范围。关键词里出现的test-driven-development就是最典型的例子它不是让 agent记得写测试而是把 TDD 的完整流程——先写失败测试、再写最小实现、再重构——固化成一个技能agent 每次进入开发任务时按这个流程走。这篇文章适合三类人看一是刚开始用 Claude Code 这类命令行代理、还在摸索怎么让它听话的开发者二是团队里想把 AI 编码规范沉淀下来的技术负责人三是单纯好奇skills 这种组织方式到底比一堆提示词强在哪的工程爱好者。我会从技能的本质、目录结构、加载机制、TDD 技能拆解、CLI 工具链、以及实际踩坑几个角度把agent-skills这套东西讲透。2. 技能不是提示词agent-skills 的核心抽象2.1 提示词和技能的本质区别很多人第一次接触 skills 概念时会下意识把它等同于更长的系统提示词。这个理解偏差会导致后面所有设计都走偏。我用一个类比说清楚提示词像是你临时口头交代同事一件事技能像是公司写进 SOP 手册的标准作业流程。临时交代的问题是它依赖上下文、依赖你当时说清楚没有、依赖对方记不记得。你这次说记得写测试下次忘了说agent 就不写了。而技能是持久化的、可被检索的、有明确触发条件的。它不依赖你每次重复而是 agent 在识别到当前任务是开发新功能时主动去加载对应的技能文档。从工程角度看这个区别带来三个实际收益可复用一个 TDD 技能写一次所有走开发流程的任务都能用不用在每个提示词里重复。可版本化技能是文件能进 Git能 review能回滚。提示词散落在聊天记录里改了什么根本追溯不了。可组合一个任务可以同时加载代码风格技能 测试技能 提交规范技能像搭积木一样组合出完整行为。2.2 技能单元应该包含哪些要素一个设计良好的技能不是一段散文式的说明而是有固定结构的。根据我在实际项目里沉淀的经验一个技能至少应该包含这几块要素作用缺失后的后果触发条件说明什么场景下该加载这个技能agent 不知道何时用技能形同虚设目标描述一句话说清这个技能要达成什么agent 理解偏差执行方向跑偏操作步骤有序的具体动作清单agent 自由发挥流程不稳定验证标准怎么判断做完了、做对了改完不验证问题被掩盖反例/禁忌明确不能做什么踩已知的坑重复犯错这个结构看起来简单但真正写起来最难的是触发条件和验证标准。触发条件写太宽技能到处被加载干扰正常任务写太窄该用的时候用不上。验证标准则是区分玩具技能和生产技能的分水岭——没有验证标准的技能agent 做完自己都不知道对不对。2.3 为什么用 Markdown 而不是代码agent-skills这类仓库普遍用 Markdown 来写技能而不是 JSON 或 YAML 配置。这个选择背后有很实际的考虑。Markdown 对模型来说是最自然的输入格式它能理解标题层级、列表、代码块、引用块这些结构而且能容忍一定程度的自然语言描述。如果用严格的 JSON schema写技能的人会被格式绑死反而写不出为什么这么做这种关键的上下文。但 Markdown 也有代价它没有强制的字段校验容易写得松散。所以实践中通常会在仓库里放一个技能模板文件规定好标题层级和必备小节让每个技能保持结构一致。这样既保留了自然语言的表达力又有一定的规范性。提示如果你打算在自己的项目里引入 skills第一件事不是写技能而是先定一个技能模板。模板定好了后面所有人写的技能才能被 agent 稳定解析。3. 目录结构与技能加载机制3.1 一个可落地的目录布局agent-skills这类仓库的目录结构直接决定了 agent 能不能高效找到并加载技能。我见过不少项目把技能全堆在一个文件夹里结果几十个文件平铺agent 检索时经常加载错。一个更合理的布局是按领域 场景分层agent-skills/ ├── README.md ├── templates/ │ └── skill-template.md ├── skills/ │ ├── development/ │ │ ├── test-driven-development.md │ │ ├── code-review-checklist.md │ │ └── refactoring-guide.md │ ├── workflow/ │ │ ├── git-commit-convention.md │ │ └── pr-description.md │ └── debugging/ │ ├── root-cause-analysis.md │ └── log-investigation.md └── cli/ └── skills.js这个布局的关键在于一级目录按技能的大类分二级目录放具体技能文件。development 放开发相关的workflow 放流程相关的debugging 放排查相关的。agent 在识别任务类型后能快速定位到对应目录而不是在几十个平铺文件里瞎找。3.2 技能是怎么被加载的这里要澄清一个常见误解skills 不是自动生效的魔法。它需要一个加载机制通常有两种模式。第一种是显式加载。用户在对话里明确说用 TDD 技能来做这个功能agent 就去读对应的技能文件然后按里面的步骤执行。这种方式可控性最强适合关键任务。第二种是条件触发。agent 在分析任务时根据任务描述匹配技能里的触发条件自动加载。比如任务里出现修复这个 bugagent 就去找 debugging 目录下的技能。这种方式更顺滑但对触发条件的写法要求很高。实际项目里两种模式通常混用。核心流程用显式加载保证稳定边缘场景用条件触发提升效率。skills CLI这类工具的价值就是提供一个统一的入口让用户能列出所有可用技能、查看某个技能的详情、手动触发加载。3.3 加载顺序和优先级当多个技能同时匹配时谁先谁后是个真问题。比如一个任务既涉及开发又涉及提交TDD 技能和 commit 规范技能都要用。这时候需要一个优先级规则。我的做法是在技能文件头部加一个priority字段用注释或 frontmatter 都行数值越小越先加载。流程类技能如提交规范优先级高因为它们约束的是什么时候做什么具体实现类技能优先级低因为它们约束的是具体怎么做。这样 agent 先确定流程框架再填充实现细节逻辑上更顺。注意不要给所有技能都设成最高优先级那样等于没有优先级。真正需要抢占的只有少数几个流程性技能。4. TDD 技能拆解把工程纪律写成 agent 能执行的步骤4.1 为什么 TDD 是 skills 的最佳样本关键词里test-driven-development排在很靠前的位置这不是偶然。TDD 是软件工程里少有的流程极其明确、验证标准极其清晰的实践天然适合写成技能。它的红-绿-重构三步每一步都有明确的输入、动作、输出几乎没有模糊地带。更重要的是TDD 恰好能治 agent 的一个通病改完不验证。很多 agent 写完代码就宣布完成根本不跑测试。而 TDD 技能强制要求先写一个会失败的测试这就把验证环节前置了——测试跑不通agent 就没法进入下一步。4.2 一个 TDD 技能的完整结构我把实际用过的 TDD 技能结构拆给你看。它大致长这样# Test-Driven Development ## 触发条件 - 任务是新增功能或修改现有功能的行为 - 项目已有测试框架jest / pytest / go test 等 ## 目标 用红-绿-重构循环实现功能确保每一步都有测试覆盖。 ## 步骤 1. 阅读需求写出一个描述期望行为的最小测试 2. 运行测试确认它失败红 3. 写最少的代码让测试通过绿 4. 运行全部测试确认没有破坏其他功能 5. 在测试保护下重构代码 6. 重复 1-5 直到功能完成 ## 验证标准 - 每个新增行为都有对应测试 - 最终测试全绿 - 重构后测试仍然全绿 ## 禁忌 - 不允许先写实现再补测试 - 不允许跳过确认测试失败这一步 - 不允许为了让测试通过而修改测试断言这个结构里最容易被忽视但最关键的是第 2 步确认测试失败。很多人包括 agent会觉得这步多余——测试都写了直接写实现不就行了但确认失败是 TDD 的灵魂它证明你的测试确实在检验新行为而不是一个永远为真的空断言。如果测试一开始就通过说明要么功能已经存在要么测试写错了。4.3 agent 执行 TDD 时的真实表现我在实际项目里让 agent 跑 TDD 技能观察到的行为很有意思。当技能写得好时agent 会老老实实先写测试、跑一遍、看到红色、再写实现。但当技能里确认失败这一步写得含糊时agent 十有八九会跳过它直接写实现然后跑测试看到绿色就宣布完成。这说明一个道理agent 会严格执行你写清楚的步骤也会严格执行你省略的步骤。技能文档的完整度直接决定 agent 行为的完整度。这也是为什么我一直强调技能要有验证标准和禁忌两块——它们是在给 agent 划边界。另一个观察是agent 在重构阶段容易过度发挥。它可能把重构理解成顺便优化一下架构然后改动范围失控。所以 TDD 技能里最好明确写一句重构仅限消除重复和改善命名不改变外部行为把范围锁死。5. skills CLI让技能可发现、可调用、可管理5.1 CLI 存在的意义有人会问技能就是一堆 Markdown 文件直接让 agent 读不就行了为什么还要一个 CLI这个问题问得好。CLI 的价值不在于读文件而在于提供统一的发现和调用接口。想象一下你的仓库里有三十个技能散落在不同目录。用户想知道有没有处理数据库迁移的技能靠翻目录很累。CLI 提供skills list命令一次性列出所有技能和它们的触发条件用户扫一眼就知道有什么可用。再比如用户想手动触发某个技能skills run test-driven-development就能把技能内容注入当前会话不用手动复制粘贴。5.2 一个最小可用的 CLI 设计skills CLI不需要做得很复杂核心就三个命令命令作用典型用法skills list列出所有技能及触发条件快速了解可用技能skills show name显示某个技能的完整内容查看技能细节skills run name加载技能到当前会话手动触发执行实现上用 Node.js 写一个脚本遍历skills/目录解析每个 Markdown 文件的标题和触发条件输出成列表。run命令则是把文件内容读出来通过标准输出或 API 传给 agent。// cli/skills.js 的核心逻辑示意 const fs require(fs); const path require(path); function listSkills(dir) { const skills []; const categories fs.readdirSync(dir); for (const category of categories) { const categoryPath path.join(dir, category); if (!fs.statSync(categoryPath).isDirectory()) continue; for (const file of fs.readdirSync(categoryPath)) { if (!file.endsWith(.md)) continue; const content fs.readFileSync(path.join(categoryPath, file), utf8); const title content.match(/^#\s(.)$/m)?.[1] || file; skills.push({ category, file, title }); } } return skills; }这段代码很朴素但它解决了一个真实痛点让技能从藏在文件系统里变成可被程序枚举的资源。有了这个基础后面可以扩展出按关键词搜索、按标签过滤、自动匹配任务等功能。5.3 CLI 和 agent 的协作方式CLI 和 agent 之间怎么协作有两种思路。一种是 CLI 作为独立工具用户手动调用把输出贴给 agent。另一种是 CLI 作为 agent 可调用的工具agent 在执行任务时自己调用skills list来发现技能。第二种更优雅但需要 agent 支持工具调用。以 Claude Code 这类支持终端命令的 agent 为例它可以直接执行node cli/skills.js list拿到技能列表然后决定加载哪个。这就形成了一个闭环agent 自己发现技能、自己加载、自己执行。提示如果你用的 agent 支持执行终端命令把 skills CLI 注册成一个可调用工具能大幅提升技能的使用率。手动贴技能的方式用几次就懒得用了。6. 把 skills 接入 Claude Code 这类命令行代理6.1 接入前要搞清楚的事在动手接入之前有几个概念要先理清。Claude Code 这类命令行代理的工作方式是在你的项目目录里运行能读写文件、执行命令。它读取项目里的配置文件比如CLAUDE.md作为上下文。所以接入 skills 最自然的方式就是在项目根目录放一个入口文件告诉 agent 技能在哪里、怎么用。这个入口文件通常叫CLAUDE.md或AGENTS.md内容大致是# 项目 Agent 配置 ## 技能库 本项目使用 agent-skills 管理技能技能位于 skills/ 目录。 ## 使用方式 - 开发新功能时加载 skills/development/test-driven-development.md - 提交代码前加载 skills/workflow/git-commit-convention.md - 排查问题时加载 skills/debugging/root-cause-analysis.md ## 技能发现 运行 node cli/skills.js list 查看所有可用技能。这个文件的作用是给 agent 一个地图。它不需要包含所有技能内容只需要指明方向。agent 在需要时自己去读具体技能文件。6.2 环境准备中的几个细节接入过程中有几个容易忽略的细节。第一是路径问题。agent 执行命令时的工作目录可能和你手动执行时不一样。CLI 脚本里最好用绝对路径或基于__dirname解析避免在我机器上能跑的尴尬。第二是权限问题。agent 执行终端命令需要相应权限。在配置里要确保 agent 有读取技能目录、执行 node 脚本的权限。如果权限不足agent 会静默失败你甚至不知道技能没加载。第三是模型选择。不同模型对长上下文技能文档的理解能力差异很大。技能文档动辄几百上千字如果模型上下文窗口小加载几个技能就爆了。实践中建议把单个技能控制在 500 字以内把详细示例放到单独的参考文件里按需加载。6.3 验证接入是否成功接入完成后怎么确认技能真的生效了我的做法是设计一个冒烟测试给 agent 一个明确需要某技能的任务观察它的行为是否符合技能描述。比如测试 TDD 技能就给 agent 一个实现一个字符串反转函数的任务。如果技能生效agent 应该先写测试、跑测试、看到失败、再写实现。如果它直接写实现说明技能没加载成功。这个验证步骤很重要因为技能加载失败往往是静默的不主动验证根本发现不了。7. 实操中踩过的坑和应对7.1 技能写太细agent 反而僵化我一开始写技能恨不得把每个细节都写进去结果发现 agent 变得很死板。比如我在代码风格技能里规定了变量名必须用驼峰agent 遇到一个必须用下划线的场景比如对接某个 API 的字段名也硬要用驼峰导致代码报错。后来我调整了思路技能规定原则和边界不规定所有细节。原则是命名要一致、要表意清晰边界是遵循项目现有风格。具体用驼峰还是下划线让 agent 根据上下文判断。这样既保证了方向又保留了灵活性。7.2 技能之间互相冲突当多个技能同时加载时冲突几乎不可避免。我遇到过最典型的一次TDD 技能要求先写测试而另一个快速原型技能要求先跑通再补测试。两个技能同时加载agent 直接卡住不知道该听谁的。解决办法是给技能加互斥标记。在技能头部注明本技能与 XX 技能互斥不可同时加载。CLI 在加载时检查冲突发现互斥就提示用户选择。这个机制看起来简单但能避免大量诡异行为。7.3 技能文档的维护成本被低估技能写出来只是开始维护才是大头。项目在演进代码规范在变技能文档如果不同步更新agent 就会按过时的规范干活。我见过一个团队技能里还写着用某个已经废弃的测试框架结果 agent 生成的测试全跑不起来。应对办法是把技能文档纳入代码 review 流程。每次改代码规范同步改技能文档。更进一步可以在 CI 里加一个检查如果技能文档里引用的文件路径不存在就报错。这样至少能保证技能里的引用不会失效。7.4 agent 对技能的理解偏差即使技能写得再清楚agent 也可能理解偏。我遇到过一次技能里写重构时不要改变外部行为agent 理解成不要改变函数签名结果它把函数内部逻辑大改了一通虽然签名没变但行为变了。这类偏差很难完全避免但可以通过增加具体示例来降低概率。在技能里放一两个正确做法和错误做法的对比示例agent 的理解准确率会明显提升。示例比抽象描述有效得多这是我在实践中反复验证过的。8. 技能体系的扩展方向8.1 从单机技能到团队技能库个人用 skills一个目录就够了。但团队用就需要考虑共享和版本管理。一个可行的做法是把技能库做成独立的 Git 仓库各项目通过 submodule 或包管理器引入。这样技能更新一次所有项目都能同步。更进一步可以给技能加版本号项目锁定特定版本。这样技能升级不会突然改变 agent 行为避免昨天还好好的今天 agent 就抽风了的情况。8.2 技能的效果度量技能到底有没有用不能靠感觉。我建议记录几个指标agent 任务的一次通过率、需要人工干预的次数、生成代码的测试覆盖率。对比引入技能前后的数据就能看出技能的实际价值。这个度量不需要很复杂手动记录几十个任务就能看出趋势。如果某个技能引入后相关任务的通过率没提升那这个技能可能写得有问题或者根本不该存在。8.3 技能和提示词的边界最后说一个容易混淆的点技能和提示词不是替代关系而是互补。技能管的是稳定的、可复用的流程和规范提示词管的是这次任务的特殊要求。比如 TDD 流程用技能固化但这次要用递归实现这种一次性要求还是写在提示词里更合适。搞清楚这个边界就不会陷入什么都想写成技能的误区。技能库应该保持精简只放那些真正跨任务复用的东西。一个塞满几十个技能的库维护成本会高到没人愿意碰。我在实际项目里用下来最深的体会是skills 的价值不在于让 agent 变聪明而在于让 agent 变稳定。模型本身的能力已经足够强真正拖后腿的是行为的不确定性。把工程经验沉淀成技能本质上是在给这种不确定性套上缰绳。缰绳套得好agent 就是一个可靠的协作者套得不好它就是一个随时给你惊喜吓的黑盒。这套东西值得每个认真用 AI 编码的人花时间琢磨。