1. 从 agent-skills 说起为什么我们需要给 AI 编程助手装上“技能包”第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是给 AI coding agents 做的一套“外挂技能库”吗后来花了两天时间把它的结构、CLI 用法和跟 Claude Code 的配合方式摸了一遍发现它想解决的问题比我想的要实在得多——它要解决的是AI 编程助手在真实项目里“什么都懂一点、但什么都不精”的尴尬。你如果用过 Claude Code、Cursor、Windsurf 这类 AI coding agents大概率遇到过这种情况让它写个 React 组件它给你写出来了但状态管理用的是三年前的写法让它改个 Python 脚本它把类型注解全给你删了让它跑测试它压根不知道你项目里用的是 vitest 还是 jest。这不是模型不行而是模型缺少你这个项目的“上下文技能”。agent-skills干的事情就是把这些技能以可复用、可组合、可通过 CLI 管理的方式喂给 AI agent。说白了它是一套面向 AI coding agents 的技能描述规范 管理工具。核心关键词里出现的skills CLI、test-driven-development、Claude Code基本勾勒出了它的使用场景你在 Claude Code 里干活通过 skills CLI 把 TDD 这类工作流技能注入进去让 agent 按照你定义的规则来写代码、跑测试、做重构。适合谁来参考三类人最值得花时间看一是已经在用 Claude Code 或类似工具、但觉得“它总是不按我的规矩来”的开发者二是团队里想统一 AI 编码规范的技术负责人三是想自己写 skill 扩展 agent 能力的高级玩家。小白也能看因为我会把 CLI 的每一步都拆开讲。2. agent-skills 的整体设计与核心思路拆解2.1 为什么不是“写更长的 prompt”而是“做技能包”很多人第一反应是我直接在 Claude Code 里把要求写详细点不就行了我一开始也这么想直到我把一段 800 字的 prompt 反复粘贴了十几次之后彻底放弃了。问题有三个prompt 不可复用、不可版本管理、不可组合。你今天写了一段“用 TDD 写 React 组件”的 prompt明天想加一条“必须用 TypeScript 严格模式”后天想换成 Vue你只能重新写。agent-skills的思路是把每个技能拆成一个独立的、有明确触发条件和执行规则的单元。一个 skill 大致包含这几块信息技能名称、适用场景什么时候该激活、具体指令agent 该怎么做、约束条件不能做什么、示例few-shot。这跟 prompt engineering 里的“角色任务约束示例”结构是一脉相承的但它把这种结构工程化了。我个人的理解是prompt 是“一次性对话”skill 是“可安装的能力”。这个区别很关键。就像你不会每次写代码都重新定义一遍函数你也不应该每次跟 agent 对话都重新定义一遍工作流。2.2 技能分层从通用技能到项目专属技能拆开agent-skills的目录结构看它其实做了一个分层设计这一点我觉得是整个项目最值得借鉴的地方通用层跟具体项目无关的技能比如test-driven-development、code-review、commit-message-convention。这些技能在任何项目里都能用。技术栈层跟语言/框架绑定的技能比如 React 的 hooks 规范、Python 的 typing 规范、Rust 的 error handling 惯例。项目层只属于你这个仓库的技能比如“我们的 API 层必须走src/api/client.ts这个封装”、“数据库迁移必须写 down 脚本”。这种分层的好处是复用粒度清晰。通用层写一次所有项目共享项目层跟着仓库走换项目就换一套。我在实际配置的时候把通用层放在全局配置目录项目层放在仓库的.agent-skills/下Claude Code 启动时会自动加载两层冲突时项目层覆盖通用层。这个覆盖逻辑很重要后面讲排查问题时会再提到。2.3 跟 Claude Code 的配合方式为什么选它作为首选载体热词里大量出现claude code、claude code安装、vscode配置claude code说明大部分人接触 agent-skills 的入口就是 Claude Code。原因也简单Claude Code 是目前少数原生支持在终端里执行命令、读写文件、跑测试的 agent而 agent-skills 里的很多技能尤其是 TDD本质上需要 agent 能真的去跑npm test、看输出、再改代码。如果 agent 只能聊天不能执行TDD 技能就是空谈。所以 agent-skills 的设计假设是宿主 agent 必须具备工具调用能力。Claude Code 满足Cursor 部分满足纯聊天窗口不满足。这一点在你选型的时候必须先确认否则装了 skill 也没用。3. 核心细节解析与实操要点3.1 一个 skill 到底长什么样字段拆解我拿test-driven-development这个技能举例把它的核心字段拆开讲。一个标准的 skill 定义通常包含以下部分不同版本字段名可能略有差异但语义一致字段作用实操建议name技能唯一标识用 kebab-case别用中文description什么时候激活这个技能写清楚触发条件agent 靠它判断instructions具体执行指令分步骤写别写成一大段constraints禁止事项越具体越好比如“禁止跳过失败测试”examples正反例至少一正一反agent 学得快version版本号语义化版本方便回滚description这个字段最容易被忽视但它其实是技能能否被正确激活的关键。我踩过的坑是一开始把 description 写成“帮助写测试”结果 agent 在任何跟测试沾边的场景都激活它包括我只是想让它解释一段测试代码的时候。后来改成“当用户要求新增功能或修复 bug 且项目存在测试框架时激活”误触发率立刻降下来了。3.2 skills CLI 的安装与基础命令skills CLI是管理这些技能的命令行工具。安装方式跟大多数 Node 生态的 CLI 一样我实测下来在 macOS 和 Ubuntu 上都跑得通# 全局安装需要 Node 18 npm install -g agent-skills-cli # 验证安装 skills --version # 初始化当前项目的技能目录 skills init # 列出已安装技能 skills list # 安装一个技能从本地或远程源 skills add test-driven-development # 移除技能 skills remove test-driven-development这里有个细节值得说skills init会在当前目录生成.agent-skills/文件夹和一个skills.config.json。别把这个文件夹加进 .gitignore项目层技能是要跟着仓库走的团队共享才有意义。我见过有人把它 ignore 了结果同事拉下来代码发现 agent 行为完全不一样排查半天才发现是技能没同步。3.3 技能加载优先级与冲突处理前面提到分层这里展开讲优先级。实测下来的加载顺序是全局技能目录~/.agent-skills/项目技能目录./.agent-skills/会话内临时技能通过 CLI 动态注入后面的覆盖前面的。同名技能项目层会完全替换全局层不是合并。这个设计我觉得是对的因为合并容易产生意料之外的行为。但要注意如果你只想覆盖全局技能的某一条约束得把整个技能复制到项目层再改不能只写差异部分。提示改完技能后Claude Code 需要重启会话才能重新加载。热更新目前不支持别指望改完立刻生效。3.4 写自定义技能的三个关键原则自己写 skill 的时候我总结了三条原则都是从翻车里学来的第一指令要可执行不要可理解。“写出高质量的代码”这种话 agent 理解不了但“每个函数必须有 JSDoc 注释参数类型用 TypeScript 标注”它就懂。把形容词换成动词和名词。第二约束要写成硬性规则。“尽量不要用 any”不如“禁止使用 any除非在注释里说明理由”。agent 对“尽量”这种词基本免疫。第三示例要覆盖边界情况。只给正例agent 遇到边界就懵。给一个正例加一个反例效果比给三个正例还好。4. 实操过程与核心环节实现4.1 环境准备从零到能跑通我按最干净的路径走一遍假设你刚装好 Claude Code想接入 agent-skills。先确认基础环境# 检查 Node 版本必须 18 以上 node -v # 检查 Claude Code 是否可用 claude --version如果 Claude Code 还没装热词里那些claude code安装、mac安装claude code、ubuntu 安装claude code的搜索需求就来自这一步。安装方式官方文档写得很清楚我不重复只提醒一点装完之后先跑一次claude确认能正常启动会话再装 skills CLI。顺序反了的话skills CLI 初始化时探测不到宿主 agent会报一个很迷惑的错。4.2 配置 TDD 技能的完整流程TDD 是 agent-skills 里最值得先配的技能因为它对 agent 行为的改变最明显。完整流程如下# 1. 进入你的项目 cd your-project # 2. 初始化技能目录 skills init # 3. 安装 TDD 技能 skills add test-driven-development # 4. 查看技能内容确认符合预期 skills show test-driven-development装完之后.agent-skills/test-driven-development.md里会有默认的 TDD 指令。默认版本大致要求 agent 遵循“红-绿-重构”循环先写一个失败的测试跑一次确认它失败再写最小实现让它通过最后重构。默认指令里有一条很关键禁止在测试失败前写实现代码。这条约束是 TDD 技能的灵魂别删。我建议装完之后手动改一处把测试命令改成你项目实际用的。默认写的是npm test如果你用 pnpm 或者 vitest得改。改的位置在 instructions 里的“运行测试”那一步。4.3 在 Claude Code 里验证技能是否生效配置完不代表生效得验证。我的验证方法是给 agent 一个明确的小任务观察它的行为顺序# 在 Claude Code 会话里输入 帮我给 utils/formatDate.ts 加一个功能支持传入时区参数如果 TDD 技能生效了agent 的行为应该是先去看有没有现成的测试文件然后先写测试跑一次给你看失败输出再写实现。如果它上来就直接改formatDate.ts说明技能没加载。这时候按顺序排查技能文件在不在、config 里有没有注册、会话有没有重启。4.4 参数选择技能粒度怎么定这是实操里最需要经验的地方。技能粒度太粗agent 行为不可控太细管理成本爆炸。我的经验值是一个技能对应一个可独立验证的工作流。TDD 是一个工作流code review 是一个工作流commit message 规范是一个工作流。但“写 React 组件”不是一个工作流它是多个工作流的组合应该拆成“组件结构规范”“状态管理规范”“测试规范”。我试过把整个前端规范塞进一个技能结果 agent 每次激活都要读一大堆不相关的内容响应变慢还容易抓错重点。拆成三个之后每个技能 200 字以内激活准确率和响应速度都上来了。5. 常见问题与排查技巧实录5.1 技能不生效的排查清单这是被问得最多的问题。我整理成一张速查表按顺序排查基本能定位现象可能原因排查方法agent 完全不按技能走技能未加载skills list确认已安装部分场景生效部分不生效description 触发条件太窄检查 description 措辞项目层技能没覆盖全局文件名不一致两层技能 name 必须完全相同改了技能没反应会话未重启退出 Claude Code 重新进CLI 报找不到宿主安装顺序反了先装 Claude Code 再装 CLI5.2 技能之间互相打架怎么办我遇到过 TDD 技能和“快速修复”技能冲突的情况一个要求先写测试一个要求直接改。agent 在两者之间反复横跳行为很不稳定。解决办法是给技能加优先级字段或者在 description 里写清楚互斥条件。我的做法是在“快速修复”技能的 constraints 里加一条“当 TDD 技能已激活时本技能不生效”。这种显式互斥比让 agent 自己判断靠谱得多。5.3 团队协作中的技能同步问题团队用 agent-skills最大的坑不是技术是规范同步。我建议把.agent-skills/纳入 code review 流程改技能跟改代码一样要过 PR。另外在 README 里写清楚新人拉下代码后第一件事是跑skills sync如果有这个命令或者手动skills add一遍。我见过团队里有人本地技能是旧的提交的代码风格跟其他人完全不一样review 的时候才发现是技能版本没对齐。注意技能文件里不要写任何密钥、内部地址、个人账号信息。这些内容会被 agent 读取存在泄露风险。我一般会在 CI 里加一个检查扫描.agent-skills/下有没有敏感字符串。5.4 性能与响应速度优化技能装多了之后Claude Code 的响应会变慢因为每次激活都要匹配所有技能的 description。我的优化经验是全局技能控制在 5 个以内项目技能控制在 10 个以内。超过这个数就要考虑合并或者按需加载。另外 description 尽量短一句话说清楚触发条件就行别写成小作文。6. 技能扩展与进阶玩法6.1 把团队规范写成技能这是 agent-skills 最有价值的用法。你们团队肯定有一堆“口口相传”的规范API 错误码怎么定义、日志格式长什么样、分支命名规则。这些以前靠文档和 review 来保证现在可以写成技能让 agent 直接执行。我帮一个团队做过这件事把他们的 API 规范写成技能后新人用 Claude Code 写出来的接口第一次 review 的通过率从 40% 提到了 70% 多。写团队规范技能的关键是把“应该”变成“必须”把“建议”变成“禁止”。文档里可以写“建议使用统一错误码”技能里必须写“所有 API 响应必须包含 code 字段取值来自 src/constants/errorCodes.ts”。6.2 技能的组合与继承进阶玩法是技能组合。比如你可以写一个frontend-feature技能它的 instructions 里引用test-driven-development和component-structure两个技能。这样激活一个技能等于激活一套工作流。目前 agent-skills 对组合的支持还比较原始主要是靠 description 里的关键词联动但已经够用了。6.3 跟其他 AI coding agents 的适配虽然热词里 Claude Code 占大头但 agent-skills 的设计本身不绑定特定 agent。我试过把它接到其他支持工具调用的 agent 上核心逻辑是通的差异主要在技能加载机制。如果你的 agent 不支持自动加载技能目录可以手动把技能内容拼进 system prompt。这种方式笨但有效适合做验证。7. 我踩过的坑和几条实在建议最后说几条纯经验的东西都是文档里不会写的。第一条别一上来就装一堆技能。我刚开始的时候装了十几个结果 agent 行为变得很难预测排查问题都不知道从哪下手。正确做法是先装一个 TDD用一周摸清楚它的行为模式再加第二个。第二条技能要跟着项目演进。项目重构了技能里的路径、命令、规范都要跟着改。我见过技能里还写着已经不存在的目录结构agent 照着执行直接报错。建议把技能维护纳入迭代流程别让它变成技术债。第三条description 的措辞值得反复打磨。这是投入产出比最高的一件事。花半小时改 description可能省下你后面几十次的误触发。我的经验是 description 里要包含“什么时候”和“什么条件下”两个要素缺一个都容易误触发。第四条保留一个“逃生舱”技能。我专门写了一个技能description 是“当用户明确说‘忽略所有技能’时激活”instructions 是“按用户字面意思执行不套用任何工作流”。有时候你就是想让 agent 别那么规矩直接干活这个技能能救急。第五条技能不是越多越好是越准越好。一个精准的技能胜过十个模糊的技能。判断标准很简单如果这个技能激活后agent 的行为有 80% 以上符合预期它就是合格的低于这个数回去改 description 和 constraints。这套东西我用了几个月最大的感受是agent-skills 本质上是在做人和 AI 之间的契约。你把期望写清楚AI 才能稳定交付。指望模型自己猜你的意图永远是在赌运气。把技能写好才是把 AI coding agent 真正用起来的关键一步。