1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个项目名我的直觉是这不是一个普通工具而是一套给 AI 编码代理AI coding agents装技能包的规范或框架。为什么这么判断因为 skills 这个词在 AI 代理语境下指的从来不是模型本身的推理能力而是外部注入的、可复用的、结构化的操作知识——比如如何做测试驱动开发如何写一个规范的 commit如何排查一个内存泄漏。这些知识模型本身可能知道一点但不知道你团队的具体做法、具体命令、具体约束。所以agent-skills要解决的核心问题就浮出水面了AI 编码代理很聪明但它不知道你的项目规矩。你让它改一个函数它可能顺手把测试删了你让它加个功能它可能不写测试直接提交。这不是模型笨是你没告诉它在这个项目里什么叫做好。这个项目适合谁三类人最该关注已经在用 Claude Code、Cursor、Copilot 这类 AI 编码代理的开发者觉得能用但不够听话想让代理按自己的工程规范干活团队技术负责人想把团队的编码规范、测试要求、提交约定固化成代理能读懂的技能文件让每个成员用的代理行为一致对 AI 代理工作流感兴趣的技术爱好者想搞清楚skills CLI这类工具到底在抽象什么。关键词里出现的test-driven-development是个强信号——它暗示这套技能体系里TDD 是一个被重点封装的技能。也就是说agent-skills很可能提供了一种机制你把先写测试再写实现这个流程写成一个 skill代理在接到编码任务时会自动加载并遵循它。下面我会从为什么需要技能层技能文件长什么样怎么落地到 Claude Code 这类工具TDD 技能的具体拆解踩过的坑几个角度把这件事讲透。内容基于我对 AI 编码代理工作流的实际使用经验以及对 skills CLI 这类工具设计逻辑的合理推演具体命令和字段以你本地实际版本为准。2. 为什么裸奔的 AI 编码代理总是不听话2.1 代理的聪明和守规矩是两回事很多人对 AI 编码代理有个误解觉得模型越强写出来的代码就越符合预期。实际用下来你会发现模型能力和工程规范遵循度是两个独立维度。一个能写出精妙算法的模型照样可能在你明确说了不要改公共接口之后手贱去重构你的 API。根本原因在于代理的默认行为是**完成任务而不是按你的方式完成任务**。它的训练目标是让代码能跑、能通过测试、能解决当前问题。至于命名风格、目录结构、错误处理约定、提交信息格式这些软约束它只能靠上下文猜。上下文里没写它就按训练数据里最常见的做法来——而最常见往往不是你想要的。我踩过最典型的一个坑让代理给一个 Python 项目加日志。它直接import logging然后在每个函数里logging.info(...)。问题是这个项目早就统一用了structlog而且日志字段有严格的命名规范。代理不是不会用 structlog是它不知道这个项目用 structlog。你每次都得在 prompt 里重复一遍累不累2.2 把规范塞进 prompt 的三个致命问题有人会说那我每次把规范写进 prompt 不就行了我试过三个问题绕不过去第一token 成本。一份完整的团队编码规范少说两三千字每次对话都塞进去长会话里 token 消耗飞快而且模型对超长上下文中段的注意力会衰减——你写在中间的那条必须写测试它可能根本没看见。第二一致性差。今天你记得写用 pytest 不用 unittest明天换个同事忘了写代理行为就不一样。规范散落在每个人的 prompt 里等于没有规范。第三无法版本化。prompt 是临时的改了就没了。团队规范应该像代码一样进 Git能 review、能回滚、能追溯这条规矩什么时候加的、为什么加。agent-skills这类项目的价值就在这里把规范从临时 prompt变成版本化资产。技能文件进仓库代理按需加载团队共享同一套。2.3 技能层到底抽象了什么我理解agent-skills的抽象是这样的一个 skill 就是一段结构化的、带触发条件的、可被代理按需读取的操作知识。它至少包含三部分元信息这个技能叫什么、什么时候该用触发条件、适用哪些文件类型指令正文具体怎么做用自然语言写清楚步骤、约束、示例可选的辅助资源脚本、模板、检查清单。关键在按需加载。代理不是一上来就把所有技能读一遍而是根据当前任务判断我现在要写测试那我去加载 TDD 技能。这既省 token又让代理的注意力集中在当前相关的规范上。提示技能文件的设计哲学和系统提示词完全不同。系统提示词是永远生效的背景约束技能是特定场景下才激活的操作手册。混用这两者要么浪费 token要么规范失效。3. 一个 skill 文件到底该写什么3.1 从触发条件倒推内容结构写 skill 最容易犯的错是把它写成一篇编码规范文档。规范文档是给人读的skill 是给代理读的两者的组织逻辑不一样。人读文档是从头到尾代理读 skill 是匹配触发条件后精准取用。所以写 skill 的第一步不是写内容是写触发条件。你要回答代理在什么情况下应该加载这个技能比如 TDD 技能的触发条件可能是当任务涉及新增功能或修改业务逻辑时。触发条件写清楚了内容结构自然就出来了——你只需要写在这个场景下代理必须知道的那几件事。我一般按这个结构组织一个 skill--- name: test-driven-development description: 当需要新增功能或修改业务逻辑时使用强制先写测试 trigger: 新增功能、修改业务逻辑、修复 bug --- ## 核心原则 先写失败的测试再写实现最后重构。 ## 具体步骤 1. 阅读需求写出一个会失败的测试 2. 运行测试确认它确实失败且失败原因正确 3. 写最小实现让测试通过 4. 重构保持测试绿色 5. 重复直到需求完成 ## 硬性约束 - 禁止在没有测试的情况下修改业务逻辑 - 测试必须能在本地独立运行 - 每个测试只验证一个行为 ## 反例 不要这样先写实现再补测试。补出来的测试往往在验证实现做了什么而不是需求要求什么。注意最后那个反例部分。给代理写规范反例比正例更有用。因为代理的默认行为往往就是那个反例你明确点出来它才会刻意避开。3.2 指令要写成可执行动作而非原则口号代码要整洁这种话对代理毫无意义因为它无法把整洁翻译成具体动作。有效的指令必须是可执行、可验证的。对比一下无效指令有效指令写高质量的测试每个测试函数只包含一个 assert测试名用test_行为_预期格式保持代码风格一致遵循项目根目录.editorconfig缩进用 4 空格行宽 100注意错误处理所有外部调用必须包裹 try/except异常必须记录日志并重新抛出业务异常提交信息要规范提交信息格式type(scope): 描述type 限 feat/fix/refactor/test/docs右边这列的每一条代理都能直接执行而且你能验证它有没有做到。写 skill 的过程其实是在逼你把团队默契翻译成机器可执行的规则——这个过程本身就很有价值很多团队写完 skill 才发现原来大家对规范的理解根本不一致。3.3 技能之间的依赖和组合真实项目里一个任务往往需要多个技能协同。比如实现一个新 API 端点可能同时触发TDD 技能先写测试、API 设计技能路由命名规范、错误处理技能统一异常格式、文档技能自动更新 OpenAPI。agent-skills这类框架通常会提供技能组合机制——要么在 skill 里声明依赖要么由代理根据任务自动编排。我的经验是技能粒度要小组合要显式。一个 skill 只干一件事需要组合时在元信息里写清楚本技能通常与 X、Y 一起使用。粒度太大代理加载一堆无关内容组合不显式代理可能漏掉关键技能。注意技能不是越多越好。我见过一个团队写了 40 多个 skill结果代理每次任务都要在技能选择上花大量推理反而变慢变笨。控制在 10 个以内覆盖最高频的场景剩下的用项目级配置文件兜底。4. 把 skills 接进 Claude Code 的实际路径4.1 先搞清楚 Claude Code 的技能加载机制Claude Code 本身有一套项目级配置机制通常通过项目根目录的配置文件如CLAUDE.md或类似约定文件来注入项目上下文。agent-skills这类工具的价值是把散乱的配置升级成结构化的技能库并提供 CLI 来管理这些技能。实际接入时你要搞清楚两件事技能文件放在哪通常是项目内一个约定目录比如.agent-skills/或.claude/skills/具体以你用的版本为准代理怎么发现技能要么通过一个索引文件列出所有可用技能及其触发条件要么通过 CLI 生成的配置注入到代理的上下文里。我建议的做法是技能文件进 Git索引文件由 CLI 生成。这样技能内容可 review、可追溯索引文件不用手动维护避免加了技能忘了更新索引这种低级错误。4.2 skills CLI 的典型工作流虽然具体命令以你本地版本为准但这类 CLI 的工作流大同小异我按常见实践梳理一遍# 1. 初始化技能目录结构 skills init # 2. 创建一个新技能交互式或从模板 skills create test-driven-development # 3. 校验技能文件格式是否正确 skills validate # 4. 生成代理可读的索引/配置 skills build # 5. 列出当前所有技能及其触发条件 skills listskills validate这一步千万别跳过。技能文件里的元信息格式错了比如 YAML frontmatter 缩进不对代理可能静默地加载失败你还以为是代理不听话。每次改完技能先 validate 再 build这是我踩过坑之后养成的习惯。4.3 验证技能真的生效了技能写完不等于生效。怎么验证我的方法是设计一个陷阱任务故意给代理一个容易违反规范的场景看它会不会触发对应技能。比如验证 TDD 技能我会说给用户模块加一个根据邮箱查用户的方法。如果技能生效代理应该先写测试、跑测试看它失败、再写实现。如果它直接甩出一段实现代码说明技能没加载或者触发条件没匹配上。排查顺序skills list确认技能在列表里检查触发条件的关键词是否覆盖了当前任务描述看代理的上下文里有没有技能内容有些工具支持查看注入的上下文实在不行把触发条件放宽一点或者直接在任务描述里点名请使用 TDD 技能。提示触发条件匹配是语义匹配还是关键词匹配不同工具实现不同。如果是关键词匹配你的触发词要覆盖同义表达比如新增功能和添加特性都得写上。5. TDD 技能一个值得拆透的样板5.1 为什么 TDD 最适合做成技能在agent-skills的关键词里test-driven-development被单独拎出来我认为很有道理。TDD 是代理默认行为和工程最佳实践冲突最激烈的场景。代理的默认行为是尽快给出能跑的代码而 TDD 要求先写一个失败的测试。这两个目标在代理的推理里是矛盾的——它倾向于跳过写失败测试这一步因为那看起来像没完成任务。把 TDD 做成技能本质是用显式指令覆盖代理的默认倾向。而且 TDD 的流程高度结构化红-绿-重构非常适合写成可执行的步骤。5.2 红绿重构在技能文件里的落地红-绿-重构三步每一步在技能文件里都要写清楚代理必须做什么和代理必须确认什么红阶段代理写出测试后必须实际运行测试并确认它失败。这一步最容易被跳过。代理经常写完测试就假设它会失败直接进入实现。但测试可能因为语法错误、导入错误而失败这种失败是假失败不能算数。技能文件里要明确运行测试确认失败原因是功能未实现而非语法或导入错误。绿阶段写最小实现让测试通过。注意最小两个字。代理倾向于一次写一个完整实现但 TDD 要求你只写刚好让当前测试通过的量。技能文件里要写只实现让当前测试通过所需的最少代码不要提前实现后续需求。重构阶段测试保持绿色的前提下改进代码。这一步代理也容易忽略因为它觉得测试过了就完事了。技能文件里要写每次绿灯后检查是否有重复代码、过长函数、不清晰命名有则重构重构后重跑测试。5.3 让代理先失败的指令技巧让代理接受先写失败测试这件事光靠命令不够得给它一个认知框架。我在技能文件里会加一段为什么先写测试的价值不在于测试本身而在于它强迫你在写实现前明确这个功能到底应该做什么。测试是你对需求的第一次精确表达。如果跳过这一步你会在实现里做一堆需求没要求的假设这些假设就是 bug 的来源。代理读到这段为什么遵循度会明显提升。给代理讲道理比单纯下命令有效——这也是写 skill 和写传统配置文件的区别。6. 技能库维护中那些没人告诉你的坑6.1 技能膨胀从 5 个到 40 个的失控技能库最容易失控。一开始大家很克制就写几个核心技能。然后每个人遇到问题就加一个 skill半年后 40 多个代理每次任务都要在技能选择上纠结。更糟的是技能之间开始冲突——A 技能说用 tabsB 技能说用 spaces代理无所适从。我的控制策略定期合并每月 review 一次技能库把触发条件重叠的技能合并设上限核心技能不超过 10 个超出的必须合并或降级为项目配置冲突检测skills validate之外我还会写个脚本检查技能间的硬性约束是否矛盾。6.2 触发条件写太窄或太宽触发条件太窄技能永远不激活等于没写太宽技能到处激活干扰其他任务。这个度很难一次调准。我的经验是从窄开始逐步放宽。先写一个很具体的触发条件观察代理在哪些本该触发的场景没触发再针对性放宽。反过来从宽到窄很难因为你不知道哪些激活是误激活。判断误激活的方法看代理的输出里有没有出现这个技能不该管的内容。比如 TDD 技能在只改文档的任务里被激活了那就是触发条件太宽。6.3 技能和项目配置的边界有些规范适合做成技能按需加载有些适合放进项目级配置永远生效。边界在哪我的划分标准永远不能违反的放项目配置特定场景才适用的放技能。比如禁止提交密钥是永远不能违反的放项目配置新增功能要先写测试是特定场景的放技能。搞混了要么项目配置臃肿要么关键约束在非触发场景下失效。6.4 团队协作技能文件的 review 流程技能文件是团队资产必须走 review。但 review 什么不是 review 文笔是 review可执行性。我要求每个技能 PR 必须包含一个陷阱任务的测试记录证明技能确实改变了代理行为触发条件的正例和反例各一个如果修改了已有技能说明为什么旧版本不够好。这套流程跑下来技能库的质量会稳定很多。没有测试的技能和没有测试的代码一样不可信。7. 我实际用下来的一些体会技能库这东西最大的价值不是让代理更听话而是逼团队把隐性知识显性化。写 skill 的过程中你会发现很多我们一直这么做但没人说清楚为什么的规矩。把这些写下来本身就是一次团队对齐。另一个体会是别指望一次写对。我第一版 TDD 技能写了 200 多字代理遵循度一般。后来加了反例、加了为什么、把步骤拆得更细遵循度才上来。技能文件是要迭代的把它当代码一样对待——有版本、有测试、有 review。最后说个反直觉的技能不是越多越好也不是越详细越好。一个 50 字的精准指令胜过 500 字的泛泛而谈。代理的注意力是稀缺资源你写的每一个字都在争夺它的注意力。写 skill 的最高境界是用最少的字让代理做出最正确的行为。