1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识地把它理解成给 AI 智能体加几个技能包这么简单。但如果你真的在 AI coding agents 这条线上摸爬滚打过一段时间就会明白它背后其实藏着一个非常硬核的工程问题如何把散落在提示词、脚本、测试用例、项目约定里的隐性经验沉淀成一套可复用、可版本管理、可被 agent 自动加载的显性技能。我最初接触这个概念是在用 Claude Code 做日常开发的时候。当时我的工作流很原始——每次开新会话都要把项目规范、代码风格、测试命令、目录结构重新讲一遍。讲一次两次还行讲到第十次的时候我就烦了这些东西明明可以写下来为什么每次都要靠嘴喂给 agent后来我开始把这些约定写进项目根目录的说明文件里再后来发现社区里已经有人把这件事做成了体系也就是所谓的agent-skills加skills CLI这套组合拳。简单说agent-skills解决的是这样一个问题让 AI coding agent 在进入一个项目时能自动知道这个项目该怎么写代码、怎么跑测试、怎么提交、有哪些坑不能踩。它不是一个具体的软件而更像一套约定俗成的目录结构和加载机制。配合skills CLI这类工具你可以把技能定义成一个个独立的小文件按需加载、按项目切换。对于天天和 Claude Code、VS Code 插件、终端命令打交道的人来说这套东西一旦用顺了效率提升是肉眼可见的。这篇文章适合三类人看第一类是把 Claude Code 当主力开发工具、但还在每次重新解释项目阶段的人第二类是听说过agent-skills但不知道从哪下手的人第三类是想把团队开发规范固化下来、让 agent 和人都遵守同一套规则的人。我会从设计思路讲到目录结构从技能编写讲到和 test-driven-development 的结合再把我踩过的坑和排查经验一并倒出来。全程按我自己的实操节奏来不整那些虚的。2. agent-skills 的整体设计与思路拆解2.1 为什么需要技能这层抽象要理解agent-skills的价值得先理解当前 AI coding agent 的一个根本矛盾模型的上下文窗口是有限的但项目的知识是无限的。你不可能把整个代码库、所有历史提交、所有团队约定都塞进一次对话里。那怎么办答案是分层——把最稳定、最通用、最需要反复用到的知识抽成独立的技能单元在需要的时候精准加载。这就像公司里的新人培训。你不会让新人把公司十年的文档全读一遍再上岗而是给他一份岗位手册里面写着这个岗位最常用的操作、最容易犯的错、必须遵守的规范。agent-skills就是给 AI agent 准备的岗位手册。每个 skill 是一个自包含的小单元描述在什么场景下、该做什么、不该做什么、怎么验证做对了。我试过两种极端做法。第一种是什么都不写全靠每次对话临时说明——结果是重复劳动而且 agent 经常忘记之前的约定。第二种是把所有规范塞进一个巨大的说明文件——结果是每次加载都消耗大量上下文真正关键的信息反而被淹没。agent-skills走的是中间路线按需加载、模块化组织、显式声明触发条件。这个设计思路和软件工程里的关注点分离是一脉相承的。2.2 目录结构背后的取舍一个典型的agent-skills目录大概长这样.agent-skills/ skills/ testing/ SKILL.md examples/ code-style/ SKILL.md git-workflow/ SKILL.md config.yaml这个结构不是随便定的。skills/下面每个子目录代表一个独立技能SKILL.md是这个技能的说明书examples/放具体示例。config.yaml负责声明哪些技能默认启用、哪些按需加载。为什么用 Markdown 而不是 JSON 或 YAML 来写技能定义因为 agent 读 Markdown 的效果明显更好。Markdown 有天然的层级结构模型能清楚区分标题正文代码块注意事项。我实测下来同样一段规范写成 Markdown 比写成 JSON 的遵循率高出一大截。这不是玄学是因为训练数据里 Markdown 的占比远高于结构化配置格式模型对它的理解更自然。另一个取舍是技能粒度。粒度太粗一个技能包罗万象加载一次就吃掉大量上下文粒度太细技能之间互相引用维护成本飙升。我的经验是一个技能对应一类可独立验证的行为。比如如何写单元测试是一个技能如何跑测试是另一个技能测试失败后怎么排查又是另一个。它们可以组合使用但各自独立成立。2.3 和 Claude Code 的加载机制怎么配合Claude Code 本身有一套项目级配置的加载逻辑它会读取项目根目录下的约定文件。agent-skills的巧妙之处在于它不跟这套机制对抗而是寄生在它之上。你可以在项目的主说明文件里写一句本项目使用 agent-skills技能定义在.agent-skills/skills/下请按需加载然后 agent 就会在需要的时候去读对应的SKILL.md。这里有个关键点触发条件要写清楚。比如 testing 技能的触发条件可以写成当用户要求新增功能、修改逻辑、或提到测试时加载。这样 agent 不会在每次对话开头就把所有技能全读一遍而是在真正需要时才去读。这个懒加载的思路直接决定了你的上下文预算够不够用。我踩过的一个坑是一开始我把所有技能的触发条件都写成始终加载结果每次对话开头 agent 都要读七八个文件响应明显变慢而且真正相关的信息被稀释了。后来改成精准触发体验立刻不一样。所以设计阶段最重要的一件事就是想清楚每个技能到底在什么场景下才需要。3. 核心细节解析与实操要点3.1 SKILL.md 到底该写什么一个高质量的SKILL.md我总结下来应该包含五个部分适用场景、核心规则、操作步骤、验证方法、常见错误。这五块缺一不可尤其是后两块很多人会忽略。适用场景写在最前面用一两句话说明什么时候该用这个技能。比如 testing 技能的场景描述是当需要为新功能编写测试、或修改现有测试时使用。这句话的作用是给 agent 一个明确的开关信号。核心规则是技能的骨架用简短的条目列出必须遵守的约定。注意是必须遵守不是建议。比如所有新增函数必须有对应的单元测试测试文件放在tests/目录下命名规则为test_模块名.py。规则要具体到可以直接执行不能写代码要规范这种废话。操作步骤是给 agent 的执行指南。这里我建议用有序列表每一步都写清楚做什么、用什么命令、预期结果是什么。比如在tests/下创建test_模块名.py导入被测模块使用 pytest 风格编写测试函数运行pytest tests/test_模块名.py -v验证确认所有用例通过后再提交验证方法是很多人漏掉的部分但它恰恰是 test-driven-development 的精髓。没有验证方法的技能等于没有闭环。验证方法要写清楚怎么判断这个技能被正确执行了。对于 testing 技能验证方法就是所有测试用例通过且覆盖率不低于设定阈值。常见错误是经验沉淀的地方。把你实际踩过的坑写进去比如不要用assertEqual比较浮点数要用assertAlmostEqualmock 对象记得在测试结束后清理。这些细节模型不会自己知道但你写进去它就会遵守。3.2 技能之间的依赖与组合技能不是孤立的。testing 技能可能依赖 code-style 技能测试代码也要符合风格规范git-workflow 技能可能依赖 testing 技能提交前必须测试通过。这种依赖关系怎么处理我的做法是在 SKILL.md 里显式声明依赖但不自动加载。比如 testing 技能的头部写一句本技能假设 code-style 技能已加载。这样 agent 知道有这个前提但不会因为加载 testing 就强行把 code-style 也拉进来。为什么不自动加载因为自动加载会导致依赖链失控——A 依赖 BB 依赖 C最后加载一个技能带出一串上下文又爆了。组合使用的时候我通常会在config.yaml里定义几个技能组。比如开发模式加载 testing code-style git-workflow调试模式加载 debugging logging。这样切换场景的时候一条命令搞定不用手动一个个指定。提示技能组不要定义太多三到五个足够。定义太多你会记不住哪个组包含哪些技能反而增加心智负担。3.3 和 test-driven-development 的深度结合agent-skills和 test-driven-developmentTDD结合是我认为最有价值的用法。传统 TDD 的流程是先写测试再写实现最后重构。把这个流程固化成一个技能agent 就会严格按照这个顺序工作。具体怎么做我在 testing 技能里加了一个TDD 模式的章节明确规定当用户要求新增功能时agent 必须先写测试、运行测试确认失败、再写实现、再运行测试确认通过。这个顺序不能颠倒。实测下来agent 遵循这个流程后产出的代码质量明显更稳定因为它被迫先想清楚这个功能到底要做什么。这里有个细节值得说测试失败的信息要反馈给 agent。当 agent 写完测试运行失败时它需要看到失败信息才能继续。所以技能里要写清楚运行测试后把完整的失败输出作为下一步的输入。这一步如果断了TDD 流程就变成了形式主义。我还试过把重构单独抽成一个技能。当测试全绿之后agent 可以加载重构技能按照小步修改、每步测试的原则优化代码。这样整个开发流程就被拆成了几个可独立验证的阶段每个阶段都有明确的入口和出口。4. 实操过程与核心环节实现4.1 从零搭建一套 agent-skills假设你现在有一个 Python 项目想给它配一套agent-skills。完整流程如下。第一步创建目录结构。在项目根目录下执行mkdir -p .agent-skills/skills/{testing,code-style,git-workflow} touch .agent-skills/config.yaml第二步编写config.yaml。这个文件声明技能组和默认行为version: 1 default_group: development groups: development: - testing - code-style - git-workflow debug: - debugging - logging skills: testing: path: skills/testing/SKILL.md trigger: 新增功能、修改逻辑、提到测试时 code-style: path: skills/code-style/SKILL.md trigger: 编写或修改任何代码时 git-workflow: path: skills/git-workflow/SKILL.md trigger: 提交、分支、合并相关操作时第三步编写第一个技能testing/SKILL.md。内容大致如下# Testing Skill ## 适用场景 当需要为新功能编写测试、修改现有测试、或用户提到测试时使用。 ## 核心规则 - 所有新增函数必须有对应单元测试 - 测试文件放在 tests/ 目录命名 test_模块名.py - 使用 pytest 风格不用 unittest 的类继承写法 - 浮点数比较用 pytest.approx不用 ## 操作步骤 1. 在 tests/ 下创建或打开对应测试文件 2. 编写测试函数函数名以 test_ 开头 3. 运行 pytest tests/test_模块名.py -v 4. 确认全部通过后再进行下一步 ## 验证方法 - 所有测试用例通过 - 新增代码行覆盖率不低于 80% - 无跳过skip的测试用例 ## 常见错误 - 不要用 assertEqual 比较浮点数 - mock 对象在测试结束后要清理 - 测试之间不能有依赖每个测试独立运行第四步在主说明文件里加一句引导。在项目根目录的CLAUDE.md或类似文件里写本项目使用 agent-skills 管理开发规范。 技能定义在 .agent-skills/skills/ 下。 当涉及测试、代码风格、提交流程时请先读取对应的 SKILL.md。第五步验证加载。开一个新的 Claude Code 会话让它给某个函数加个测试观察它是否会主动去读 testing 技能。如果不会检查触发条件是否写得太模糊。4.2 参数选择与阈值设定技能里涉及数值的地方都要给出明确阈值不能含糊。我列几个常见的参数推荐值理由测试覆盖率阈值80%低于这个值说明测试不充分高于这个值边际收益递减单个 SKILL.md 行数50-150 行太短信息不足太长加载成本高技能组数量3-5 个超过 5 个记不住切换成本高触发条件关键词3-5 个太少容易漏触发太多容易误触发覆盖率阈值为什么定 80%这是业界比较通行的经验值。核心逻辑分支覆盖到边界情况覆盖到剩下的 getter/setter 之类的样板代码不覆盖也不影响质量。如果你追求 100%往往会为了覆盖率写一堆无意义的测试反而增加维护负担。单个 SKILL.md 的行数控制在 50 到 150 行之间是我反复调整后的结论。低于 50 行信息量不够agent 读完还是不知道怎么做高于 150 行加载成本上升而且说明这个技能该拆分了。4.3 和 VS Code、终端命令的配合Claude Code 在 VS Code 里以插件形式运行时agent-skills的加载逻辑是一样的因为插件本质上还是调用同一套核心。区别在于VS Code 环境下你可以更方便地查看 agent 读了哪些文件。我通常会在调试时打开输出面板观察 agent 的加载行为。终端命令方面技能里涉及的命令要写完整。比如不要写运行测试要写pytest tests/ -v --covsrc。完整命令的好处是 agent 可以直接执行不需要再猜。我试过写模糊命令结果 agent 经常自己发挥跑出一些我没预期的结果。注意技能里涉及的所有命令都要在你自己的环境里先跑通一遍。没跑通的命令写进去agent 执行失败后会产生混乱反而拖慢进度。5. 常见问题与排查技巧实录5.1 技能不生效怎么办这是最常见的问题。agent 明明应该加载某个技能但行为上完全没体现。排查思路按以下顺序来。先确认技能文件路径是否正确。config.yaml里写的path是相对于项目根目录的如果路径写错agent 根本找不到文件。我踩过一次坑把skills/testing/SKILL.md写成了skill/testing/SKILL.md少了个 s排查了半小时。再确认触发条件是否匹配。如果触发条件写的是提到测试时但你实际说的是帮我验证一下这个函数那可能就不触发。解决办法是把触发条件写得更宽泛一些或者直接在对话里明确说请加载 testing 技能。最后确认主说明文件里的引导语句是否存在。有些项目根目录下没有CLAUDE.md或者有但没写引导语句agent 就不知道agent-skills的存在。这一步最容易被忽略。5.2 技能之间冲突怎么处理两个技能给出矛盾指令时agent 会怎么选答案是不确定。所以你要主动避免冲突。我遇到过的典型冲突是code-style 技能要求函数不超过 20 行但某个具体功能的实现天然就需要 30 行。这时候 agent 会纠结。解决办法是在 code-style 技能里加一条例外规则当函数逻辑无法在 20 行内清晰表达时允许适当放宽但需在函数注释中说明原因。另一个冲突来源是优先级不明确。testing 技能说提交前必须测试通过git-workflow 技能说提交信息要符合规范如果两个都触发agent 可能先做这个忘了那个。我的做法是在config.yaml里给技能组内的技能排个序明确执行顺序。5.3 常见问题速查表问题现象可能原因解决方法技能完全不加载路径错误或主文件无引导检查路径补充引导语句技能加载了但不遵循规则写得太模糊改成具体可执行的条目加载后响应变慢技能太大或触发太频繁拆分技能收窄触发条件多个技能指令冲突优先级不明确在 config 里定义执行顺序命令执行失败命令未在本地验证先手动跑通再写入技能测试覆盖率不达标阈值设置不合理调整到 80% 左右5.4 几个独家避坑技巧第一个技巧技能要版本化。把.agent-skills/目录纳入 git 管理每次修改技能都提交。这样当 agent 行为发生变化时你可以通过git log追溯是哪个技能改动导致的。我吃过没版本化的亏改了一个技能后 agent 行为异常但想不起来改了什么只能全部回滚重来。第二个技巧新技能先小范围试。不要一上来就把技能组全启用先单独启用一个新技能观察几天确认稳定后再加入技能组。这样出问题的时候影响面小。第三个技巧定期清理僵尸技能。项目演进过程中有些技能会过时。比如早期项目用 unittest后来迁移到 pytest那 unittest 相关的技能就该删掉。留着不仅占上下文还可能误导 agent。第四个技巧给技能写反例。除了写应该怎么做还要写不应该怎么做。模型对反例的敏感度很高写了反例之后违规行为明显减少。比如 testing 技能里写不要用time.sleep等待异步结果要用awaitagent 就不会再犯这个错。6. 技能体系的扩展与长期维护6.1 从个人项目到团队协作个人用agent-skills和团队用复杂度完全不是一个量级。个人项目里技能怎么写你自己说了算团队项目里技能是多人共享的契约改一个字都可能影响别人的工作流。我的建议是团队技能要有 review 流程。任何对.agent-skills/的修改都要走 pull request至少一个人 review。review 的重点不是代码风格而是这条规则是否真的应该成为团队共识。我见过太多团队把个人偏好写进技能结果其他人用起来各种别扭。另一个建议是技能分层。团队级技能放在仓库根目录个人级技能放在本地配置里。团队级技能定义必须遵守的底线个人级技能定义我喜欢这样的偏好。这样既保证了一致性又保留了灵活性。6.2 技能和项目文档的关系有人会问我已经有项目文档了为什么还要写技能这两者的定位不一样。项目文档是给人看的技能是给 agent 看的。给人看的文档可以写得详细、有背景、有来龙去脉给 agent 看的技能要写得直接、可执行、无歧义。但这不意味着两者要重复维护。我的做法是技能里引用文档而不是复制文档。比如技能里写代码风格遵循docs/style-guide.md重点注意第 3 节的命名规范而不是把整个风格指南抄一遍。这样文档更新时技能不用改。6.3 后续可以怎么扩展agent-skills这套思路可以扩展到很多场景。比如把它和 CI 流程结合让 agent 在提交前自动跑一遍技能里定义的验证步骤。再比如把它和代码审查结合让 agent 按照技能里的规则自动 review 别人的 PR。我最近在试的一个方向是技能的自适应调整。根据 agent 实际执行的成功率动态调整技能的触发条件和规则强度。成功率低的规则说明写得太严或太模糊需要优化成功率高的规则可以保持。这个方向还在摸索但初步看是有价值的。最后分享一个我个人的体会agent-skills最大的价值不在于让 agent 更聪明而在于让 agent 更一致。聪明是模型本身的能力一致是你通过工程手段赋予的。一个行为一致的 agent比一个偶尔惊艳但经常跑偏的 agent在实际开发中靠谱得多。这套东西值得花时间打磨因为它是你和 agent 之间长期协作的基础设施。