1. 从 agent-skills 说起为什么 AI 编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我的直觉是这大概率又是一个把提示词打包成模板的仓库。但真正翻完它的结构、跑通它的 CLI、再把它接到 Claude Code 里用了几轮之后我改主意了。它解决的不是提示词怎么写的问题而是AI 编码代理怎么稳定地做对一件事的问题——这两件事的难度差了一个量级。先把概念说清楚。所谓agent-skills本质上是给 AI 编码代理AI coding agents准备的一套可复用、可组合、可被程序化调用的能力单元。每个 skill 通常包含三部分一段描述这个能力做什么的元信息、一份指导代理如何执行的操作说明、以及可选的辅助脚本或资源文件。代理在接到任务时不是靠一段万能提示词硬扛而是先判断这个任务该调用哪个 skill再按 skill 里定义的流程一步步执行。这套思路为什么重要因为大模型在编码场景里最大的问题从来不是不会写代码而是不稳定。同一个需求今天给你写个能跑的版本明天给你写个漏了边界条件的版本后天干脆把测试文件也一起改了。test-driven-development这类 skill 的价值就在于它把先写测试、再写实现、最后重构这个流程固化下来让代理每次都必须走同一条路而不是自由发挥。这个项目适合谁三类人最该看一是已经在用 Claude Code 或类似工具、但总觉得输出质量飘忽的开发者二是想把 AI 编码能力集成进自己 CI/CD 或内部工具链的工程团队三是想理解代理工程这套方法论到底怎么落地的人。哪怕你只是刚装完 Claude Code 想找个靠谱的起点这套 skill 组织方式也比你自己攒一堆提示词要省事得多。下面我会按设计思路—核心细节—实操落地—问题排查这条线把 agent-skills 从里到外拆一遍中间会穿插我自己踩过的坑和实测有效的配置。2. 整体设计与思路拆解为什么是技能而不是提示词2.1 从提示词工程到技能工程的范式转变早两年大家玩 AI 编码主流做法是攒一个超长的 system prompt把编码规范、项目结构、命名习惯全塞进去。这套做法在小项目上还能凑合一旦项目变大就崩了——提示词越长模型对其中每一条的注意力越稀释最后变成什么都说了等于什么都没说。agent-skills 的设计思路正好相反把一个大而全的提示词拆成一堆小而专的技能。每个 skill 只负责一件事比如写单元测试做代码审查生成数据库迁移脚本。代理在执行任务时按需加载上下文里只出现当前真正需要的那部分指令。这个转变带来的直接好处是上下文利用率大幅提升间接好处是每个 skill 都可以独立迭代、独立测试。我打个生活化的比方。传统提示词像是一本厚厚的员工手册新员工入职先背完整本干活时还得自己翻。技能体系更像是贴在工位旁边的一张张操作卡片做咖啡的时候看咖啡那张修打印机的时候看打印机那张。手册不会消失但它退居到背景知识的位置真正指导动作的是那些卡片。2.2 技能目录结构背后的考量一个典型的 skill 目录长这样skills/ test-driven-development/ SKILL.md scripts/ run-tests.sh references/ testing-patterns.md code-review/ SKILL.md核心是那个SKILL.md它承担了元信息和操作说明两个职责。文件开头通常有一段结构化的元数据声明这个 skill 的名字、适用场景、触发条件正文部分则是给代理看的操作指南。把脚本和参考资料放在子目录里是为了让 skill 保持自包含——一个 skill 文件夹拷到哪都能用不依赖外部路径。提示SKILL.md 里的描述要写得像给一个新同事交代任务而不是像写 API 文档。代理理解自然语言指令的能力远强于理解结构化配置把什么时候用、怎么用、注意什么用大白话讲清楚效果比堆参数好得多。2.3 与 Claude Code 的契合点在哪里Claude Code 这类工具的一个关键特性是它能读写文件、执行终端命令、并且能在多轮对话里保持任务上下文。agent-skills 恰好利用了这三点skill 文件本身是文件代理可以直接读skill 里的脚本可以通过终端执行整个读 skill—执行—验证的循环天然就是多轮的。这也是为什么 skills CLI 这类工具会出现。手动管理几十个 skill 文件夹、还要保证它们被正确加载太容易出错了。CLI 的作用就是把安装、更新、列出、移除 skill这些操作标准化让 skill 的分发像装 npm 包一样简单。3. 核心细节解析与实操要点3.1 SKILL.md 到底该怎么写这是整个体系里最容易被低估的部分。很多人第一次写 SKILL.md会写成一段泛泛的你要认真写测试之类的废话。代理拿到这种指令跟没拿到差不多。有效的写法是把流程拆成可验证的步骤每一步都有明确的输入和输出。以 test-driven-development 这个 skill 为例一份能用的 SKILL.md 大致包含这些内容触发条件当用户要求新增功能、修复 bug、或重构现有代码时启用前置检查确认项目里已有测试框架确认测试命令是什么执行流程先写一个会失败的测试运行确认它确实失败再写最小实现让它通过最后重构验证标准所有测试通过且新增测试确实覆盖了目标行为禁止事项不允许在没写测试的情况下直接改实现代码注意最后那条禁止事项。这是 skill 和普通提示词最大的区别之一——好的 skill 会明确划出红线。模型在没有约束的时候倾向于走捷径你告诉它必须先写测试它可能还是会先写实现再补测试。但如果你明确写禁止先改实现它在多数情况下会遵守。3.2 脚本与代理的分工边界一个常见的困惑是哪些事该让代理用自然语言推理完成哪些事该写成脚本让代理调用我的经验法则是确定性的、重复性的、容易出错的操作用脚本需要判断和权衡的操作用自然语言。比如运行测试并返回结果这件事写成脚本最稳因为命令是固定的代理只需要读输出。判断这个测试是否覆盖了边界条件这件事就得靠代理推理写不成脚本。在 agent-skills 里脚本通常放在scripts/目录下SKILL.md 里用相对路径引用。这样设计的好处是脚本可以被单独测试——你可以不启动代理直接跑一遍脚本看它是否正常工作。这一点在排查问题时特别有用能快速区分是脚本坏了还是是代理理解错了。3.3 技能的粒度控制粒度太粗一个 skill 管一大堆事等于没拆粒度太细一个 skill 只管一行代码的写法代理光加载 skill 就耗尽了上下文。我实测下来比较舒服的粒度是一个 skill 对应一个完整的、有明确起止的工作单元。写一个函数的单元测试太细完成一个功能模块的开发太粗为一个已有函数补充测试覆盖刚好。判断标准很简单如果这个 skill 执行完之后你能明确说这件事做完了那粒度就合适。3.4 版本管理与团队协作skill 是要演进的。今天你觉得先写测试这条规则没问题明天可能发现某些场景下需要先写接口定义。这时候就需要版本管理。agent-skills 的目录结构天然适合放进 Git每个 skill 一个文件夹改动通过 PR 走审查。团队协作时有个坑要注意不同人对同一个 skill 的理解可能不一样。我见过一个团队两个人分别改了 code-review 这个 skill一个强调必须指出性能问题一个强调不要吹毛求疵结果合并之后代理彻底懵了。解决办法是在 SKILL.md 里明确写出优先级——哪些问题必须报哪些问题可以忽略。4. 实操过程与核心环节实现4.1 环境准备与 skills CLI 安装假设你已经在 Ubuntu 或 macOS 上装好了 Claude Code接下来装 skills CLI。这类 CLI 工具通常通过包管理器分发具体命令以官方文档为准我这里给一个通用的流程# 确认 Node.js 环境多数 skills CLI 基于 Node node -v npm -v # 全局安装 skills CLI包名以官方为准 npm install -g skills-cli-package # 验证安装 skills --version装完之后第一件事是初始化一个 skills 目录skills init这个命令会在当前目录下创建skills/文件夹和一份基础配置。如果你是在已有项目里用建议把 skills 目录放在项目根目录跟.git平级这样代理在项目里工作时能直接读到。注意如果你用的是 VS Code 里的 Claude Code 插件skills 目录的路径要跟插件的工作区根目录对齐。我踩过一次坑skills 放在上层目录插件死活读不到排查了半小时才发现是工作区范围的问题。4.2 安装第一个 skill以 test-driven-development 为例# 从仓库安装指定 skill skills install test-driven-development # 列出已安装的 skill skills list # 查看某个 skill 的详情 skills info test-driven-development装完之后skills/目录下会多出一个test-driven-development/文件夹。打开里面的 SKILL.md 通读一遍这一步别跳过——你得知道代理接下来会按什么流程走否则出了问题你都不知道该从哪查。4.3 在 Claude Code 里触发 skillskill 装好了不等于代理会自动用。触发方式通常有两种第一种是显式触发你在对话里直接说用 test-driven-development 这个 skill 来完成这个任务。这种方式最可控适合刚开始磨合的阶段。第二种是隐式触发代理根据 SKILL.md 里写的触发条件自己判断。这种方式更自然但前提是你的触发条件写得足够清晰。我建议新手先用显式触发跑通几轮确认 skill 行为符合预期之后再放开隐式触发。实测下来一个完整的 TDD 流程在 Claude Code 里大概是这样你描述需求给用户模块加一个邮箱格式校验函数代理读取 test-driven-development skill代理先写测试文件包含正常邮箱、缺 符号、缺域名等用例代理运行测试确认失败代理写实现代码代理再次运行测试确认通过代理检查是否有可重构的地方整个过程你能在终端里看到每一步的命令和输出。如果第 4 步代理跳过了确认失败直接写实现说明 skill 的约束没生效需要回去检查 SKILL.md 的措辞。4.4 参数与配置的取舍skills CLI 一般会提供一些配置项比如 skill 的加载优先级、是否允许代理自动安装新 skill、脚本执行的超时时间等。这些参数没有标准答案取决于你的使用场景。配置项保守设置激进设置适用场景自动安装 skill关闭开启个人探索 vs 团队规范脚本超时30 秒300 秒单元测试 vs 集成测试隐式触发关闭开启磨合期 vs 熟练期脚本执行权限需确认自动执行生产项目 vs 实验项目我的建议是从保守设置起步。尤其是脚本执行权限让代理自动跑命令这件事在实验项目里很爽在生产项目里就是定时炸弹。等你对某个 skill 的行为完全信任了再逐步放开。4.5 把 skill 接进现有工作流skill 不是只能手动触发。你可以把它接进 Git hooks、CI 流程、甚至编辑器快捷键。比如在 pre-commit 阶段自动跑一遍 code-review skill让代理先审一遍改动再提交。# 示例在 pre-commit 里调用 code-review skill #!/bin/bash skills run code-review --staged if [ $? -ne 0 ]; then echo 代码审查未通过请检查代理输出 exit 1 fi这种接法的好处是把 AI 审查变成了流程的一部分而不是靠人记得去用。坏处是如果 skill 本身有问题会阻塞整个提交流程。所以接进 CI 之前一定要先在本地跑够足够的样本。5. 常见问题与排查技巧实录5.1 代理不按 skill 流程走怎么办这是最高频的问题。表现是skill 明明装了代理还是按自己的习惯来。排查顺序如下先确认 skill 是否真的被加载了。在 Claude Code 里问一句你现在能用哪些 skill看它列出来的清单里有没有你要的那个。如果没有检查 skills 目录路径是否正确、CLI 是否装在了正确的环境里。如果 skill 加载了但行为不对八成是 SKILL.md 写得不够明确。重点检查三处触发条件是否写得太宽泛导致代理觉得这个任务不适用、执行步骤是否有歧义导致代理自由发挥、禁止事项是否缺失导致代理走捷径。我遇到过一个典型案例skill 里写应该先写测试代理理解成可以最后补测试。把应该改成必须把先写测试改成在修改任何实现代码之前必须先创建对应的测试文件并运行确认其失败问题就解决了。给代理写指令措辞的确定性比文采重要一百倍。5.2 脚本执行失败的排查路径脚本失败通常分三类环境问题、权限问题、逻辑问题。环境问题最常见比如脚本里用了python3但系统只有python或者依赖的某个命令行工具没装。排查方法是脱离代理直接在终端里手动跑一遍脚本看报什么错。权限问题在 macOS 和 Ubuntu 上表现不同。Ubuntu 上可能是文件没有执行权限chmod x一下就好。macOS 上可能是 Gatekeeper 拦截需要在系统设置里放行。逻辑问题最麻烦因为脚本本身能跑但结果不对。这时候要看脚本的输入输出是否符合预期。我习惯在脚本开头加一行set -e让它在任何一步失败时立即退出而不是带着错误状态继续往下跑。5.3 常见问题速查表现象可能原因排查动作代理完全无视 skillskill 未加载或路径错误询问代理可用 skill 列表代理部分遵循 skillSKILL.md 措辞模糊检查触发条件和步骤描述脚本报 command not found依赖工具未安装手动执行脚本看报错脚本无输出权限不足或路径错误检查执行权限和相对路径测试通过但结果不对测试用例覆盖不足审查测试文件内容skill 之间行为冲突多个 skill 触发条件重叠明确各 skill 的优先级5.4 几个我踩过的坑第一个坑是skill 装太多。刚开始新鲜一口气装了十几个结果代理每次都要在众多 skill 里挑反而变慢了还经常挑错。后来精简到五六个核心 skill效率明显提升。skill 不是越多越好够用就行。第二个坑是忽略 skill 的更新。skill 仓库是会迭代的早期版本可能有 bug 或者措辞不当。定期跑一下skills update能省不少事。但更新前记得看一眼 changelog有次更新改了一个 skill 的触发条件导致我原来的工作流全乱了。第三个坑是在 skill 里写死项目路径。这种 skill 换个项目就用不了。正确做法是用相对路径或者环境变量让 skill 保持可移植。第四个坑是把 skill 当成万能药。有些任务就是不适合用 skill 固化流程比如探索性的原型开发你根本不知道下一步要做什么硬套 skill 反而束手束脚。skill 适合的是那些流程明确、重复性高的任务。5.5 关于模型选择的补充Claude Code 本身支持接入不同的模型后端社区里也有各种切换方案。我的经验是skill 的效果跟模型能力高度相关。同一个 test-driven-development skill在能力强的模型上能完整走完流程在能力弱的模型上可能走到第三步就忘了前面的约束。所以如果你发现 skill 行为不稳定先别急着改 skill换个模型试试。如果换模型之后就好了那问题在模型不在 skill。反过来如果换什么模型都不行那大概率是 SKILL.md 本身有问题。另外不同模型对指令格式的敏感度不一样。有的模型对 Markdown 结构响应好有的对纯文本段落响应好。SKILL.md 用 Markdown 写是通用做法但如果你的模型表现异常可以试试把关键指令用纯文本再强调一遍。6. 把 agent-skills 用出价值的几个思路skill 体系真正的价值不在于单个 skill 有多强而在于组合。我现在的做法是把几个基础 skill 串成一条流水线接到需求先用一个需求澄清skill 把模糊描述变成明确任务再用 test-driven-development 写实现最后用 code-review 过一遍。三个 skill 各管一段代理在每段里的行为都可预测。这套组合用下来最大的感受是可预测性比峰值能力更重要。一个偶尔写出惊艳代码但经常跑偏的代理不如一个每次都稳定输出合格代码的代理。skill 的作用就是把代理的行为收敛到一个可接受的范围内牺牲一点上限换来大量的确定性。如果你刚开始接触这套东西我的建议是从一个 skill 开始把它用熟、用透理解它为什么这么设计再考虑加第二个。贪多嚼不烂这件事在 skill 体系里体现得特别明显。等你对某个 skill 的行为完全有把握了再把它接进自动化流程那时候你才真正拥有了一个可靠的 AI 编码伙伴而不是一个需要时刻盯着的不确定因素。