1. 从 agent-skills 说起为什么 AI 编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我正被一堆重复的 AI 编码任务折磨得够呛。那段时间我同时在维护三个项目每个项目都需要 AI 编码代理帮我处理代码审查、单元测试生成、重构建议这些事。问题是每次开新会话我都得把同样的规则、同样的流程、同样的检查清单重新说一遍。这就像你雇了一个很聪明的新员工但他每天早上来上班都会失忆你得从头给他做入职培训。agent-skills解决的就是这个问题。它本质上是一套面向 AI 编码代理的技能定义框架通过结构化的技能文件让代理在不同项目、不同会话之间保持一致的做事方式。你可以把它理解成给 AI 代理准备的“标准作业程序库”——每个技能文件就是一份 SOP告诉代理在特定场景下应该遵循什么流程、检查哪些要点、输出什么格式的结果。这个项目适合谁如果你正在用 Claude Code、Cursor、Windsurf 这类 AI 编码工具并且希望它们按照你团队的规范来干活而不是每次随机发挥那agent-skills这套思路就非常值得研究。哪怕你只是刚接触 AI 编码代理理解技能体系的设计逻辑也能帮你更好地驾驭这些工具而不是被它们牵着鼻子走。我花了大概两周时间深入研究这套框架的设计理念并在自己的项目里做了落地实践。下面把我踩过的坑、总结的经验、以及可以直接抄作业的配置方案完整分享出来。2. agent-skills 的核心设计思路拆解2.1 为什么是“技能”而不是“提示词”很多人第一次接触 AI 编码代理时习惯把所有的指令塞进一个巨大的系统提示词里。我早期也这么干过结果就是提示词越写越长最后超过了两千行维护起来极其痛苦。更糟糕的是当提示词太长时模型对其中某些部分的注意力会下降导致一些关键规则被忽略。agent-skills的核心洞察在于把“技能”从“提示词”中解耦出来。每个技能是一个独立的 Markdown 文件包含特定场景下的完整操作指南。代理在执行任务时根据当前上下文动态加载相关技能而不是一次性把所有规则都塞进上下文窗口。这个设计的好处很明显。第一上下文利用率高。代理只在需要的时候加载需要的技能不会浪费 token 在无关规则上。第二可维护性强。修改某个技能不影响其他技能团队可以分工维护不同的技能文件。第三可组合性好。多个技能可以叠加使用比如“代码审查”技能和“安全扫描”技能可以同时生效。我实测下来把原来两千行的系统提示词拆成十五个技能文件后代理执行任务的准确率有明显提升。特别是在处理复杂任务时因为上下文更聚焦模型不容易“分心”。2.2 技能文件的目录结构与命名规范agent-skills对技能文件的组织方式有明确约定。通常来说技能存放在项目根目录的.agent/skills/目录下每个技能一个子目录目录名就是技能标识符。子目录里至少包含一个SKILL.md文件这是技能的主入口。为什么用目录而不是单文件因为一个完整的技能往往需要附带辅助资源比如代码模板、检查清单、示例文件等。用目录结构可以把这些资源组织在一起代理加载技能时可以一并读取。命名规范上我建议用 kebab-case比如test-driven-development、code-review、security-audit。这样做的好处是跨平台兼容性好不会因为大小写问题在 Windows 和 Linux 之间出现路径解析差异。另外技能名要尽量具体避免用utils、helpers这种模糊命名否则代理很难判断什么时候该加载这个技能。2.3 技能描述文件的元数据设计每个SKILL.md文件的开头部分通常包含 YAML 格式的元数据用来告诉代理这个技能是干什么的、什么时候该用、依赖哪些其他技能。我见过很多项目忽略元数据设计结果代理根本不知道什么时候该加载哪个技能技能体系形同虚设。一个典型的元数据块包含这几个字段name是技能的唯一标识description用一两句话说明技能用途triggers列出触发条件比如用户提到“写测试”或“review 代码”dependencies声明依赖的其他技能。这些字段看起来简单但设计好坏直接影响代理的调度准确率。我踩过的一个坑是triggers写得太宽泛。比如有个技能叫code-quality触发条件写了“代码相关”结果代理几乎每个任务都会加载它反而干扰了其他更具体技能的生效。后来我把触发条件改得更精确比如“用户要求检查代码风格”或“任务涉及重构”调度准确率就上来了。3. 核心技能模块的详细拆解与实操要点3.1 test-driven-development 技能让代理先写测试再写实现test-driven-development是agent-skills体系里最核心的技能之一也是我实践下来收益最大的一个。这个技能的核心逻辑是强制代理遵循“红-绿-重构”的循环先写一个会失败的测试然后写最少的代码让测试通过最后在测试保护下重构。为什么要把 TDD 做成一个独立技能因为 AI 编码代理天然倾向于直接写实现代码然后补一些看起来像测试的东西。但那种“先写实现再补测试”的方式测试往往是在验证实现的行为而不是验证需求的行为。TDD 反过来先让测试定义期望行为实现代码必须去满足测试这样代码质量更有保障。这个技能文件里需要包含的关键内容有测试框架的检测逻辑比如自动识别项目用的是 Jest、Pytest 还是 JUnit、测试文件命名约定、断言风格要求、以及每个循环步骤的具体操作指南。我建议在技能里明确写出“禁止在测试通过之前编写实现代码”这样的硬性规则否则代理很容易偷懒。实操中有一个细节值得注意代理写第一个失败测试时要确保测试失败的原因是“功能未实现”而不是“语法错误”或“导入路径错误”。我见过代理写了一个测试运行后报错说模块找不到然后它就去创建了一个空模块测试还是失败但它误以为这是预期的失败。所以技能文件里要强调失败测试的报错信息必须与缺失的功能直接相关。3.2 code-review 技能把审查清单变成可执行规则code-review技能解决的是代理审查代码时“凭感觉”的问题。没有这个技能的时候你让代理 review 代码它可能会说“这段代码看起来不错但建议添加更多注释”这种不痛不痒的话。有了技能约束后代理会按照你定义的清单逐项检查。我在技能文件里定义的审查维度包括命名是否表意清晰、函数是否单一职责、错误处理是否完备、边界条件是否覆盖、是否有重复代码、日志是否恰当、安全漏洞检查等。每个维度下面再细分具体检查点比如错误处理维度下包含“是否捕获了所有可能的异常”、“异常信息是否包含足够上下文”、“是否避免了吞异常”等。这里有个经验审查清单不要写太长。我一开始写了五十多个检查点结果代理执行时明显敷衍很多检查点只是走个过场。后来精简到二十个核心检查点每个都要求代理给出具体的代码行引用和修改建议审查质量反而提升了。技能文件里可以加一条规则如果某个检查点不适用代理需要明确说明原因而不是跳过。3.3 技能之间的依赖与组合关系agent-skills体系里技能不是孤立的。test-driven-development和code-review可以组合使用代理先按 TDD 流程写代码写完后再按 code-review 清单自查。这种组合通过元数据里的dependencies字段来声明。但组合不是越多越好。我试过让代理同时加载五六个技能结果它的行为变得很僵硬每个步骤都要对照多个技能文件效率反而下降。后来我总结出一个原则单次任务加载的技能不超过三个。如果确实需要更多技能就分阶段执行每个阶段加载两到三个。技能组合还有一个坑是规则冲突。比如一个技能要求“函数不超过二十行”另一个技能要求“所有逻辑必须内联以便审查”这两个规则就会打架。解决办法是在技能设计阶段就做好协调或者在元数据里声明优先级。我通常会在项目级的配置里定义一个skill-priority列表明确冲突时以哪个技能为准。4. 在 Claude Code 中落地 agent-skills 的完整实操4.1 环境准备与 Claude Code 安装要点要在 Claude Code 里使用agent-skills首先得把基础环境搭好。Claude Code 的安装方式根据操作系统有所不同。在 macOS 上通常通过包管理器安装在 Ubuntu 上可以用官方的安装脚本。安装完成后运行claude --version确认版本然后运行claude进入交互模式完成初始配置。这里有一个常见问题Claude Code 在某些地区可能无法直接使用官方文档里会有支持地区的说明。如果你遇到网络相关的限制需要先确认自己所在地区是否在支持范围内。另外Claude Code 的注册账号和未注册账号在使用权限上有差异注册账号可以保存会话历史和使用更多模型未注册账号则有一些功能限制。安装完成后我建议先在空项目里跑一个简单任务确认代理能正常读写文件、执行终端命令。Claude Code 的一个强大之处是它可以直接执行终端命令这意味着代理可以自己运行测试、安装依赖、查看 git 状态。但这个能力也带来风险所以技能文件里要明确哪些命令需要用户确认后才能执行。4.2 项目目录初始化与技能文件放置在项目根目录创建.agent/skills/目录然后为每个技能创建子目录。以test-driven-development为例目录结构是这样的.agent/ skills/ test-driven-development/ SKILL.md templates/ test-template.js checklists/ tdd-checklist.md code-review/ SKILL.md checklists/ review-checklist.mdSKILL.md是必须的其他辅助文件按需添加。我建议在项目根目录再放一个.agent/config.yaml用来配置技能加载策略、优先级、以及全局规则。这个配置文件让代理在启动时就知道该去哪里找技能、按什么顺序加载。4.3 编写第一个 SKILL.md 的完整示例下面是我在实际项目中使用的test-driven-development技能的SKILL.md核心内容。这个文件经过多次迭代目前效果比较稳定--- name: test-driven-development description: 强制代理遵循红-绿-重构循环先写失败测试再写实现 triggers: - 用户要求实现新功能 - 用户要求修复 bug - 用户提到写测试或TDD dependencies: - code-review --- ## 执行流程 1. 分析需求确定要测试的行为 2. 编写一个失败的测试运行并确认失败原因正确 3. 编写最少的实现代码让测试通过 4. 运行全部测试确认没有破坏其他功能 5. 在测试保护下重构代码 6. 重复上述步骤直到功能完成 ## 硬性规则 - 禁止在测试通过之前编写实现代码 - 每个测试只验证一个行为 - 测试名称必须描述期望行为而不是实现细节 - 失败测试的报错必须与缺失功能直接相关这个文件看起来简单但每一条规则都是踩坑后总结出来的。比如“测试名称必须描述期望行为”这条是因为代理早期总写test_function_1这种名字后来 review 时根本看不懂测试在验证什么。4.4 验证技能是否生效的检查方法技能文件写好后怎么确认代理真的在用我的做法是设计一个验证任务让代理实现一个简单功能然后观察它的行为。如果它先写测试再写实现说明 TDD 技能生效了。如果它直接写实现说明技能没被加载或者触发条件没匹配上。排查技能不生效的思路先检查.agent/skills/目录路径是否正确再检查SKILL.md的元数据格式是否有语法错误然后检查触发条件是否覆盖了当前任务。我遇到过一次问题是 YAML 里的triggers用了中文标点导致解析失败代理完全没加载技能。这种细节问题很隐蔽建议用 YAML 校验工具先检查一遍。5. 常见问题与排查技巧实录5.1 技能加载失败的五种典型原因在实际使用中技能加载失败是最常见的问题。我整理了一个排查表覆盖了大部分场景问题现象可能原因排查方法代理完全不按技能执行技能目录路径错误确认.agent/skills/在项目根目录部分任务生效部分不生效触发条件覆盖不全检查triggers是否包含当前任务关键词技能文件解析报错YAML 元数据格式错误用 YAML 校验工具检查语法技能之间规则冲突优先级未定义在 config 中设置skill-priority代理忽略硬性规则规则表述不够明确用“禁止”“必须”等强约束词这个表是我在三个项目里反复踩坑后总结的基本上覆盖了百分之九十以上的技能加载问题。遇到问题时按表排查通常几分钟就能定位。5.2 代理不遵守技能规则时的处理策略有时候技能加载成功了但代理执行时还是偷懒。比如 TDD 技能要求先写测试代理却直接写实现然后补一个测试。这种情况我遇到过好几次后来发现原因是技能文件里的规则不够“硬”。处理策略有几个层次。第一在技能文件里用更强的约束词比如把“建议先写测试”改成“禁止在测试通过前编写实现代码”。第二在项目配置里加一个验证步骤代理完成任务后自动检查是否遵循了 TDD 流程。第三如果代理反复不遵守可以在会话开始时明确提醒它加载并遵循相关技能。我个人的经验是规则表述越具体、越可验证代理遵守的概率越高。“写高质量代码”这种模糊要求基本没用“函数不超过二十行且每个函数只做一件事”这种可量化规则才有效。5.3 多技能组合时的冲突解决多技能组合时规则冲突是难免的。比如code-review技能要求“所有公共函数必须有文档注释”而另一个技能要求“代码要简洁避免冗余”。代理可能会困惑文档注释算不算冗余解决冲突的核心是定义优先级。我在.agent/config.yaml里这样配置skill-priority: - security-audit - test-driven-development - code-review - code-style优先级高的技能规则覆盖优先级低的。这样当security-audit要求“所有输入必须验证”和code-style要求“代码简洁”冲突时安全规则优先。这个配置让代理的行为更可预测减少了“随机发挥”的情况。5.4 技能体系的维护与迭代建议技能体系不是写完就一劳永逸的。随着项目演进技能文件也需要迭代。我建议每个月做一次技能回顾看看哪些技能经常被触发、哪些从未生效、哪些规则导致了误报。维护时有一个原则技能文件要像代码一样对待。每次修改都记录变更原因重要修改走 review 流程。我见过团队把技能文件当草稿纸随手改来改去结果代理行为越来越不稳定。后来我们规定技能文件修改必须提交 PR并且附上修改前后的行为对比情况才好转。另外技能文件里可以加一个“变更日志”区块记录每次修改的时间、原因、影响范围。这样新成员加入时能快速理解技能体系的演进过程不用从头摸索。6. 技能体系带来的实际收益与个人体会落地agent-skills这套体系三个月后我最大的感受是AI 编码代理从“需要时刻盯着”变成了“可以放心交办”。以前让代理写代码我得反复检查它有没有遵循规范、有没有漏掉测试、有没有引入安全问题。现在这些检查都固化在技能文件里代理执行任务时会自动对照我只需要在最后做一次验收。具体收益上代码审查环节的时间消耗下降了大概百分之四十因为代理自查已经过滤掉了大部分低级问题。测试覆盖率从原来的百分之六十左右提升到百分之八十五以上因为 TDD 技能强制先写测试。跨项目的一致性也明显改善同一个代理在不同项目里的行为风格基本统一减少了上下文切换的成本。当然也有代价。前期设计技能文件需要投入不少时间特别是调试触发条件和解决规则冲突。但这是一次性投入后续维护成本很低。我的建议是先从一两个核心技能开始比如 TDD 和 code-review跑通流程后再逐步扩展。不要一上来就设计十几个技能那样很容易因为规则冲突和维护负担而放弃。最后分享一个小技巧技能文件里的示例代码要尽量贴近项目实际使用的技术栈。我早期用了一个通用的 JavaScript 示例结果代理在 Python 项目里也照搬那个示例的风格闹了不少笑话。后来我把示例改成从项目里摘录的真实代码片段代理的输出风格就自然多了。 AI编码代理技能体系实战：agent-skills从设计到落地
1. 从 agent-skills 说起为什么 AI 编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我正被一堆重复的 AI 编码任务折磨得够呛。那段时间我同时在维护三个项目每个项目都需要 AI 编码代理帮我处理代码审查、单元测试生成、重构建议这些事。问题是每次开新会话我都得把同样的规则、同样的流程、同样的检查清单重新说一遍。这就像你雇了一个很聪明的新员工但他每天早上来上班都会失忆你得从头给他做入职培训。agent-skills解决的就是这个问题。它本质上是一套面向 AI 编码代理的技能定义框架通过结构化的技能文件让代理在不同项目、不同会话之间保持一致的做事方式。你可以把它理解成给 AI 代理准备的“标准作业程序库”——每个技能文件就是一份 SOP告诉代理在特定场景下应该遵循什么流程、检查哪些要点、输出什么格式的结果。这个项目适合谁如果你正在用 Claude Code、Cursor、Windsurf 这类 AI 编码工具并且希望它们按照你团队的规范来干活而不是每次随机发挥那agent-skills这套思路就非常值得研究。哪怕你只是刚接触 AI 编码代理理解技能体系的设计逻辑也能帮你更好地驾驭这些工具而不是被它们牵着鼻子走。我花了大概两周时间深入研究这套框架的设计理念并在自己的项目里做了落地实践。下面把我踩过的坑、总结的经验、以及可以直接抄作业的配置方案完整分享出来。2. agent-skills 的核心设计思路拆解2.1 为什么是“技能”而不是“提示词”很多人第一次接触 AI 编码代理时习惯把所有的指令塞进一个巨大的系统提示词里。我早期也这么干过结果就是提示词越写越长最后超过了两千行维护起来极其痛苦。更糟糕的是当提示词太长时模型对其中某些部分的注意力会下降导致一些关键规则被忽略。agent-skills的核心洞察在于把“技能”从“提示词”中解耦出来。每个技能是一个独立的 Markdown 文件包含特定场景下的完整操作指南。代理在执行任务时根据当前上下文动态加载相关技能而不是一次性把所有规则都塞进上下文窗口。这个设计的好处很明显。第一上下文利用率高。代理只在需要的时候加载需要的技能不会浪费 token 在无关规则上。第二可维护性强。修改某个技能不影响其他技能团队可以分工维护不同的技能文件。第三可组合性好。多个技能可以叠加使用比如“代码审查”技能和“安全扫描”技能可以同时生效。我实测下来把原来两千行的系统提示词拆成十五个技能文件后代理执行任务的准确率有明显提升。特别是在处理复杂任务时因为上下文更聚焦模型不容易“分心”。2.2 技能文件的目录结构与命名规范agent-skills对技能文件的组织方式有明确约定。通常来说技能存放在项目根目录的.agent/skills/目录下每个技能一个子目录目录名就是技能标识符。子目录里至少包含一个SKILL.md文件这是技能的主入口。为什么用目录而不是单文件因为一个完整的技能往往需要附带辅助资源比如代码模板、检查清单、示例文件等。用目录结构可以把这些资源组织在一起代理加载技能时可以一并读取。命名规范上我建议用 kebab-case比如test-driven-development、code-review、security-audit。这样做的好处是跨平台兼容性好不会因为大小写问题在 Windows 和 Linux 之间出现路径解析差异。另外技能名要尽量具体避免用utils、helpers这种模糊命名否则代理很难判断什么时候该加载这个技能。2.3 技能描述文件的元数据设计每个SKILL.md文件的开头部分通常包含 YAML 格式的元数据用来告诉代理这个技能是干什么的、什么时候该用、依赖哪些其他技能。我见过很多项目忽略元数据设计结果代理根本不知道什么时候该加载哪个技能技能体系形同虚设。一个典型的元数据块包含这几个字段name是技能的唯一标识description用一两句话说明技能用途triggers列出触发条件比如用户提到“写测试”或“review 代码”dependencies声明依赖的其他技能。这些字段看起来简单但设计好坏直接影响代理的调度准确率。我踩过的一个坑是triggers写得太宽泛。比如有个技能叫code-quality触发条件写了“代码相关”结果代理几乎每个任务都会加载它反而干扰了其他更具体技能的生效。后来我把触发条件改得更精确比如“用户要求检查代码风格”或“任务涉及重构”调度准确率就上来了。3. 核心技能模块的详细拆解与实操要点3.1 test-driven-development 技能让代理先写测试再写实现test-driven-development是agent-skills体系里最核心的技能之一也是我实践下来收益最大的一个。这个技能的核心逻辑是强制代理遵循“红-绿-重构”的循环先写一个会失败的测试然后写最少的代码让测试通过最后在测试保护下重构。为什么要把 TDD 做成一个独立技能因为 AI 编码代理天然倾向于直接写实现代码然后补一些看起来像测试的东西。但那种“先写实现再补测试”的方式测试往往是在验证实现的行为而不是验证需求的行为。TDD 反过来先让测试定义期望行为实现代码必须去满足测试这样代码质量更有保障。这个技能文件里需要包含的关键内容有测试框架的检测逻辑比如自动识别项目用的是 Jest、Pytest 还是 JUnit、测试文件命名约定、断言风格要求、以及每个循环步骤的具体操作指南。我建议在技能里明确写出“禁止在测试通过之前编写实现代码”这样的硬性规则否则代理很容易偷懒。实操中有一个细节值得注意代理写第一个失败测试时要确保测试失败的原因是“功能未实现”而不是“语法错误”或“导入路径错误”。我见过代理写了一个测试运行后报错说模块找不到然后它就去创建了一个空模块测试还是失败但它误以为这是预期的失败。所以技能文件里要强调失败测试的报错信息必须与缺失的功能直接相关。3.2 code-review 技能把审查清单变成可执行规则code-review技能解决的是代理审查代码时“凭感觉”的问题。没有这个技能的时候你让代理 review 代码它可能会说“这段代码看起来不错但建议添加更多注释”这种不痛不痒的话。有了技能约束后代理会按照你定义的清单逐项检查。我在技能文件里定义的审查维度包括命名是否表意清晰、函数是否单一职责、错误处理是否完备、边界条件是否覆盖、是否有重复代码、日志是否恰当、安全漏洞检查等。每个维度下面再细分具体检查点比如错误处理维度下包含“是否捕获了所有可能的异常”、“异常信息是否包含足够上下文”、“是否避免了吞异常”等。这里有个经验审查清单不要写太长。我一开始写了五十多个检查点结果代理执行时明显敷衍很多检查点只是走个过场。后来精简到二十个核心检查点每个都要求代理给出具体的代码行引用和修改建议审查质量反而提升了。技能文件里可以加一条规则如果某个检查点不适用代理需要明确说明原因而不是跳过。3.3 技能之间的依赖与组合关系agent-skills体系里技能不是孤立的。test-driven-development和code-review可以组合使用代理先按 TDD 流程写代码写完后再按 code-review 清单自查。这种组合通过元数据里的dependencies字段来声明。但组合不是越多越好。我试过让代理同时加载五六个技能结果它的行为变得很僵硬每个步骤都要对照多个技能文件效率反而下降。后来我总结出一个原则单次任务加载的技能不超过三个。如果确实需要更多技能就分阶段执行每个阶段加载两到三个。技能组合还有一个坑是规则冲突。比如一个技能要求“函数不超过二十行”另一个技能要求“所有逻辑必须内联以便审查”这两个规则就会打架。解决办法是在技能设计阶段就做好协调或者在元数据里声明优先级。我通常会在项目级的配置里定义一个skill-priority列表明确冲突时以哪个技能为准。4. 在 Claude Code 中落地 agent-skills 的完整实操4.1 环境准备与 Claude Code 安装要点要在 Claude Code 里使用agent-skills首先得把基础环境搭好。Claude Code 的安装方式根据操作系统有所不同。在 macOS 上通常通过包管理器安装在 Ubuntu 上可以用官方的安装脚本。安装完成后运行claude --version确认版本然后运行claude进入交互模式完成初始配置。这里有一个常见问题Claude Code 在某些地区可能无法直接使用官方文档里会有支持地区的说明。如果你遇到网络相关的限制需要先确认自己所在地区是否在支持范围内。另外Claude Code 的注册账号和未注册账号在使用权限上有差异注册账号可以保存会话历史和使用更多模型未注册账号则有一些功能限制。安装完成后我建议先在空项目里跑一个简单任务确认代理能正常读写文件、执行终端命令。Claude Code 的一个强大之处是它可以直接执行终端命令这意味着代理可以自己运行测试、安装依赖、查看 git 状态。但这个能力也带来风险所以技能文件里要明确哪些命令需要用户确认后才能执行。4.2 项目目录初始化与技能文件放置在项目根目录创建.agent/skills/目录然后为每个技能创建子目录。以test-driven-development为例目录结构是这样的.agent/ skills/ test-driven-development/ SKILL.md templates/ test-template.js checklists/ tdd-checklist.md code-review/ SKILL.md checklists/ review-checklist.mdSKILL.md是必须的其他辅助文件按需添加。我建议在项目根目录再放一个.agent/config.yaml用来配置技能加载策略、优先级、以及全局规则。这个配置文件让代理在启动时就知道该去哪里找技能、按什么顺序加载。4.3 编写第一个 SKILL.md 的完整示例下面是我在实际项目中使用的test-driven-development技能的SKILL.md核心内容。这个文件经过多次迭代目前效果比较稳定--- name: test-driven-development description: 强制代理遵循红-绿-重构循环先写失败测试再写实现 triggers: - 用户要求实现新功能 - 用户要求修复 bug - 用户提到写测试或TDD dependencies: - code-review --- ## 执行流程 1. 分析需求确定要测试的行为 2. 编写一个失败的测试运行并确认失败原因正确 3. 编写最少的实现代码让测试通过 4. 运行全部测试确认没有破坏其他功能 5. 在测试保护下重构代码 6. 重复上述步骤直到功能完成 ## 硬性规则 - 禁止在测试通过之前编写实现代码 - 每个测试只验证一个行为 - 测试名称必须描述期望行为而不是实现细节 - 失败测试的报错必须与缺失功能直接相关这个文件看起来简单但每一条规则都是踩坑后总结出来的。比如“测试名称必须描述期望行为”这条是因为代理早期总写test_function_1这种名字后来 review 时根本看不懂测试在验证什么。4.4 验证技能是否生效的检查方法技能文件写好后怎么确认代理真的在用我的做法是设计一个验证任务让代理实现一个简单功能然后观察它的行为。如果它先写测试再写实现说明 TDD 技能生效了。如果它直接写实现说明技能没被加载或者触发条件没匹配上。排查技能不生效的思路先检查.agent/skills/目录路径是否正确再检查SKILL.md的元数据格式是否有语法错误然后检查触发条件是否覆盖了当前任务。我遇到过一次问题是 YAML 里的triggers用了中文标点导致解析失败代理完全没加载技能。这种细节问题很隐蔽建议用 YAML 校验工具先检查一遍。5. 常见问题与排查技巧实录5.1 技能加载失败的五种典型原因在实际使用中技能加载失败是最常见的问题。我整理了一个排查表覆盖了大部分场景问题现象可能原因排查方法代理完全不按技能执行技能目录路径错误确认.agent/skills/在项目根目录部分任务生效部分不生效触发条件覆盖不全检查triggers是否包含当前任务关键词技能文件解析报错YAML 元数据格式错误用 YAML 校验工具检查语法技能之间规则冲突优先级未定义在 config 中设置skill-priority代理忽略硬性规则规则表述不够明确用“禁止”“必须”等强约束词这个表是我在三个项目里反复踩坑后总结的基本上覆盖了百分之九十以上的技能加载问题。遇到问题时按表排查通常几分钟就能定位。5.2 代理不遵守技能规则时的处理策略有时候技能加载成功了但代理执行时还是偷懒。比如 TDD 技能要求先写测试代理却直接写实现然后补一个测试。这种情况我遇到过好几次后来发现原因是技能文件里的规则不够“硬”。处理策略有几个层次。第一在技能文件里用更强的约束词比如把“建议先写测试”改成“禁止在测试通过前编写实现代码”。第二在项目配置里加一个验证步骤代理完成任务后自动检查是否遵循了 TDD 流程。第三如果代理反复不遵守可以在会话开始时明确提醒它加载并遵循相关技能。我个人的经验是规则表述越具体、越可验证代理遵守的概率越高。“写高质量代码”这种模糊要求基本没用“函数不超过二十行且每个函数只做一件事”这种可量化规则才有效。5.3 多技能组合时的冲突解决多技能组合时规则冲突是难免的。比如code-review技能要求“所有公共函数必须有文档注释”而另一个技能要求“代码要简洁避免冗余”。代理可能会困惑文档注释算不算冗余解决冲突的核心是定义优先级。我在.agent/config.yaml里这样配置skill-priority: - security-audit - test-driven-development - code-review - code-style优先级高的技能规则覆盖优先级低的。这样当security-audit要求“所有输入必须验证”和code-style要求“代码简洁”冲突时安全规则优先。这个配置让代理的行为更可预测减少了“随机发挥”的情况。5.4 技能体系的维护与迭代建议技能体系不是写完就一劳永逸的。随着项目演进技能文件也需要迭代。我建议每个月做一次技能回顾看看哪些技能经常被触发、哪些从未生效、哪些规则导致了误报。维护时有一个原则技能文件要像代码一样对待。每次修改都记录变更原因重要修改走 review 流程。我见过团队把技能文件当草稿纸随手改来改去结果代理行为越来越不稳定。后来我们规定技能文件修改必须提交 PR并且附上修改前后的行为对比情况才好转。另外技能文件里可以加一个“变更日志”区块记录每次修改的时间、原因、影响范围。这样新成员加入时能快速理解技能体系的演进过程不用从头摸索。6. 技能体系带来的实际收益与个人体会落地agent-skills这套体系三个月后我最大的感受是AI 编码代理从“需要时刻盯着”变成了“可以放心交办”。以前让代理写代码我得反复检查它有没有遵循规范、有没有漏掉测试、有没有引入安全问题。现在这些检查都固化在技能文件里代理执行任务时会自动对照我只需要在最后做一次验收。具体收益上代码审查环节的时间消耗下降了大概百分之四十因为代理自查已经过滤掉了大部分低级问题。测试覆盖率从原来的百分之六十左右提升到百分之八十五以上因为 TDD 技能强制先写测试。跨项目的一致性也明显改善同一个代理在不同项目里的行为风格基本统一减少了上下文切换的成本。当然也有代价。前期设计技能文件需要投入不少时间特别是调试触发条件和解决规则冲突。但这是一次性投入后续维护成本很低。我的建议是先从一两个核心技能开始比如 TDD 和 code-review跑通流程后再逐步扩展。不要一上来就设计十几个技能那样很容易因为规则冲突和维护负担而放弃。最后分享一个小技巧技能文件里的示例代码要尽量贴近项目实际使用的技术栈。我早期用了一个通用的 JavaScript 示例结果代理在 Python 项目里也照搬那个示例的风格闹了不少笑话。后来我把示例改成从项目里摘录的真实代码片段代理的输出风格就自然多了。