拓冰网站定制 
1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套给 AI coding agent 用的能力包。它要解决的问题很具体——当你把 Claude Code 这类命令行 AI 编程助手接进项目之后会发现它默认只会聊天式改代码缺少一套可复用、可版本管理、可被 agent 自动加载的工程化技能。agent-skills干的就是把怎么让 agent 按测试驱动开发TDD的节奏干活怎么让 agent 遵守项目规范怎么让 agent 自己跑测试再改代码这些经验沉淀成结构化的 skill 文件让 agent 在需要的时候自动读取并执行。关键词里出现的skills CLI、test-driven-development、AI coding agents、Claude Code基本勾勒出了它的全貌这是一个围绕 AI 编程代理的技能编排层。它不训练模型也不改模型权重而是通过一套约定好的目录结构和元数据把人类工程师的最佳实践翻译成 agent 能理解的指令集。你可以把它理解成给 agent 装的插件系统——只不过插件的内容不是代码而是工作流。适合谁看三类人最该关注。第一类是把 Claude Code 当日常主力工具、但总觉得它不够听话的开发者第二类是团队里想把 AI 编码规范统一起来的 tech lead第三类是想自己写 skill、扩展 agent 能力边界的折腾党。如果你只是偶尔用 AI 补全几行代码这篇可能有点重但只要你开始让 agent 独立完成一个 feature、跑一轮测试、提交一次 PRagent-skills这套思路就值得认真拆一遍。下面我会从它的核心机制、目录结构、TDD skill 的落地方式、CLI 的用法、以及我自己踩过的坑几个角度把这块东西讲透。2. agent-skills 到底解决了什么痛点2.1 裸用 Claude Code 的三个典型翻车现场先说清楚没有 skills 的时候会发生什么你才能理解这套东西的价值。翻车一agent 改完代码不跑测试。你让它实现一个函数它噼里啪啦写完然后说完成。你一看边界条件没处理导入路径写错测试根本跑不过。它不会主动去跑pytest或npm test因为默认行为里没有验证这一步。翻车二每次都要重复交代规范。你的项目用 4 空格缩进、用ruff做 lint、commit message 遵循 conventional commits。这些你每次开新会话都得重新说一遍说漏一条它就自由发挥。上下文一长它还会忘。翻车三agent 不知道什么时候该做什么。面对加一个用户登录接口这种任务人类工程师知道要先写测试、再写实现、再重构。agent 不知道它会直接冲去写实现测试留到最后甚至不写。agent-skills的核心洞察就是这些不是模型能力问题是流程编排问题。模型足够聪明缺的是在正确的时机被喂正确的指令。skill 就是那个时机触发器。2.2 skill 和 prompt、和 CLAUDE.md 的区别很多人第一反应是这不就是写个 prompt 吗我放 CLAUDE.md 里不就行了区别在于加载时机和粒度。CLAUDE.md 是全局常驻的每次会话都塞进上下文写多了会稀释注意力而且它是静态规则不区分场景。skill 是按需加载的agent 判断当前任务需要测试驱动开发这个技能时才去读对应的 skill 文件读完执行完就释放。打个比方CLAUDE.md 像是贴在工位上的员工手册天天看skill 像是抽屉里的操作手册做特定工序时才翻出来。前者适合放永远成立的约束比如禁止提交密钥后者适合放特定任务才用的流程比如如何写一个符合 TDD 的 feature。这个区分非常关键因为它直接决定了你的上下文预算怎么花。上下文是稀缺资源常驻内容越少agent 在关键时刻的脑容量越充足。2.3 一个 skill 的最小构成一个标准的 skill 通常包含三部分元数据frontmattername、description、触发条件。agent 靠 description 判断这个 skill 跟当前任务相不相关。指令正文具体的工作流步骤用自然语言写但要求足够具体、可执行。辅助资源可选的脚本、模板、参考文件skill 正文里可以引用它们。元数据里的 description 是最容易被写砸的地方。写得太泛帮助写代码agent 永远匹配不上写得太窄当用户要求用 pytest 写一个带 mock 的异步测试时使用又几乎触发不了。好的 description 是任务类型 关键动作的组合比如实现新功能时按测试先行的顺序推进。3. 目录结构与 skill 的加载逻辑3.1 典型目录长什么样虽然agent-skills的具体文件我没法逐行给你但这类项目的目录约定高度一致我按通用实践给你还原一个可用的结构agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── tdd-checklist.md │ ├── code-review/ │ │ └── SKILL.md │ └── commit-convention/ │ └── SKILL.md ├── cli/ │ └── index.js └── README.md每个 skill 一个目录目录名就是 skill 的标识。核心文件是SKILL.md里面用 YAML frontmatter 声明元数据正文写指令。references/放那些正文太长、按需引用的补充材料。提示目录名和 frontmatter 里的 name 保持一致能省掉很多调试时的困惑。我见过有人目录叫tdd、name 写test-driven-development结果 CLI 按目录名索引、agent 按 name 匹配两边对不上skill 死活不触发。3.2 agent 是怎么发现skill 的加载逻辑分两步。第一步是索引agent 启动时扫描 skills 目录只读每个 SKILL.md 的 frontmatter把 name 和 description 装进一个轻量清单。这一步不读正文所以开销很小。第二步是匹配与加载当 agent 接到任务它拿任务描述去跟清单里的 description 做语义匹配命中哪个就把哪个的正文读进上下文。这个设计的好处是可扩展性。你装 50 个 skill启动时也只加载 50 条 description不会撑爆上下文。真正占空间的正文只在需要时进来。但这也带来一个坑description 的质量直接决定 skill 的命中率。我建议你写完 description 后拿几个真实任务描述去人肉匹配一遍看看能不能对上。对不上就改别指望 agent 比你聪明。3.3 优先级与冲突处理多个 skill 同时命中怎么办常见做法是给 skill 加priority字段或者靠 description 的 specificity 排序。更稳妥的做法是让 skill 之间职责不重叠。比如写测试和TDD 流程这两个 skill 就容易打架——前者只管写测试后者管整个测试-实现-重构循环。我的经验是把细粒度的 skill 作为粗粒度 skill 的子步骤引用而不是让它们平级竞争。4. TDD skill把工程纪律塞进 agent 的脑子里4.1 为什么 TDD 是 agent 最该学的第一课在所有 skill 里test-driven-development是最值得先做的原因很实在TDD 天然适合 agent。人类做 TDD 的痛苦在于忍住不先写实现很反人性但 agent 没有这个心理负担它只是执行指令。而且 TDD 的循环红-绿-重构是高度结构化的正好是 agent 擅长的按步骤执行。更妙的是测试本身就是可验证的反馈信号——agent 写完测试跑一遍红了写实现再跑绿了。这个反馈闭环让 agent 能自我纠错而不是写完就拍屁股走人。4.2 一个可落地的 TDD skill 正文该怎么写指令正文最忌讳写成你要遵循 TDD 原则这种空话。agent 需要的是可执行的动作序列。我推荐按这个骨架写先确认测试框架和运行命令。让 agent 读 package.json / pyproject.toml找到测试命令别猜。写一个失败的测试。明确要求只写一个测试用例覆盖当前要实现的最小行为。运行测试确认它失败。这一步不能省。如果测试直接通过说明要么测试写错了要么功能已存在都要停下来报告。写最小实现让测试通过。强调最小禁止顺手实现其他功能。再跑测试确认变绿。重构。在测试保护下清理代码重构后必须再跑一次测试。循环。回到第 2 步处理下一个行为。每一步都要写清楚运行什么命令看到什么结果才算通过不通过怎么办。比如第 3 步可以写运行测试命令。如果测试通过而非失败停止当前循环向用户报告测试未按预期失败可能功能已实现或测试断言有误。4.3 让 agent 真的去跑命令而不是假装跑这是 TDD skill 能不能生效的生死线。很多 agent 会脑补测试结果——它写完测试不去执行直接说测试通过。你必须用强指令堵死这条路。有效的写法是明确要求 agent展示命令输出。比如每次运行测试后把完整的命令和输出粘贴到回复里。没有真实输出的测试通过一律视为未完成。 这句话看着啰嗦但实测能显著降低 agent 偷懒的概率。另外如果你的 agent 环境支持工具调用比如 Claude Code 的 Bash 工具要在 skill 里明确使用终端工具执行测试命令而不是让它在脑子里模拟。工具调用是硬约束脑补是软约束能上硬的就别用软的。4.4 测试粒度agent 最容易失控的地方agent 写测试有个通病一次写一大堆。你让它实现一个计算器它一口气写 20 个测试用例然后开始逐个实现循环节奏全乱了。skill 里必须限制粒度。我的做法是加一条硬规则每个循环只允许新增一个测试用例。新增第二个测试前必须确认前一个已经变绿。 这条规则把 agent 拉回小步快跑的节奏也让每次失败的范围可控——出问题时你知道是哪个行为没实现而不是面对一片红。5. skills CLI安装、管理与调试5.1 CLI 存在的意义有人会问skill 不就是几个 markdown 文件吗我手动拷进项目不就行了要 CLI 干嘛CLI 解决的是分发和版本管理。手动拷贝的问题在于skill 更新了你怎么同步多个项目怎么共享团队里怎么保证大家用的是同一版CLI 把这些变成一条命令的事。典型用法是skills install name把某个 skill 装进当前项目的 skills 目录skills list看装了哪些skills update拉最新版。5.2 安装与初始化按通用实践流程大概是这样# 全局安装 CLI npm install -g agent-skills-cli # 在项目里初始化 skills 目录 skills init # 安装 TDD skill skills install test-driven-development # 查看已安装 skills listskills init通常会创建skills/目录并生成一个配置文件记录 skill 的来源和版本。这个配置文件要提交到 git这样团队成员 clone 之后跑一次skills sync就能对齐。注意CLI 的包名和命令名在不同项目里可能不一样装之前先看 README 的 Quick Start别照着记忆里的命令硬敲。我踩过一次把skills敲成了另一个同名工具装了一堆不相干的东西。5.3 调试 skill 不生效的问题skill 装了但 agent 不用是最常见的求助。排查顺序我总结成一张表现象可能原因排查动作agent 完全不提 skilldescription 匹配不上拿任务描述手动比对 descriptionagent 提了但没执行正文指令太抽象检查是否有可执行命令和验证步骤执行了但中途跑偏缺少边界约束补充禁止做什么的负面指令时灵时不灵上下文被挤占精简 CLAUDE.md给 skill 留空间我遇到最多的是第一类。description 写得太文学比如帮助开发者写出优雅的代码agent 根本不知道什么时候该用。改成实现新功能时按测试先行的顺序推进每个循环只加一个测试之后命中率立刻上来了。5.4 多 skill 协同的编排思路当你有 TDD、code-review、commit-convention 三个 skill 时理想状态是它们能串成一条流水线TDD 负责实现code-review 负责检查commit-convention 负责提交。但 agent 不会自动串你得在 skill 里写交接指令。比如 TDD skill 的最后一步可以写所有测试通过后提示用户或自动触发 code-review skill 进行代码审查。 这样 skill 之间就有了调用关系。不过要注意别搞成无限套娃交接链超过三层agent 就容易迷失。6. 我踩过的坑和几条实操心得6.1 坑一skill 写成了教科书我第一版 TDD skill 写了满满一页 TDD 的历史、原则、好处结果 agent 读完该干嘛还是干嘛。后来我把它砍到只剩动作步骤效果立竿见影。skill 是操作手册不是科普文章。每一句话都要能对应到一个动作或一个判断否则就是噪音。6.2 坑二忽略了失败路径新手写 skill 只写顺利情况写测试、跑测试、写实现、跑测试、通过。但真实开发里测试跑不起来环境问题、测试一直红实现有 bug、测试意外绿了断言写错都是常态。skill 里必须为这些分支写清楚停下来报告什么。agent 遇到没写过的分支默认行为往往是硬着头皮往下走结果越走越偏。6.3 坑三把 skill 当成了万能药skill 能规范流程但不能提升模型本身的代码能力。如果模型写不出正确的实现再好的 TDD skill 也只是让它更快地写出错误的代码。skill 的定位是放大已有的能力不是补足缺失的能力。想清楚这一点你就不会对 skill 抱不切实际的期待。6.4 心得从小处开始用真实任务验证别一上来就写十个 skill。先写一个 TDD skill拿一个真实的小任务比如给现有函数加参数校验跑一遍观察 agent 在哪一步卡壳、哪一步偷懒然后针对性改 skill。改完再跑反复几轮skill 才真正可用。这个过程没有捷径但每一轮都能让你更懂 agent 的行为模式。6.5 心得给 skill 加自检清单在 skill 正文末尾加一个 checklist让 agent 在结束前逐条自查。比如 TDD skill 的清单可以是每个测试用例是否都真实运行过并展示了输出是否每个循环只新增了一个测试重构后是否重新运行了全部测试是否有未处理的失败测试这个清单相当于给 agent 一个交卷前检查的动作能拦下不少低级失误。实测下来加了清单之后 agent 的假装完成明显减少。7. 把 agent-skills 用出长期价值agent-skills这类项目的真正价值不在于它自带几个 skill而在于它提供了一套把团队工程经验沉淀成 agent 可执行资产的范式。你今天写的 TDD skill明天可以扩展成数据库迁移 skillAPI 设计 skill发布流程 skill。每沉淀一个agent 在你项目里的专业度就高一截。我自己的做法是每次在 code review 里发现 agent 犯的重复性错误就想想这个能不能写成一条 skill 规则。能写就写写完验证。几个月下来agent 在我项目里的表现跟刚接入时完全是两个水平。这不是模型变强了是我把该教的都教给它了。如果你刚开始折腾我的建议是先别管 CLI 和目录规范就手写一个SKILL.md塞进项目让 agent 读跑一个真实任务感受一下按需加载的指令和常驻的 CLAUDE.md到底差在哪。感受过那个差异后面的一切就顺理成章了。 agent-skills 实战：用 TDD skill 让 AI coding agent 真正跑测试
1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套给 AI coding agent 用的能力包。它要解决的问题很具体——当你把 Claude Code 这类命令行 AI 编程助手接进项目之后会发现它默认只会聊天式改代码缺少一套可复用、可版本管理、可被 agent 自动加载的工程化技能。agent-skills干的就是把怎么让 agent 按测试驱动开发TDD的节奏干活怎么让 agent 遵守项目规范怎么让 agent 自己跑测试再改代码这些经验沉淀成结构化的 skill 文件让 agent 在需要的时候自动读取并执行。关键词里出现的skills CLI、test-driven-development、AI coding agents、Claude Code基本勾勒出了它的全貌这是一个围绕 AI 编程代理的技能编排层。它不训练模型也不改模型权重而是通过一套约定好的目录结构和元数据把人类工程师的最佳实践翻译成 agent 能理解的指令集。你可以把它理解成给 agent 装的插件系统——只不过插件的内容不是代码而是工作流。适合谁看三类人最该关注。第一类是把 Claude Code 当日常主力工具、但总觉得它不够听话的开发者第二类是团队里想把 AI 编码规范统一起来的 tech lead第三类是想自己写 skill、扩展 agent 能力边界的折腾党。如果你只是偶尔用 AI 补全几行代码这篇可能有点重但只要你开始让 agent 独立完成一个 feature、跑一轮测试、提交一次 PRagent-skills这套思路就值得认真拆一遍。下面我会从它的核心机制、目录结构、TDD skill 的落地方式、CLI 的用法、以及我自己踩过的坑几个角度把这块东西讲透。2. agent-skills 到底解决了什么痛点2.1 裸用 Claude Code 的三个典型翻车现场先说清楚没有 skills 的时候会发生什么你才能理解这套东西的价值。翻车一agent 改完代码不跑测试。你让它实现一个函数它噼里啪啦写完然后说完成。你一看边界条件没处理导入路径写错测试根本跑不过。它不会主动去跑pytest或npm test因为默认行为里没有验证这一步。翻车二每次都要重复交代规范。你的项目用 4 空格缩进、用ruff做 lint、commit message 遵循 conventional commits。这些你每次开新会话都得重新说一遍说漏一条它就自由发挥。上下文一长它还会忘。翻车三agent 不知道什么时候该做什么。面对加一个用户登录接口这种任务人类工程师知道要先写测试、再写实现、再重构。agent 不知道它会直接冲去写实现测试留到最后甚至不写。agent-skills的核心洞察就是这些不是模型能力问题是流程编排问题。模型足够聪明缺的是在正确的时机被喂正确的指令。skill 就是那个时机触发器。2.2 skill 和 prompt、和 CLAUDE.md 的区别很多人第一反应是这不就是写个 prompt 吗我放 CLAUDE.md 里不就行了区别在于加载时机和粒度。CLAUDE.md 是全局常驻的每次会话都塞进上下文写多了会稀释注意力而且它是静态规则不区分场景。skill 是按需加载的agent 判断当前任务需要测试驱动开发这个技能时才去读对应的 skill 文件读完执行完就释放。打个比方CLAUDE.md 像是贴在工位上的员工手册天天看skill 像是抽屉里的操作手册做特定工序时才翻出来。前者适合放永远成立的约束比如禁止提交密钥后者适合放特定任务才用的流程比如如何写一个符合 TDD 的 feature。这个区分非常关键因为它直接决定了你的上下文预算怎么花。上下文是稀缺资源常驻内容越少agent 在关键时刻的脑容量越充足。2.3 一个 skill 的最小构成一个标准的 skill 通常包含三部分元数据frontmattername、description、触发条件。agent 靠 description 判断这个 skill 跟当前任务相不相关。指令正文具体的工作流步骤用自然语言写但要求足够具体、可执行。辅助资源可选的脚本、模板、参考文件skill 正文里可以引用它们。元数据里的 description 是最容易被写砸的地方。写得太泛帮助写代码agent 永远匹配不上写得太窄当用户要求用 pytest 写一个带 mock 的异步测试时使用又几乎触发不了。好的 description 是任务类型 关键动作的组合比如实现新功能时按测试先行的顺序推进。3. 目录结构与 skill 的加载逻辑3.1 典型目录长什么样虽然agent-skills的具体文件我没法逐行给你但这类项目的目录约定高度一致我按通用实践给你还原一个可用的结构agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── tdd-checklist.md │ ├── code-review/ │ │ └── SKILL.md │ └── commit-convention/ │ └── SKILL.md ├── cli/ │ └── index.js └── README.md每个 skill 一个目录目录名就是 skill 的标识。核心文件是SKILL.md里面用 YAML frontmatter 声明元数据正文写指令。references/放那些正文太长、按需引用的补充材料。提示目录名和 frontmatter 里的 name 保持一致能省掉很多调试时的困惑。我见过有人目录叫tdd、name 写test-driven-development结果 CLI 按目录名索引、agent 按 name 匹配两边对不上skill 死活不触发。3.2 agent 是怎么发现skill 的加载逻辑分两步。第一步是索引agent 启动时扫描 skills 目录只读每个 SKILL.md 的 frontmatter把 name 和 description 装进一个轻量清单。这一步不读正文所以开销很小。第二步是匹配与加载当 agent 接到任务它拿任务描述去跟清单里的 description 做语义匹配命中哪个就把哪个的正文读进上下文。这个设计的好处是可扩展性。你装 50 个 skill启动时也只加载 50 条 description不会撑爆上下文。真正占空间的正文只在需要时进来。但这也带来一个坑description 的质量直接决定 skill 的命中率。我建议你写完 description 后拿几个真实任务描述去人肉匹配一遍看看能不能对上。对不上就改别指望 agent 比你聪明。3.3 优先级与冲突处理多个 skill 同时命中怎么办常见做法是给 skill 加priority字段或者靠 description 的 specificity 排序。更稳妥的做法是让 skill 之间职责不重叠。比如写测试和TDD 流程这两个 skill 就容易打架——前者只管写测试后者管整个测试-实现-重构循环。我的经验是把细粒度的 skill 作为粗粒度 skill 的子步骤引用而不是让它们平级竞争。4. TDD skill把工程纪律塞进 agent 的脑子里4.1 为什么 TDD 是 agent 最该学的第一课在所有 skill 里test-driven-development是最值得先做的原因很实在TDD 天然适合 agent。人类做 TDD 的痛苦在于忍住不先写实现很反人性但 agent 没有这个心理负担它只是执行指令。而且 TDD 的循环红-绿-重构是高度结构化的正好是 agent 擅长的按步骤执行。更妙的是测试本身就是可验证的反馈信号——agent 写完测试跑一遍红了写实现再跑绿了。这个反馈闭环让 agent 能自我纠错而不是写完就拍屁股走人。4.2 一个可落地的 TDD skill 正文该怎么写指令正文最忌讳写成你要遵循 TDD 原则这种空话。agent 需要的是可执行的动作序列。我推荐按这个骨架写先确认测试框架和运行命令。让 agent 读 package.json / pyproject.toml找到测试命令别猜。写一个失败的测试。明确要求只写一个测试用例覆盖当前要实现的最小行为。运行测试确认它失败。这一步不能省。如果测试直接通过说明要么测试写错了要么功能已存在都要停下来报告。写最小实现让测试通过。强调最小禁止顺手实现其他功能。再跑测试确认变绿。重构。在测试保护下清理代码重构后必须再跑一次测试。循环。回到第 2 步处理下一个行为。每一步都要写清楚运行什么命令看到什么结果才算通过不通过怎么办。比如第 3 步可以写运行测试命令。如果测试通过而非失败停止当前循环向用户报告测试未按预期失败可能功能已实现或测试断言有误。4.3 让 agent 真的去跑命令而不是假装跑这是 TDD skill 能不能生效的生死线。很多 agent 会脑补测试结果——它写完测试不去执行直接说测试通过。你必须用强指令堵死这条路。有效的写法是明确要求 agent展示命令输出。比如每次运行测试后把完整的命令和输出粘贴到回复里。没有真实输出的测试通过一律视为未完成。 这句话看着啰嗦但实测能显著降低 agent 偷懒的概率。另外如果你的 agent 环境支持工具调用比如 Claude Code 的 Bash 工具要在 skill 里明确使用终端工具执行测试命令而不是让它在脑子里模拟。工具调用是硬约束脑补是软约束能上硬的就别用软的。4.4 测试粒度agent 最容易失控的地方agent 写测试有个通病一次写一大堆。你让它实现一个计算器它一口气写 20 个测试用例然后开始逐个实现循环节奏全乱了。skill 里必须限制粒度。我的做法是加一条硬规则每个循环只允许新增一个测试用例。新增第二个测试前必须确认前一个已经变绿。 这条规则把 agent 拉回小步快跑的节奏也让每次失败的范围可控——出问题时你知道是哪个行为没实现而不是面对一片红。5. skills CLI安装、管理与调试5.1 CLI 存在的意义有人会问skill 不就是几个 markdown 文件吗我手动拷进项目不就行了要 CLI 干嘛CLI 解决的是分发和版本管理。手动拷贝的问题在于skill 更新了你怎么同步多个项目怎么共享团队里怎么保证大家用的是同一版CLI 把这些变成一条命令的事。典型用法是skills install name把某个 skill 装进当前项目的 skills 目录skills list看装了哪些skills update拉最新版。5.2 安装与初始化按通用实践流程大概是这样# 全局安装 CLI npm install -g agent-skills-cli # 在项目里初始化 skills 目录 skills init # 安装 TDD skill skills install test-driven-development # 查看已安装 skills listskills init通常会创建skills/目录并生成一个配置文件记录 skill 的来源和版本。这个配置文件要提交到 git这样团队成员 clone 之后跑一次skills sync就能对齐。注意CLI 的包名和命令名在不同项目里可能不一样装之前先看 README 的 Quick Start别照着记忆里的命令硬敲。我踩过一次把skills敲成了另一个同名工具装了一堆不相干的东西。5.3 调试 skill 不生效的问题skill 装了但 agent 不用是最常见的求助。排查顺序我总结成一张表现象可能原因排查动作agent 完全不提 skilldescription 匹配不上拿任务描述手动比对 descriptionagent 提了但没执行正文指令太抽象检查是否有可执行命令和验证步骤执行了但中途跑偏缺少边界约束补充禁止做什么的负面指令时灵时不灵上下文被挤占精简 CLAUDE.md给 skill 留空间我遇到最多的是第一类。description 写得太文学比如帮助开发者写出优雅的代码agent 根本不知道什么时候该用。改成实现新功能时按测试先行的顺序推进每个循环只加一个测试之后命中率立刻上来了。5.4 多 skill 协同的编排思路当你有 TDD、code-review、commit-convention 三个 skill 时理想状态是它们能串成一条流水线TDD 负责实现code-review 负责检查commit-convention 负责提交。但 agent 不会自动串你得在 skill 里写交接指令。比如 TDD skill 的最后一步可以写所有测试通过后提示用户或自动触发 code-review skill 进行代码审查。 这样 skill 之间就有了调用关系。不过要注意别搞成无限套娃交接链超过三层agent 就容易迷失。6. 我踩过的坑和几条实操心得6.1 坑一skill 写成了教科书我第一版 TDD skill 写了满满一页 TDD 的历史、原则、好处结果 agent 读完该干嘛还是干嘛。后来我把它砍到只剩动作步骤效果立竿见影。skill 是操作手册不是科普文章。每一句话都要能对应到一个动作或一个判断否则就是噪音。6.2 坑二忽略了失败路径新手写 skill 只写顺利情况写测试、跑测试、写实现、跑测试、通过。但真实开发里测试跑不起来环境问题、测试一直红实现有 bug、测试意外绿了断言写错都是常态。skill 里必须为这些分支写清楚停下来报告什么。agent 遇到没写过的分支默认行为往往是硬着头皮往下走结果越走越偏。6.3 坑三把 skill 当成了万能药skill 能规范流程但不能提升模型本身的代码能力。如果模型写不出正确的实现再好的 TDD skill 也只是让它更快地写出错误的代码。skill 的定位是放大已有的能力不是补足缺失的能力。想清楚这一点你就不会对 skill 抱不切实际的期待。6.4 心得从小处开始用真实任务验证别一上来就写十个 skill。先写一个 TDD skill拿一个真实的小任务比如给现有函数加参数校验跑一遍观察 agent 在哪一步卡壳、哪一步偷懒然后针对性改 skill。改完再跑反复几轮skill 才真正可用。这个过程没有捷径但每一轮都能让你更懂 agent 的行为模式。6.5 心得给 skill 加自检清单在 skill 正文末尾加一个 checklist让 agent 在结束前逐条自查。比如 TDD skill 的清单可以是每个测试用例是否都真实运行过并展示了输出是否每个循环只新增了一个测试重构后是否重新运行了全部测试是否有未处理的失败测试这个清单相当于给 agent 一个交卷前检查的动作能拦下不少低级失误。实测下来加了清单之后 agent 的假装完成明显减少。7. 把 agent-skills 用出长期价值agent-skills这类项目的真正价值不在于它自带几个 skill而在于它提供了一套把团队工程经验沉淀成 agent 可执行资产的范式。你今天写的 TDD skill明天可以扩展成数据库迁移 skillAPI 设计 skill发布流程 skill。每沉淀一个agent 在你项目里的专业度就高一截。我自己的做法是每次在 code review 里发现 agent 犯的重复性错误就想想这个能不能写成一条 skill 规则。能写就写写完验证。几个月下来agent 在我项目里的表现跟刚接入时完全是两个水平。这不是模型变强了是我把该教的都教给它了。如果你刚开始折腾我的建议是先别管 CLI 和目录规范就手写一个SKILL.md塞进项目让 agent 读跑一个真实任务感受一下按需加载的指令和常驻的 CLAUDE.md到底差在哪。感受过那个差异后面的一切就顺理成章了。