1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个词是在翻 Claude Code 相关仓库的时候。当时我的第一反应是这不就是把“提示词工程”换了个马甲吗但真正把仓库拉下来、跑通 skills CLI、看着一个空荡荡的 agent 目录被一条条技能文件填满之后我意识到这东西解决的是一个非常具体、非常痛的问题——AI coding agent 的“能力复用”问题。先把这个概念说清楚。agent-skills本质上是一套面向 AI 编码代理的技能描述规范与配套工具链。它做的事情是把“怎么让 agent 干某件事”这件事从散落在各个项目里的提示词、脚本、配置文件抽象成一个个独立、可版本化、可组合的 skill 单元。每个 skill 通常包含一段结构化的说明告诉 agent 这个技能是干什么的、什么时候用、可能附带的脚本或模板、以及触发条件。然后通过一个 skills CLI把这些技能安装到你的 agent 工作目录里让 Claude Code 这类工具在运行时能够按需加载。它能做什么简单讲三件事。第一把重复劳动固化下来。比如你每次开新项目都要让 agent 按 TDD 流程走——先写测试、再写实现、最后重构——这套流程如果每次都靠手打提示词既累又容易漏。做成 skill 之后一句触发词就能拉起整套流程。第二让技能可以跨项目、跨团队共享。你踩过的坑、总结的最佳实践可以打包成一个 skill 发给同事而不是在群里发一段三百行的提示词。第三给 agent 的行为加上约束和检查点。skill 里可以定义“做完这一步必须跑测试”“改完文件必须检查 lint”把软性的口头约定变成硬性的流程节点。适合谁看如果你只是偶尔用 Claude Code 问几个问题那这东西对你价值有限。但如果你属于下面几类人agent-skills值得你花一个下午认真研究每天用 AI coding agent 写代码超过两小时的开发者团队里在推 AI 辅助开发规范的技术负责人以及那些觉得“每次都要重新调教 agent”很烦、想把这部分工作沉淀下来的工程师。我自己属于第一类和第三类的混合体所以下面这些内容基本都是我在真实项目里趟出来的。2. 核心设计思路拆解为什么是 skill而不是 prompt 或 plugin2.1 从“一次性提示词”到“可复用技能单元”的转变在agent-skills出现之前大家管理 agent 能力的方式基本是三种写在项目根目录的CLAUDE.md或类似文件里、存在个人的提示词笔记里、或者干脆每次现编。这三种方式有个共同的毛病——它们是扁平的、无结构的、不可组合的。你没法说“这个项目只用 A 和 B 两个技能那个项目用 B 和 C”也没法给技能标版本、写依赖、做测试。agent-skills的设计思路我理解下来核心就一句话把技能当成软件包来管理。每个 skill 是一个目录里面有SKILL.md描述元信息和使用说明可以有scripts/放辅助脚本可以有templates/放代码模板可以有references/放参考资料。这个结构和 npm 包、Python 包的设计哲学是一脉相承的——约定优于配置目录结构即接口。为什么这么设计因为 agent 的能力管理本质上和依赖管理是同一类问题。你需要知道“我装了什么”“版本是多少”“谁依赖谁”“怎么升级”“怎么卸载”。一旦用上包管理的思维这些问题就都有现成答案了。skills CLI 提供的install、list、remove、update这些命令就是把这套思维落地。2.2 skills CLI 在整个工具链里的位置很多人第一次接触会搞混skills CLI 和 Claude Code 是什么关系我的理解是Claude Code 是运行时skills CLI 是包管理器agent-skills 是包规范。三者分工明确。Claude Code 负责实际执行——读文件、写代码、跑命令、和用户对话。它本身内置了一些基础能力但不可能预装所有场景的技能。skills CLI 负责把技能从远程仓库或本地路径安装到 Claude Code 能读到的位置通常是项目下的.claude/skills/或用户级的~/.claude/skills/。而 agent-skills 规范定义了技能长什么样、元信息怎么写、触发条件怎么描述。这个分层的好处是解耦。技能作者不需要关心你用的是哪个版本的 Claude Code只要按规范写就行。Claude Code 也不需要内置所有技能按需加载即可。你作为使用者可以在不同项目里装不同的技能组合互不干扰。2.3 为什么 test-driven-development 会成为高频技能在热词里看到test-driven-development和agent-skills绑在一起我一点都不意外。TDD 是 AI coding agent 最需要、也最适合用 skill 来固化的流程之一。原因很直接TDD 的步骤是高度结构化的而且顺序不能乱。先写失败的测试再写刚好能过的实现最后重构。这个流程如果让 agent 自由发挥它大概率会跳过第一步直接写实现或者写完实现再补测试——那就不是 TDD 了是“测试后补”。而 skill 可以把这套流程写成明确的步骤序列每一步都有检查点测试必须先跑失败、实现必须让测试通过、重构后测试必须仍然通过。agent 每走一步都要对照 skill 里的约束偏离了就会被拉回来。我实测下来一个写得好的 TDD skill能让 agent 的代码质量提升一个档次。不是因为它更聪明了而是因为它被流程约束住了。这就像给一个手很快但容易跳步的工匠配了一张必须打勾的检查表。3. 核心细节解析一个 skill 到底长什么样3.1 SKILL.md 的元信息字段与写法要点一个标准的 skill 目录核心是SKILL.md。这个文件分两部分YAML frontmatter 和正文。frontmatter 里最关键的是name、description、when_to_use这三个字段。name是技能的唯一标识建议用短横线分隔的小写英文比如test-driven-development、code-review-checklist。别用中文别用空格别用大写——这些都会在 CLI 处理时出问题。description是一句话说明写给人和 agent 看的。这里有个坑不要写得太泛。我见过有人写“帮助写更好的代码”这种描述等于没写。好的描述是“按红-绿-重构循环执行 TDD每步验证测试状态”。具体、可判断、有边界。when_to_use是触发条件这个字段最容易被忽视但恰恰最重要。它决定了 agent 在什么场景下会主动加载这个技能。写法上建议用“当用户要求……时”“当任务涉及……时”这样的句式把触发场景列清楚。比如 TDD skill 的when_to_use可以写“当用户要求按测试驱动方式开发新功能时当任务涉及为新模块编写测试时当用户提到 TDD、红绿重构等关键词时。”正文部分就是给 agent 看的详细指令。我的经验是正文要写成“操作手册”而不是“概念说明”。不要解释什么是 TDD直接写第一步做什么、第二步做什么、每步的验证标准是什么。agent 不需要理解原理它需要的是可执行的步骤。3.2 技能目录的组织方式与文件命名约定除了SKILL.md一个完整的 skill 还可以包含其他目录。我常用的组织方式是这样的test-driven-development/ ├── SKILL.md ├── scripts/ │ ├── run-tests.sh │ └── check-coverage.py ├── templates/ │ ├── test-template.py │ └── impl-template.py └── references/ └── tdd-patterns.mdscripts/放可执行脚本agent 可以在流程中调用。templates/放代码模板agent 生成新文件时可以参考。references/放补充资料agent 需要深入某个话题时可以读。命名上有个小技巧脚本名用动词开头模板名用名词开头。run-tests.sh一看就知道是干什么的test-template.py一看就知道是什么。这种一致性在技能多了之后特别重要不然你自己都记不住哪个文件是哪个。3.3 触发机制agent 怎么知道该用哪个 skill这是很多人困惑的地方装了一堆 skillagent 怎么知道当前该用哪个答案是两层匹配。第一层是 Claude Code 启动时会扫描 skills 目录读取每个SKILL.md的 frontmatter把name、description、when_to_use加载到上下文里。第二层是当你的请求进来时agent 会根据这些元信息和你的话做匹配决定加载哪个 skill 的完整内容。所以when_to_use写得准不准直接决定了 skill 会不会被正确触发。我踩过的坑是一开始把when_to_use写得太窄结果 agent 经常不触发后来放宽了一点又变成频繁误触发。最后的经验是——用具体的动作词和场景词而不是抽象的概念词。“写单元测试”比“保证代码质量”好“重构现有函数”比“改进代码结构”好。4. 实操过程从零装好一套 agent-skills 工作流4.1 环境准备与 skills CLI 安装假设你已经在用 Claude Code不管是 VS Code 插件版还是终端版skills CLI 的安装都不复杂。我分别在 macOS 和 Ubuntu 上装过流程基本一致。先确认 Node.js 环境。skills CLI 是 npm 包需要 Node 18 以上。用node -v检查如果版本太低先用 nvm 或系统包管理器升级。这一步别偷懒我见过因为 Node 版本太老导致 CLI 装上了但跑不起来的情况。node -v # 确认 18 npm install -g agent-skills/cli # 或者用 npx 直接跑不全局安装 npx agent-skills/cli --help装完之后跑skills --version确认。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Ubuntu 上偶尔会遇到这个问题npm config get prefix看一下路径然后手动加进.bashrc或.zshrc。提示如果你在公司网络环境下 npm 安装慢可以配一下镜像源。这个和具体网络环境有关配一个稳定的 registry 就行不用折腾太多。4.2 初始化项目级 skills 目录skills 可以装在用户级~/.claude/skills/也可以装在项目级project/.claude/skills/。我的建议是项目级优先。原因很简单不同项目需要的技能不一样项目级隔离能避免互相干扰。用户级适合放那些你所有项目都会用的通用技能比如代码审查清单。在项目根目录执行skills init这个命令会创建.claude/skills/目录并生成一个skills.json记录已安装的技能和版本。这个文件应该提交到 git这样团队其他人 clone 下来之后跑skills install就能装齐所有依赖。这一点和package.json的逻辑完全一样。如果你已经有CLAUDE.mdskills init不会覆盖它但会在里面追加一段说明告诉 Claude Code 去读 skills 目录。如果你手动管理CLAUDE.md记得检查一下这段追加内容在不在。4.3 安装第一个技能以 TDD 为例从官方仓库或社区仓库安装技能命令格式是skills install test-driven-development如果要指定来源仓库skills install github:some-org/some-skills/test-driven-development装完之后用skills list确认。你会看到技能名、版本、来源、安装路径。这时候打开.claude/skills/test-driven-development/SKILL.md花五分钟读一遍。这一步不能省。你得知道这个技能会怎么影响 agent 的行为不然出了问题你都不知道从哪查。我装完 TDD skill 之后做的第一件事是开一个新分支让 Claude Code 做一个简单功能观察它是不是真的按红-绿-重构的流程走。第一次跑的时候发现它跳过了“先写失败测试”这一步直接写了实现。回去看 SKILL.md发现when_to_use里没有明确写“必须从失败测试开始”agent 就按自己的习惯来了。在 skill 里补了一句强制约束之后行为就对了。4.4 在 Claude Code 里验证技能是否生效验证方法很直接给 Claude Code 一个明确会触发该 skill 的任务然后看它的输出结构。以 TDD skill 为例你可以说“用 TDD 方式给 utils.py 里的 parse_date 函数加一个边界情况处理”。如果 skill 生效了agent 应该先写一个会失败的测试跑给你看失败然后再改实现。如果没生效排查顺序是这样的先skills list确认技能装了再打开 SKILL.md 确认when_to_use覆盖了你的说法然后检查 Claude Code 的版本是否支持 skills 加载太老的版本可能不认这个目录最后看.claude/skills/的路径对不对——有些项目根目录不是 git 根目录路径会错位。注意Claude Code 的 skills 加载行为在不同版本间有差异。如果你发现技能装了但 agent 完全不读先升级到最新版试试。升级命令在终端版和插件版里不太一样终端版一般claude update就行。5. 常见问题与排查技巧实录5.1 技能装了但 agent 不触发怎么办这是最高频的问题。我整理了一个排查表按顺序过一遍基本能定位现象可能原因排查方法解决方式完全不触发路径不对确认.claude/skills/在项目根目录移到正确位置或重新 init偶尔触发when_to_use 太窄读 SKILL.md 的触发条件补充场景词和动作词频繁误触发when_to_use 太宽看是否被无关任务触发收窄条件加限定词触发但行为不对正文指令不清晰读正文步骤描述改成可执行的操作序列装了但 list 里没有安装失败看 install 命令输出检查网络和仓库地址我遇到最多的是第二种和第四种。第二种的典型表现是你说“帮我写个测试”agent 没反应你说“用 TDD 写个测试”它才动。这就是when_to_use里只写了“TDD”没写“写测试”。第四种的典型表现是agent 知道要用 TDD但顺序乱了。这就是正文里步骤写得太抽象得改成“第一步写一个断言当前行为错误的测试”这种粒度。5.2 多个技能冲突时的优先级处理当你装了多个技能它们可能在同一个任务上都有话说。比如你装了 TDD skill 和 code-review skillagent 写完代码后是先跑 TDD 的验证步骤还是先走 review 流程我的经验是在 skill 里显式声明依赖和顺序。比如 code-review skill 的when_to_use里可以写“在 TDD 流程的验证步骤完成后触发”。或者在 TDD skill 的正文最后加一句“完成重构后如果项目安装了 code-review skill按该 skill 执行审查”。另一种做法是用 skills CLI 的--priority参数给技能排优先级。但这个参数在不同版本里行为不太一致我一般还是靠 skill 内部的显式声明来控制更可靠。5.3 技能版本升级与回滚的实操技能也是会迭代的。skills update可以升级所有技能skills update name升级单个。升级前建议先skills list --verbose看一下当前版本和最新版本心里有数。回滚的话skills CLI 目前没有直接的rollback命令。我的做法是在skills.json里锁定版本号然后skills install重新装。比如把test-driven-development: ^1.2.0改成1.1.0再跑一次 install。这个和 npm 的版本锁定逻辑一样。提示团队协作时skills.json一定要提交。我见过有人只提交了.claude/skills/目录但没提交skills.json结果同事 clone 下来技能是旧的排查了半天才发现是版本不一致。5.4 自己写 skill 时最容易踩的三个坑第一个坑是把 skill 写成教程。我第一版 TDD skill 写了八百字解释什么是红绿重构agent 读完还是不知道具体怎么做。后来砍到两百字全是步骤和检查点效果反而好了。agent 不需要理解它需要执行。第二个坑是触发条件写得太抽象。“当需要保证代码质量时”这种条件agent 根本没法判断。改成“当用户要求写测试时当用户提到 TDD 时当任务涉及为新函数添加测试时”触发率立刻上来了。第三个坑是脚本路径写死。skill 里的脚本如果用绝对路径换台机器就废了。统一用相对于 skill 目录的路径或者用环境变量。我在run-tests.sh里一开始写了/Users/myname/project/...推到团队仓库后所有人都跑不了改成$(dirname $0)/../..才解决。6. 把 agent-skills 用出复利我的一些个人做法6.1 从“装别人的”到“写自己的”的过渡时机我大概用了两周社区技能之后开始写自己的第一个 skill。触发点很具体我发现每次让 Claude Code 按我们团队的代码规范写 Python 时都要重复交代一堆东西——类型注解要全、异常要具体、日志要用结构化格式。这些规则写一次是提示词写十次就该变成 skill 了。判断标准很简单如果你发现自己在不同项目里重复交代同一套指令超过三次就该把它做成 skill。不要等到“完美”了再写先写个粗糙版本用起来再迭代。我的第一个 skill 只有二十行现在迭代到第三版加了脚本和模板但核心结构没变。6.2 团队共享技能库的目录结构建议如果你在团队里推这套东西建议单独开一个仓库放共享技能结构可以这样team-skills/ ├── skills/ │ ├── python-style/ │ ├── api-design-review/ │ └── migration-checklist/ ├── README.md └── skills.json每个项目通过skills install github:your-org/team-skills/python-style来引用。这样技能更新一次所有项目skills update就能同步。比在每个项目里复制粘贴强太多。README 里要写清楚每个技能是干什么的、什么时候用、有没有依赖。我见过团队仓库里堆了二十个技能但没文档新人根本不知道从哪开始。6.3 技能与项目文档的边界划分最后一个心得不是所有东西都该做成 skill。项目特有的业务逻辑、一次性的迁移方案、和具体代码强耦合的说明这些放项目文档里更合适。skill 适合放的是跨项目通用的流程和规范。我的划分标准是如果一段内容换个项目还能用做成 skill如果只在这个项目里有意义留在CLAUDE.md或项目 wiki 里。按这个标准我的技能库里现在只有六个技能但每一个都是反复用到的。少而精比多而杂强。这套东西我用了大概三个月最大的感受是agent 的上限取决于你给它的约束有多清晰。agent-skills提供的不是让 agent 变聪明的魔法而是一套把“你知道该怎么做”变成“agent 必须这么做”的机制。把流程固化下来把检查点设好剩下的就是让它跑。跑偏了就改 skill改完再跑。这个循环转起来之后你会发现自己在 AI 辅助开发上花的时间越来越少产出却越来越稳。