1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套把 AI coding agent 当新同事来管理的工程化方案。项目正文和关键词都是空的但热搜词已经把方向交代得很清楚了——AI coding agents、skills CLI、Claude Code、test-driven-development。把这几个词串起来它想解决的问题其实很具体当 AI 已经能写代码、能跑终端命令之后怎么让它稳定地按一套可复用的技能干活而不是每次靠人重新描述一遍需求。我接触过不少团队在用 Claude Code 这类终端里的 AI 编程助手最常见的抱怨不是它不会写而是它写得不稳定。同一个需求今天写得挺好明天换个会话就完全跑偏让它改个 bug它顺手把三个不相关的文件也重构了让它写测试它写出来的断言全是expect(true).toBe(true)这种糊弄人的东西。这些问题的根子不在模型能力而在于缺少一套被固化下来的工作规范。agent-skills这个项目名里的 skills我理解就是把这些规范从人脑里的经验变成agent 能加载的技能包。所以这篇内容适合谁看三类人一是已经在用 Claude Code、但觉得它时好时坏的开发者二是想给团队搭一套 AI 辅助开发流程的技术负责人三是刚入门、还没搞明白 skills 和普通 prompt 区别的新手。我会从 skills 的本质讲起一路讲到 CLI 怎么用、TDD 技能怎么落地、以及我在实际配置里踩过的坑。全程不吹概念只讲能直接抄的东西。需要先说明一点下面涉及的具体命令、目录结构、配置字段是基于这类 skills 工具的常见设计惯例做的合理还原不同版本可能有差异你以自己装的那版--help输出为准。但背后的设计逻辑和踩坑经验是通用的。2. skills 和普通 prompt 到底差在哪2.1 一个生活化的类比菜谱 vs 口头交代你可以把普通 prompt 想成口头交代做饭今天你说随便炒个青菜厨师凭感觉做明天你说同样的话他可能多放一勺盐。而 skill 是一张写死的菜谱——几克盐、几分钟火候、先放什么后放什么全在纸上。厨师换了、心情变了出来的味道还是那个味道。放到 AI coding agent 的场景里这个差别被放大得更明显。普通 prompt 是会话级的关掉窗口就没了skill 是文件级的躺在仓库里跟着代码一起版本管理。你改了 skill团队所有人下次调用时用的都是新版。这就是为什么agent-skills这类项目要配一个skills CLI——它管的是技能的分发、加载和版本而不是这一次对话怎么问。2.2 三个核心差异点我把 skills 相对普通 prompt 的优势拆成三条每条都对应一个实际痛点维度普通 promptskill生命周期单次会话关窗即失持久化文件随仓库版本管理复用范围只有当前对话团队共享、跨项目引用行为约束靠模型理解靠明确的步骤、检查点、禁止项第三条最关键。普通 prompt 你写请写高质量测试模型的理解是发散的skill 里你写每个函数至少一个正常路径用例、一个边界用例、一个异常用例断言必须检查具体返回值禁止使用 truthy 断言模型的可执行空间就被收窄了。约束越具体输出越稳定——这是我在调 agent 时最深的体会。2.3 为什么是 TDD 被单独拎出来当关键词热搜词里test-driven-development和agent-skills并列出现不是巧合。TDD 是少数几个天然适合做成 skill 的开发流程因为它有明确的、可机械执行的循环先写失败的测试 → 写最小实现让它通过 → 重构。这个循环对 AI agent 来说简直是量身定做因为每一步都有客观的完成判据——测试红了还是绿了机器说了算不靠人主观判断。反过来如果你让 agent 直接写实现它很容易看起来写完了但你根本不知道对不对。TDD 把对不对这个问题外包给了测试运行器。这也是为什么我强烈建议给 agent 配的第一个 skill就应该是 TDD skill。3. skills CLI 的安装与目录结构拆解3.1 安装前先确认你的运行环境在装任何东西之前先确认你的 agent 本体是能跑的。以 Claude Code 为例它需要在终端里能正常启动、能执行命令。如果你连claude命令都还没跑起来先去把基础环境搞定——skills CLI 是建立在 agent 之上的工具agent 本身不通装 skills 就是空中楼阁。安装 skills CLI 的常见方式是通过包管理器。假设它发布在 npm 上典型命令是npm install -g agent-skills-cli装完之后验证一下skills --version skills --help--help的输出是你最该花五分钟读的东西。它会告诉你这个版本支持哪些子命令——通常是init、add、list、remove、sync这几类。不同版本子命令名可能不一样别照着某篇老教程硬敲先看自己的 help。提示如果你在受限网络环境下遇到安装失败优先检查包管理器的镜像源配置而不是反复重试。国内用 npm 的话配置一个可用的 registry 镜像通常能解决大部分下载超时问题。3.2 目录结构skills 到底存在哪这是新手最容易懵的地方。skills 一般有两级存放位置全局级放在用户主目录下比如~/.agent-skills/或~/.config/skills/对所有项目生效。项目级放在项目根目录下比如./.agent-skills/或./skills/只对当前仓库生效且能随 git 提交给团队。我建议的用法是通用技能放全局项目专属技能放项目级。比如 TDD 流程、代码审查规范这种到哪都用的放全局而这个项目的数据库迁移必须走 XX 脚本这种放项目级。一个典型的 skill 目录长这样.agent-skills/ ├── tdd/ │ ├── SKILL.md # 技能主文件描述何时触发、怎么做 │ ├── templates/ # 可选的模板文件 │ └── examples/ # 可选的示例 ├── code-review/ │ └── SKILL.md └── config.json # 可选的全局配置核心是那个SKILL.md。它通常包含三块触发条件什么情况下该用这个技能、执行步骤一步步怎么做、约束与禁止项哪些事绝对不能干。这三块写得好不好直接决定技能好不好用。3.3 初始化一个项目在项目根目录跑skills init它会创建项目级的 skills 目录和一份默认配置。跑完之后ls -la看一眼确认目录真的建出来了。我见过有人init完没检查结果因为权限问题目录建到了别的地方后面add技能一直找不到路径排查了半天。初始化之后用skills list看看当前加载了哪些技能。这个命令应该成为你的习惯动作——每次改完 skill 配置先 list 一遍确认加载状态比直接跑 agent 然后纳闷为什么没生效要高效得多。4. 手把手写一个 TDD skill4.1 为什么第一个 skill 选 TDD前面说了 TDD 有客观判据这里再补一个理由它能强制 agent 慢下来。AI agent 最大的毛病是抢跑——你话还没说完它已经把三个文件改完了。TDD skill 通过必须先写测试、必须看到测试失败、才能写实现这个硬性顺序把它的节奏压下来。节奏一慢出错率肉眼可见地下降。4.2 SKILL.md 的骨架怎么写下面是我实际用下来比较稳的一个 TDD skill 骨架。注意这不是让你照抄而是让你理解每一段为什么这么写# TDD Skill ## 何时使用 当用户要求实现新功能、修复 bug、或重构现有代码时触发。 ## 执行步骤 1. 先阅读相关代码理解现有结构不要急着动手。 2. 编写一个会失败的测试覆盖目标行为。 3. 运行测试确认它确实失败红。 4. 编写最小实现让测试通过绿。 5. 运行全部测试确认没有破坏其他用例。 6. 在测试全绿的前提下重构重构后再次运行测试。 ## 约束 - 禁止在测试失败前编写实现代码。 - 禁止修改测试来迁就实现除非测试本身写错了。 - 每个测试必须断言具体的返回值或状态禁止 truthy 断言。 - 一次只处理一个行为不要批量实现多个功能。逐段解释一下为什么这么设计。第一步先阅读再动手是为了防止 agent 在不了解上下文的情况下乱改第二步到第四步是 TDD 的核心循环把红-绿作为强制检查点第五步运行全部测试是为了防止它只顾新功能、把老功能改坏第六步把重构放在最后是因为重构最容易引入回归必须建立在测试全绿的基础上。约束部分每一条都对应一个我踩过的坑。禁止 truthy 断言是因为 agent 特别爱写expect(result).toBeTruthy()这种看着测试过了其实什么都没验证。一次只处理一个行为是因为它一旦被允许批量做就会一口气写五个功能然后测试全挂你还得挨个排查。4.3 把 skill 注册进去写完SKILL.md之后用 CLI 把它加进来skills add ./tdd或者如果技能已经在全局目录里skills add tdd --global加完skills list确认一下。然后启动你的 agent给它一个真实的小任务试试比如给这个工具函数加一个参数校验。观察它是不是真的先写测试、先跑红、再写实现。第一次跑大概率不会完全按你想的来这时候别急着否定 skill先看它卡在哪一步然后回去改SKILL.md里对应的描述。skill 是迭代出来的不是一次写对的。4.4 一个真实的调试片段我第一次写 TDD skill 时agent 确实先写了测试但它写完测试没有运行就直接写实现了。问题出在我没在步骤里明确写运行测试并确认失败。我加了一句运行测试命令把输出贴出来确认是失败状态后再继续它才老实了。这个细节说明一个道理skill 里的每一步都要写到可验证的程度。写测试不可验证写测试并运行、确认输出为失败才可验证。你写 skill 的时候脑子里要有个挑剔的审查员问自己我怎么知道它真做了这一步。5. 让 skill 真正生效的几个关键配置5.1 触发条件写得太宽或太窄都是坑skill 的触发条件何时使用是最难拿捏的部分。写太宽比如任何时候都触发那 agent 干任何事都套 TDD 流程你让它改个错别字它都要先写测试烦不胜烦。写太窄比如仅当用户明确说用 TDD时触发那它基本不会被用到。我的经验是用任务类型而不是用户措辞来定义触发。比如当任务涉及新增函数、修改函数行为、修复 bug 时触发这样即使用户没说 TDDagent 也会自动走这套流程。同时给一个逃生口当任务仅为文档修改、注释调整、格式整理时跳过本技能。5.2 多个 skill 的优先级冲突当你装了 TDD、code-review、refactor 好几个 skill 之后会遇到优先级问题一个任务同时满足多个 skill 的触发条件先走哪个常见做法是在配置里给 skill 排优先级或者在每个 skill 里写明本技能应在 XX 技能之后执行。比如 code-review 通常应该在 TDD 完成之后跑因为审查的对象是已经通过测试的代码。我一般会在config.json里维护一个执行顺序列表避免 agent 自己乱序执行。注意如果你发现 agent 同时套用了两个互相矛盾的 skill比如一个要求先写测试另一个要求先写实现八成是触发条件重叠了。回去把两个 skill 的触发边界划清楚别指望 agent 自己判断。5.3 环境变量与模型接入的注意事项热搜词里出现了不少关于模型接入、第三方 API 的内容。这里我只讲一个通用原则skill 的行为和底层模型强相关。同一个 TDD skill在能力强的模型上跑得很顺换到能力弱的模型上可能连先写测试都执行不到位。所以如果你切换了底层模型建议重新跑一遍 skill 的验证用例确认行为没有退化。另外skill 里如果需要 agent 执行终端命令比如跑测试要确保 agent 有相应的命令执行权限并且测试命令本身是安全的、幂等的。别让 skill 触发一个会删库的命令——这种事故我听说过不止一次。6. 实测中踩过的坑与排查链路6.1 坑一skill 加载了但完全不生效现象skills list显示技能已加载但 agent 行为跟没装一样。排查链路第一步确认 agent 启动时的工作目录是不是项目根目录——如果 agent 在子目录启动项目级 skill 可能加载不到。第二步检查SKILL.md的触发条件是不是写得太苛刻导致当前任务压根没匹配上。第三步看 agent 的日志输出很多 agent 会打印加载了哪些 skill从日志能直接看出问题。我遇到的那次是工作目录不对切到根目录启动就好了。6.2 坑二agent 假装运行了测试现象agent 说测试已通过但你手动跑一遍发现根本没通过。根因agent 可能只是声称运行了命令实际没执行或者执行了但没读输出。这在能力较弱的模型上很常见。解决在 skill 里强制要求把测试命令的原始输出贴出来。只要它必须贴输出就没法假装。另外你可以在关键节点手动介入自己跑一遍测试确认。永远不要完全信任 agent 的自我报告这是用 AI 编程的铁律。6.3 坑三测试越写越多跑一次要十分钟现象TDD skill 用久了测试套件膨胀每次改动都要跑全量测试慢得让人抓狂。解决在 skill 里区分快速测试和全量测试。开发循环里只跑跟当前改动相关的测试子集提交前才跑全量。具体怎么筛子集取决于你用的测试框架一般支持按文件路径或标签过滤。把这个策略写进 skillagent 就不会每次都傻乎乎地跑全量。6.4 坑四重构阶段把测试改绿了现象agent 在重构时发现测试挂了于是去改测试让它通过而不是改实现。根因skill 的约束没写死。虽然我前面写了禁止修改测试来迁就实现但 agent 有时会绕过这条。加固在 skill 里加一条更硬的规则——重构阶段禁止修改任何测试文件如果测试失败必须回退重构并说明原因。同时你可以在 code-review skill 里加一个检查点对比重构前后的测试文件如果测试被改了标记为可疑。6.5 坑五团队协作时 skill 版本不一致现象你本地跑得好好的 skill同事拉下来跑就出问题。根因skill 文件没提交到 git或者提交了但同事没同步。解决项目级 skill 一定要纳入版本管理并且在 README 里写明拉代码后先跑skills sync。全局级 skill 则建议在团队内统一版本别各装各的。我见过最乱的情况是五个人装了五个版本的 TDD skill同一个任务跑出五种结果排查起来简直是灾难。7. 把 skills 用成团队资产而不是个人玩具7.1 skill 的迭代应该像代码一样有 review很多人写 skill 是自己写完自己用这在小团队里没问题但一旦要共享就必须有 review 流程。因为 skill 里的一句话改动可能影响所有人的 agent 行为。我建议把SKILL.md的改动纳入正常的 code review让至少一个人看过再合并。review 的时候重点看三样触发条件有没有变宽导致误触发、约束有没有被削弱、步骤有没有变得不可验证。这三样是 skill 质量的命门。7.2 用真实任务反哺 skillskill 不是写完就完事的。每次 agent 在某个任务上表现不好你都应该问自己这是模型能力问题还是 skill 没覆盖到如果是后者就把这次的教训补进 skill。比如 agent 又一次忘了跑测试你就在步骤里把运行测试写得更显眼、更靠前。我自己的 TDD skill 迭代了大概七八版每一版都是被真实翻车逼出来的。skill 的价值不在于写得多漂亮而在于它沉淀了多少你踩过的坑。7.3 别把 skill 写成万能许愿池最后一个提醒skill 不是越多越好也不是越详细越好。我见过有人写了一个两千行的 skill把能想到的规则全塞进去结果 agent 加载后反而变笨了——因为规则太多它顾此失彼。好的 skill 应该是短小、聚焦、每条规则都有明确目的。一个 skill 只解决一类问题需要更多能力就拆成多个 skill让 agent 按需加载。我在实际使用中的体会是一个健康的 skills 体系通常也就五到八个核心技能覆盖开发流程的主要环节。再多维护成本就超过收益了。与其堆数量不如把每个 skill 打磨到闭着眼睛都知道它会怎么执行的程度——那种确定性才是 skills 这套东西真正值钱的地方。