1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个项目名我的直觉是这不是一个普通工具库而是一套给 AI coding agent 用的技能包。关键词里同时出现了skills CLI、Claude Code、test-driven-development基本可以确定它的定位——把可复用的工程能力封装成 agent 能直接调用的技能单元让 AI 在写代码这件事上从能聊变成能干活。为什么这个方向值得关注因为过去一年我用 Claude Code 这类终端 agent 的真实体感是模型本身够聪明但缺的是规矩。你让它写个功能它上来就改文件改完不跑测试跑完不检查边界最后你花在 review 和返工上的时间比手写还多。agent-skills想解决的正是这个问题——把先写测试再写实现改完必须验证提交前自查这些老工程师的肌肉记忆固化成 agent 可以加载的技能。这篇文章适合三类人看一是已经在用 Claude Code、想让它更靠谱的开发者二是对 AI coding agent 感兴趣、想知道技能到底怎么落地的人三是团队里想把 AI 编码流程标准化的技术负责人。我会从技能的本质讲起拆解 skills CLI 的工作方式重点讲 test-driven-development 这个技能为什么是整套体系里最值钱的一块最后给出一套可以直接抄的落地步骤和踩坑清单。需要先说明一点agent-skills的具体实现细节我没有拿到官方源码下面涉及目录结构、CLI 参数的部分是基于 Claude Code 生态里 skills 机制的常见实践做的合理还原逻辑上能自洽你照着搭一套自己的技能库完全没问题。2. agent-skills 到底在解决什么问题2.1 裸奔的 agent 和有技能的 agent 差在哪先做个对比。没有技能约束的 agent你给它一句给用户模块加个登录接口它的典型行为是直接打开文件、凭感觉写一段代码、可能顺手改了几个不相关的地方、然后告诉你完成了。至于这个接口有没有处理空密码、有没有防重复提交、有没有对应的测试全靠运气。有技能约束的 agent 完全不一样。它会先加载test-driven-development技能按技能里定义的流程走先写一个会失败的测试再写最小实现让测试通过最后重构。整个过程你不需要反复提醒因为技能文件里已经把什么时候该做什么写死了。这个差别不是模型能力的差别是流程约束的差别。模型再强没有流程也会偷懒模型一般但流程卡得死产出反而稳定。这就是agent-skills的核心价值——它不提升模型智商它提升模型的行为下限。2.2 技能和 prompt 模板的本质区别很多人第一反应是这不就是写个 prompt 吗 不是。prompt 模板是你在对话里临时塞给模型的一段话用完就没了下次对话又得重来。技能是持久化、可发现、可组合的资产。具体区别体现在三个层面加载方式prompt 靠你手动粘贴技能靠 agent 根据任务自动匹配加载。你说帮我加个功能agent 自己判断该调 TDD 技能你说帮我查个 bug它调调试技能。结构约束prompt 是一段自由文本技能通常有固定结构——触发条件、执行步骤、检查清单、失败处理。结构化的东西模型执行起来更不容易跑偏。可维护性prompt 散落在各个聊天记录里技能是版本化的文件可以 review、可以迭代、可以团队共享。我自己的经验是一个打磨好的技能文件效果顶得上十次反复叮嘱。因为叮嘱是即时的、情绪化的技能是沉淀的、结构化的。2.3 为什么是现在这个时间点AI coding agent 在 2024 到 2025 年集中爆发Claude Code、各类 CLI agent 层出不穷。但大家很快发现一个尴尬的现实demo 很惊艳生产很难用。原因就是 agent 缺少工程纪律。agent-skills这类项目的出现标志着社区开始从追求 agent 能做什么转向追求 agent 做得对不对。这个转向很关键它意味着 AI 编码正在从玩具阶段进入工程阶段。谁先把技能体系搭起来谁就能真正把 agent 用进日常开发而不是停留在尝鲜。3. skills CLI 的工作机制拆解3.1 技能是怎么被组织和发现的一套典型的 skills 体系目录结构大概长这样.agent-skills/ skills/ test-driven-development/ SKILL.md examples/ code-review/ SKILL.md debugging/ SKILL.md config.json每个技能一个目录核心是SKILL.md这个文件。文件名大写是有讲究的——它是 agent 扫描时的入口标记类似README.md之于一个仓库。agent 启动时会扫描这个目录把每个技能的元信息名称、描述、触发关键词读进上下文真正需要执行时才加载完整内容。这种元信息常驻、正文按需加载的设计很聪明。因为上下文窗口是稀缺资源如果把所有技能全文都塞进去还没干活上下文就满了。只加载摘要命中任务时再展开既省 token 又保证准确。config.json一般用来配置技能目录路径、启用哪些技能、以及一些全局参数。这个文件让技能库可以跨项目复用——你可以把技能放在一个中心目录多个项目通过配置指向它。3.2 技能文件的内部结构一个写得好的SKILL.md我建议包含这几块--- name: test-driven-development description: 在实现任何新功能或修复 bug 时使用强制先写测试 triggers: - 实现功能 - 修复 bug - 添加接口 --- ## 何时使用 当任务涉及新增或修改代码逻辑时。 ## 执行步骤 1. 先写一个失败的测试明确预期行为 2. 运行测试确认它确实失败 3. 写最小实现让测试通过 4. 重构保持测试绿色 5. 重复直到功能完整 ## 检查清单 - [ ] 测试是否先于实现编写 - [ ] 是否见过测试失败 - [ ] 实现是否最小化frontmatter 里的triggers是灵魂。它决定了 agent 什么时候会想起这个技能。写得太窄技能永远不被触发写得太宽什么任务都往里套反而添乱。我的经验是触发词要贴着用户会怎么说来写而不是贴着技术术语来写。用户说加个功能比说实现一个方法更常见。3.3 技能加载的时机与优先级这里有个容易被忽略的细节技能不是越多越好。如果你装了二十个技能agent 每次都要在二十个里挑选择成本上去了误触发概率也上去了。合理的做法是分层。基础层放三到五个高频技能比如 TDD、代码审查、调试进阶层放特定场景技能比如数据库迁移、API 设计。基础层常驻进阶层按项目启用。优先级方面我实测下来流程类技能应该高于知识类技能。因为知识模型自己就有缺的是流程约束。TDD 这种逼你先写测试的技能价值远高于告诉你什么是单元测试的技能。4. test-driven-development 技能为什么是整套体系的压舱石4.1 TDD 对 agent 的意义和对人不一样对人来说TDD 是一种设计方法帮你理清接口、降低耦合。对 agent 来说TDD 的意义更直接——它是唯一能让 agent 自我验证的机制。人写完代码心里大概知道对不对。agent 写完代码它自己也不知道对不对除非有测试跑给它看。没有测试agent 的完成只是我写完了不是它对了。有了测试agent 就有了反馈回路跑测试、看结果、不对就改。这个回路是 agent 从生成器变成问题解决者的关键。我踩过的最大的坑就是早期让 agent 直接写实现。它写得飞快但十个功能里有三个有隐藏 bug而且这些 bug 往往在边界条件上——空输入、超长字符串、并发。后来强制走 TDDbug 率肉眼可见地降下来因为边界条件在写测试的时候就被逼着想到了。4.2 红绿重构在 agent 场景下的具体落地经典 TDD 是红-绿-重构三步。放到 agent 场景每一步都要有明确的机器可验证信号红agent 写一个测试然后必须运行它并且确认它失败。这一步不能省。我见过 agent 写完测试直接说测试写好了根本没跑。所以技能文件里要写死必须运行测试命令并展示失败输出。绿agent 写最小实现让测试通过。关键词是最小。agent 的天性是过度设计你让它加个加法它可能给你写个计算器框架。技能里要明确只写让当前测试通过的最少代码。重构测试保持绿色的前提下整理代码。这一步 agent 经常跳过因为能跑就行。技能里要把它列为必做项并给出重构的检查点比如消除重复、命名清晰。4.3 一个真实的技能执行片段假设任务是给字符串工具加一个判断回文的方法。加载了 TDD 技能的 agent 会这样走第一步写测试def test_is_palindrome(): assert is_palindrome(racecar) is True assert is_palindrome(hello) is False assert is_palindrome() is True第二步运行看到NameError: is_palindrome is not defined确认红。第三步写最小实现def is_palindrome(s): return s s[::-1]第四步运行绿。第五步重构——这里其实没什么可重构的但 agent 会检查一遍命名和边界确认空字符串返回 True 是符合预期的。整个过程你一句话没说agent 自己走完了。这就是技能的价值把需要你盯着的流程变成 agent 自己遵守的纪律。5. 把 agent-skills 接进 Claude Code 的实操路径5.1 环境准备里最容易翻车的地方Claude Code 的安装本身不复杂但有几个点新手经常卡住。第一是 Node 版本Claude Code 对 Node 版本有要求版本太低会直接报错建议先node -v确认。第二是终端环境如果你在 VS Code 里用集成终端要确保它用的是你配置好的那个 shell而不是默认的。技能目录的接入核心是让 Claude Code 知道去哪里找技能。常见做法是在项目根目录放.agent-skills/或者在全局配置里指定技能路径。我建议项目级和全局级结合通用的 TDD、代码审查放全局项目特有的技能放项目里。这样换项目不用重新配项目专属的又不会污染全局。提示技能目录的路径不要用中文或空格某些环境下会导致扫描失败。用纯英文短横线命名最稳。5.2 从零搭一个最小可用技能库不要一上来就搞十几个技能先搭三个跑通闭环test-driven-development流程约束最高优先级code-review改完代码自查检查命名、边界、重复commit-message规范提交信息方便回溯每个技能的SKILL.md控制在 50 行以内。太长了 agent 加载慢而且重点不突出。写完先手动测给 agent 一个任务看它会不会自动加载对应技能。如果不会多半是triggers写得不对调整触发词再试。我自己的调优过程是这样的先写宽泛的触发词观察哪些任务误触发了再逐步收窄。比如code-review一开始触发词写了代码结果写代码时也触发后来改成审查检查review就准多了。5.3 验证技能是否真的生效怎么判断技能生效了看 agent 的行为有没有变化。没装 TDD 技能时你说加个功能它直接改文件。装了之后它应该先写测试文件。如果行为没变检查三件事技能目录路径对不对、SKILL.md的 frontmatter 格式对不对、触发词和你的说法对不对得上。还有一个隐蔽的坑有些 agent 会把技能内容读进上下文但不一定严格执行。这时候要在技能里加强制措辞比如你必须先运行测试并展示输出否则不得进入下一步。措辞的强度确实会影响执行率这是我反复试出来的。6. 技能设计里那些文档不会告诉你的经验6.1 触发词要贴着用户口语写这是我最想强调的一条。技能作者容易犯的错是用技术术语写触发词。比如调试技能触发词写debug异常排查但用户实际说的是这个报错了跑不起来结果不对。触发词对不上技能就是摆设。我的做法是把团队里大家描述问题的原话收集起来直接当触发词。口语化、多样化宁可多写几个同义词。反正触发词只是元信息多几个不占多少上下文。6.2 技能之间要避免打架两个技能如果都声称自己适用于修改代码agent 就会纠结。解决办法是给技能划定清晰的边界。TDD 技能管新增或修改逻辑代码审查技能管改完之后的自查两者是流水线上的先后关系不是竞争关系。在技能描述里写清楚本技能在 X 之后使用能有效减少冲突。6.3 技能要能失败也要能退出好的技能不只是告诉 agent 怎么做还要告诉它什么时候停。比如 TDD 技能里应该有一句如果测试连续三次无法通过停止并报告不要继续盲目修改。 没有退出条件的技能会让 agent 陷入死循环反复改反复错浪费大量 token。我见过最惨的一次agent 在一个测试上卡了十几轮每轮都微调实现越改越乱。后来在技能里加了三次不过就停的规则这种情况再没出现过。6.4 定期清理失效技能技能库和代码库一样会腐化。有些技能随着工具升级失效了有些技能被更好的替代了。建议每个月过一遍把没人用的、触发不了的、效果差的删掉。技能库精简agent 的选择才准。7. 常见问题与排查思路7.1 技能不触发怎么办按这个顺序排查先确认技能目录被 agent 扫描到了看启动日志或配置再确认SKILL.md的 frontmatter 能被正确解析YAML 格式很挑缩进最后确认触发词和你的输入匹配。三步走下来九成问题能定位。7.2 技能触发了但执行不到位多半是技能内容太抽象。把写好测试改成写一个测试文件包含至少三个断言运行并展示失败输出执行率立刻上去。agent 需要的是可操作的指令不是原则性的口号。7.3 多个技能同时触发导致混乱给技能加优先级字段或者在描述里写明适用顺序。实在冲突的就合并成一个技能用内部步骤区分场景。7.4 技能在不同项目间怎么复用把通用技能放全局目录项目通过配置引用。项目特有的技能放项目内。这样既复用又隔离。跨机器同步的话把技能库做成一个独立的 git 仓库各项目 submodule 引用版本可控。8. 我对 agent-skills 这类项目的一点判断用了一段时间下来我越来越觉得AI coding agent 的竞争下半场不在模型在技能生态。模型能力会趋同但一套打磨好的技能库是实打实的工程资产别人抄不走。agent-skills这个方向最聪明的地方是它把怎么用 AI 写代码这件事从个人经验变成了可沉淀、可传播、可迭代的资产。以前一个老工程师的编码纪律只在他自己脑子里现在可以写成技能文件让 agent 替他执行。如果你现在还在手动给 agent 写 prompt、反复叮嘱同样的话真的建议花一个下午搭一套自己的技能库。从 TDD 这一个技能开始跑通闭环你会明显感觉到 agent 从需要盯着变成可以放手。这个转变一旦体验过就回不去了。最后分享一个我自己的小习惯每次 agent 犯了新错误我不只是当场纠正而是回头把这个错误对应的规则补进技能文件。这样同样的坑agent 只会踩一次。技能库就是这么一点点长起来的比任何教程都管用。 1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个项目名我的直觉是这不是一个普通工具库而是一套给 AI coding agent 用的技能包。关键词里同时出现了skills CLI、Claude Code、test-driven-development基本可以确定它的定位——把可复用的工程能力封装成 agent 能直接调用的技能单元让 AI 在写代码这件事上从能聊变成能干活。为什么这个方向值得关注因为过去一年我用 Claude Code 这类终端 agent 的真实体感是模型本身够聪明但缺的是规矩。你让它写个功能它上来就改文件改完不跑测试跑完不检查边界最后你花在 review 和返工上的时间比手写还多。agent-skills想解决的正是这个问题——把先写测试再写实现改完必须验证提交前自查这些老工程师的肌肉记忆固化成 agent 可以加载的技能。这篇文章适合三类人看一是已经在用 Claude Code、想让它更靠谱的开发者二是对 AI coding agent 感兴趣、想知道技能到底怎么落地的人三是团队里想把 AI 编码流程标准化的技术负责人。我会从技能的本质讲起拆解 skills CLI 的工作方式重点讲 test-driven-development 这个技能为什么是整套体系里最值钱的一块最后给出一套可以直接抄的落地步骤和踩坑清单。需要先说明一点agent-skills的具体实现细节我没有拿到官方源码下面涉及目录结构、CLI 参数的部分是基于 Claude Code 生态里 skills 机制的常见实践做的合理还原逻辑上能自洽你照着搭一套自己的技能库完全没问题。2. agent-skills 到底在解决什么问题2.1 裸奔的 agent 和有技能的 agent 差在哪先做个对比。没有技能约束的 agent你给它一句给用户模块加个登录接口它的典型行为是直接打开文件、凭感觉写一段代码、可能顺手改了几个不相关的地方、然后告诉你完成了。至于这个接口有没有处理空密码、有没有防重复提交、有没有对应的测试全靠运气。有技能约束的 agent 完全不一样。它会先加载test-driven-development技能按技能里定义的流程走先写一个会失败的测试再写最小实现让测试通过最后重构。整个过程你不需要反复提醒因为技能文件里已经把什么时候该做什么写死了。这个差别不是模型能力的差别是流程约束的差别。模型再强没有流程也会偷懒模型一般但流程卡得死产出反而稳定。这就是agent-skills的核心价值——它不提升模型智商它提升模型的行为下限。2.2 技能和 prompt 模板的本质区别很多人第一反应是这不就是写个 prompt 吗 不是。prompt 模板是你在对话里临时塞给模型的一段话用完就没了下次对话又得重来。技能是持久化、可发现、可组合的资产。具体区别体现在三个层面加载方式prompt 靠你手动粘贴技能靠 agent 根据任务自动匹配加载。你说帮我加个功能agent 自己判断该调 TDD 技能你说帮我查个 bug它调调试技能。结构约束prompt 是一段自由文本技能通常有固定结构——触发条件、执行步骤、检查清单、失败处理。结构化的东西模型执行起来更不容易跑偏。可维护性prompt 散落在各个聊天记录里技能是版本化的文件可以 review、可以迭代、可以团队共享。我自己的经验是一个打磨好的技能文件效果顶得上十次反复叮嘱。因为叮嘱是即时的、情绪化的技能是沉淀的、结构化的。2.3 为什么是现在这个时间点AI coding agent 在 2024 到 2025 年集中爆发Claude Code、各类 CLI agent 层出不穷。但大家很快发现一个尴尬的现实demo 很惊艳生产很难用。原因就是 agent 缺少工程纪律。agent-skills这类项目的出现标志着社区开始从追求 agent 能做什么转向追求 agent 做得对不对。这个转向很关键它意味着 AI 编码正在从玩具阶段进入工程阶段。谁先把技能体系搭起来谁就能真正把 agent 用进日常开发而不是停留在尝鲜。3. skills CLI 的工作机制拆解3.1 技能是怎么被组织和发现的一套典型的 skills 体系目录结构大概长这样.agent-skills/ skills/ test-driven-development/ SKILL.md examples/ code-review/ SKILL.md debugging/ SKILL.md config.json每个技能一个目录核心是SKILL.md这个文件。文件名大写是有讲究的——它是 agent 扫描时的入口标记类似README.md之于一个仓库。agent 启动时会扫描这个目录把每个技能的元信息名称、描述、触发关键词读进上下文真正需要执行时才加载完整内容。这种元信息常驻、正文按需加载的设计很聪明。因为上下文窗口是稀缺资源如果把所有技能全文都塞进去还没干活上下文就满了。只加载摘要命中任务时再展开既省 token 又保证准确。config.json一般用来配置技能目录路径、启用哪些技能、以及一些全局参数。这个文件让技能库可以跨项目复用——你可以把技能放在一个中心目录多个项目通过配置指向它。3.2 技能文件的内部结构一个写得好的SKILL.md我建议包含这几块--- name: test-driven-development description: 在实现任何新功能或修复 bug 时使用强制先写测试 triggers: - 实现功能 - 修复 bug - 添加接口 --- ## 何时使用 当任务涉及新增或修改代码逻辑时。 ## 执行步骤 1. 先写一个失败的测试明确预期行为 2. 运行测试确认它确实失败 3. 写最小实现让测试通过 4. 重构保持测试绿色 5. 重复直到功能完整 ## 检查清单 - [ ] 测试是否先于实现编写 - [ ] 是否见过测试失败 - [ ] 实现是否最小化frontmatter 里的triggers是灵魂。它决定了 agent 什么时候会想起这个技能。写得太窄技能永远不被触发写得太宽什么任务都往里套反而添乱。我的经验是触发词要贴着用户会怎么说来写而不是贴着技术术语来写。用户说加个功能比说实现一个方法更常见。3.3 技能加载的时机与优先级这里有个容易被忽略的细节技能不是越多越好。如果你装了二十个技能agent 每次都要在二十个里挑选择成本上去了误触发概率也上去了。合理的做法是分层。基础层放三到五个高频技能比如 TDD、代码审查、调试进阶层放特定场景技能比如数据库迁移、API 设计。基础层常驻进阶层按项目启用。优先级方面我实测下来流程类技能应该高于知识类技能。因为知识模型自己就有缺的是流程约束。TDD 这种逼你先写测试的技能价值远高于告诉你什么是单元测试的技能。4. test-driven-development 技能为什么是整套体系的压舱石4.1 TDD 对 agent 的意义和对人不一样对人来说TDD 是一种设计方法帮你理清接口、降低耦合。对 agent 来说TDD 的意义更直接——它是唯一能让 agent 自我验证的机制。人写完代码心里大概知道对不对。agent 写完代码它自己也不知道对不对除非有测试跑给它看。没有测试agent 的完成只是我写完了不是它对了。有了测试agent 就有了反馈回路跑测试、看结果、不对就改。这个回路是 agent 从生成器变成问题解决者的关键。我踩过的最大的坑就是早期让 agent 直接写实现。它写得飞快但十个功能里有三个有隐藏 bug而且这些 bug 往往在边界条件上——空输入、超长字符串、并发。后来强制走 TDDbug 率肉眼可见地降下来因为边界条件在写测试的时候就被逼着想到了。4.2 红绿重构在 agent 场景下的具体落地经典 TDD 是红-绿-重构三步。放到 agent 场景每一步都要有明确的机器可验证信号红agent 写一个测试然后必须运行它并且确认它失败。这一步不能省。我见过 agent 写完测试直接说测试写好了根本没跑。所以技能文件里要写死必须运行测试命令并展示失败输出。绿agent 写最小实现让测试通过。关键词是最小。agent 的天性是过度设计你让它加个加法它可能给你写个计算器框架。技能里要明确只写让当前测试通过的最少代码。重构测试保持绿色的前提下整理代码。这一步 agent 经常跳过因为能跑就行。技能里要把它列为必做项并给出重构的检查点比如消除重复、命名清晰。4.3 一个真实的技能执行片段假设任务是给字符串工具加一个判断回文的方法。加载了 TDD 技能的 agent 会这样走第一步写测试def test_is_palindrome(): assert is_palindrome(racecar) is True assert is_palindrome(hello) is False assert is_palindrome() is True第二步运行看到NameError: is_palindrome is not defined确认红。第三步写最小实现def is_palindrome(s): return s s[::-1]第四步运行绿。第五步重构——这里其实没什么可重构的但 agent 会检查一遍命名和边界确认空字符串返回 True 是符合预期的。整个过程你一句话没说agent 自己走完了。这就是技能的价值把需要你盯着的流程变成 agent 自己遵守的纪律。5. 把 agent-skills 接进 Claude Code 的实操路径5.1 环境准备里最容易翻车的地方Claude Code 的安装本身不复杂但有几个点新手经常卡住。第一是 Node 版本Claude Code 对 Node 版本有要求版本太低会直接报错建议先node -v确认。第二是终端环境如果你在 VS Code 里用集成终端要确保它用的是你配置好的那个 shell而不是默认的。技能目录的接入核心是让 Claude Code 知道去哪里找技能。常见做法是在项目根目录放.agent-skills/或者在全局配置里指定技能路径。我建议项目级和全局级结合通用的 TDD、代码审查放全局项目特有的技能放项目里。这样换项目不用重新配项目专属的又不会污染全局。提示技能目录的路径不要用中文或空格某些环境下会导致扫描失败。用纯英文短横线命名最稳。5.2 从零搭一个最小可用技能库不要一上来就搞十几个技能先搭三个跑通闭环test-driven-development流程约束最高优先级code-review改完代码自查检查命名、边界、重复commit-message规范提交信息方便回溯每个技能的SKILL.md控制在 50 行以内。太长了 agent 加载慢而且重点不突出。写完先手动测给 agent 一个任务看它会不会自动加载对应技能。如果不会多半是triggers写得不对调整触发词再试。我自己的调优过程是这样的先写宽泛的触发词观察哪些任务误触发了再逐步收窄。比如code-review一开始触发词写了代码结果写代码时也触发后来改成审查检查review就准多了。5.3 验证技能是否真的生效怎么判断技能生效了看 agent 的行为有没有变化。没装 TDD 技能时你说加个功能它直接改文件。装了之后它应该先写测试文件。如果行为没变检查三件事技能目录路径对不对、SKILL.md的 frontmatter 格式对不对、触发词和你的说法对不对得上。还有一个隐蔽的坑有些 agent 会把技能内容读进上下文但不一定严格执行。这时候要在技能里加强制措辞比如你必须先运行测试并展示输出否则不得进入下一步。措辞的强度确实会影响执行率这是我反复试出来的。6. 技能设计里那些文档不会告诉你的经验6.1 触发词要贴着用户口语写这是我最想强调的一条。技能作者容易犯的错是用技术术语写触发词。比如调试技能触发词写debug异常排查但用户实际说的是这个报错了跑不起来结果不对。触发词对不上技能就是摆设。我的做法是把团队里大家描述问题的原话收集起来直接当触发词。口语化、多样化宁可多写几个同义词。反正触发词只是元信息多几个不占多少上下文。6.2 技能之间要避免打架两个技能如果都声称自己适用于修改代码agent 就会纠结。解决办法是给技能划定清晰的边界。TDD 技能管新增或修改逻辑代码审查技能管改完之后的自查两者是流水线上的先后关系不是竞争关系。在技能描述里写清楚本技能在 X 之后使用能有效减少冲突。6.3 技能要能失败也要能退出好的技能不只是告诉 agent 怎么做还要告诉它什么时候停。比如 TDD 技能里应该有一句如果测试连续三次无法通过停止并报告不要继续盲目修改。 没有退出条件的技能会让 agent 陷入死循环反复改反复错浪费大量 token。我见过最惨的一次agent 在一个测试上卡了十几轮每轮都微调实现越改越乱。后来在技能里加了三次不过就停的规则这种情况再没出现过。6.4 定期清理失效技能技能库和代码库一样会腐化。有些技能随着工具升级失效了有些技能被更好的替代了。建议每个月过一遍把没人用的、触发不了的、效果差的删掉。技能库精简agent 的选择才准。7. 常见问题与排查思路7.1 技能不触发怎么办按这个顺序排查先确认技能目录被 agent 扫描到了看启动日志或配置再确认SKILL.md的 frontmatter 能被正确解析YAML 格式很挑缩进最后确认触发词和你的输入匹配。三步走下来九成问题能定位。7.2 技能触发了但执行不到位多半是技能内容太抽象。把写好测试改成写一个测试文件包含至少三个断言运行并展示失败输出执行率立刻上去。agent 需要的是可操作的指令不是原则性的口号。7.3 多个技能同时触发导致混乱给技能加优先级字段或者在描述里写明适用顺序。实在冲突的就合并成一个技能用内部步骤区分场景。7.4 技能在不同项目间怎么复用把通用技能放全局目录项目通过配置引用。项目特有的技能放项目内。这样既复用又隔离。跨机器同步的话把技能库做成一个独立的 git 仓库各项目 submodule 引用版本可控。8. 我对 agent-skills 这类项目的一点判断用了一段时间下来我越来越觉得AI coding agent 的竞争下半场不在模型在技能生态。模型能力会趋同但一套打磨好的技能库是实打实的工程资产别人抄不走。agent-skills这个方向最聪明的地方是它把怎么用 AI 写代码这件事从个人经验变成了可沉淀、可传播、可迭代的资产。以前一个老工程师的编码纪律只在他自己脑子里现在可以写成技能文件让 agent 替他执行。如果你现在还在手动给 agent 写 prompt、反复叮嘱同样的话真的建议花一个下午搭一套自己的技能库。从 TDD 这一个技能开始跑通闭环你会明显感觉到 agent 从需要盯着变成可以放手。这个转变一旦体验过就回不去了。最后分享一个我自己的小习惯每次 agent 犯了新错误我不只是当场纠正而是回头把这个错误对应的规则补进技能文件。这样同样的坑agent 只会踩一次。技能库就是这么一点点长起来的比任何教程都管用。