智能体技能：让AI编码智能体遵循优秀工程实践

以下文章最初发表于Addy Osmani的博客，经作者许可在此转载。

任何AI编码智能体的默认行为都是采取通往“完成”的最短路径。要求一个功能，它就编写该功能。它不会询问你是否有一个规范，不会在实现之前编写测试，不会考虑更改是否跨越信任边界，也不会检查PR在审查者眼中会是什么样子。它产生代码，宣布胜利，然后继续前进。

这是每位高级工程师整个职业生涯都在学习避免的相同失败模式。任何任务的高级版本都包括不出现在差异中的工作：揭示假设、编写规范、将工作分解为可审查的块、选择无聊的设计、留下结果正确的证据、调整更改的大小以便人类可以实际审查。这些步骤正是区分能够大规模发布可靠软件的工程师与那些推送会出问题的代码的人的大部分因素。

智能体跳过这些步骤的原因与任何初级工程师相同。它们是不可见的。奖励信号指向“任务完成”，而不是“任务完成并且设计文档存在”。因此，我们必须重新加上高级工程师的脚手架。

Agent Skills是我对这种脚手架的尝试。它刚刚突破了27,000颗星，显然我不是唯一想要它的人。这篇文章是README没有完全涵盖的部分：每个设计选择存在的原因，它们如何映射到标准SDLC和谷歌已发布的工程实践，以及即使你从未安装单个技能，也应该从该项目中借鉴什么。

技能究竟是什么

“技能”这个词在Claude Code/Anthropic的词汇表中承担了大量工作，需要精确理解。技能是一个带有前置元数据的Markdown文件，当情况需要时会被注入到智能体的上下文中。它介于系统提示片段和运行手册之间。

技能不是参考文档。它不是“你应该知道的关于测试的一切”。它是一个工作流：智能体遵循的一系列步骤，带有产生证据的检查点，并以定义的退出标准结束。

这个区别就是整个游戏的关键。如果你将一篇2000字的关于测试最佳实践的文章放入智能体的上下文，智能体阅读它，生成看似合理的文本，然后跳过实际测试。如果你将一个工作流放在那里（先编写失败的测试，运行它，看到它失败，编写最少代码通过，看到它通过，重构），智能体就有事情可做，而你也有事情可验证。

流程重于散文。工作流重于参考。带有退出标准的步骤重于没有它们的文章。这一个区别将有用的技能与漂亮的Markdown文件区分开来。它也解释了为什么如此多的“AI规则”仓库在实践中最终无所作为。规则就是文章。

技能编码的SDLC

仓库中的20个技能组织在六个生命周期阶段周围，上面有七个斜杠命令。定义（/spec）是你决定实际构建什么的地方。计划（/plan）分解工作。构建（/build）用垂直切片实现它。验证（/test）证明它有效。审查（/review）捕获遗漏的东西。发布（/ship）安全地将其交付给用户。/code-simplify贯穿整个过程的基础。

这不是巧合。这是每个正常运作的工程组织运行的相同SDLC，只是词汇不同。谷歌称之为设计文档→审查→实现→可读性审查→启动清单。亚马逊称之为反向工作备忘录和提升门槛者。每个健康的团队都有这个循环的某种版本。

AI编码智能体的新问题是，大多数智能体默认跳过了这些阶段中的大多数。你要求一个功能，你得到一个实现，而规范、计划、测试、审查和启动清单都没有发生。技能推动智能体经历高级工程师强迫自己经历的相同阶段，因为没有它们就发布代码是产生事故的方式。

一个复杂功能可能依次激活11个技能。一个小错误修复可能使用三个。路由器（using-agent-skills）决定哪些适用。关键是工作流根据实际范围缩放，而不是根据假设的范围。

起作用的五个原则

项目中的五个设计决策是承重墙。系统的其余部分跟随它们。

**1. 流程重于散文**

已经涵盖。工作流是智能体可操作的；文章则不是。对人类团队也是如此。如果你的团队手册有200页，在时间压力下没人会读。如果它是一小组带有检查点的工作流，人们实际运行它们。

**2. 反合理化表格**

这是项目中最独特的设计决策，也是我最希望其他团队借鉴的。

每个技能包含一个常见借口的表格，智能体（或疲惫的工程师）可能用这些借口来跳过工作流，并配以书面的反驳。接近原文的一些例子：

• “这个任务太简单，不需要规范。” → 验收标准仍然适用。五行就可以了。零行不行。
• “我稍后写测试。” → “稍后”是承重词。没有稍后。先编写失败的测试。
• “测试通过了，发布吧。” → 通过的测试是证据，不是证明。你检查了运行时吗？你验证了用户可见的行为吗？人类阅读了差异吗？

这样做的原因是LLM非常擅长合理化。它们会生成一段看似合理的段落，解释为什么这个特定任务不需要规范，或者为什么这个特定更改无需审查就可以合并。反合理化表格是对智能体尚未说出的谎言的预写反驳。

这个模式对人类团队同样有效。大多数工程衰减不是有人选择做坏工作，而是人们接受看似合理的理由来跳过他们不想做的部分。一个写下其反合理化的团队是一个拥有更少合理化的团队。

**3. 验证不可协商**

每个技能终止于具体证据。测试通过。构建输出干净。运行时跟踪显示预期行为。审查者签字。“看起来正确”永远不够。

这是使Anthropic的harness从失败中恢复、使Cursor的planner/worker/judge分裂实际捕获错误、使任何长时间运行的智能体可恢复的相同原则。智能体是生成器。你需要一个独立的信号表明工作已完成。技能将那个信号烘焙到每个工作流中。

**4. 渐进式披露**

不要在会话开始时将所有20个技能加载到上下文中。根据阶段激活它们。一个小型元技能（using-agent-skills）充当路由器，决定哪个技能适用于当前任务。

这是应用于技能粒度的harness工程课。加载到上下文中的每个令牌都会在某个地方降低性能，所以你加载相关的内容，将其他内容留在磁盘上。渐进式披露是你如何将20个技能的库放入5K令牌的槽中而不污染井。

**5. 范围纪律**

元技能编码了一个不可协商的要求，如果可能我会将其钉在每个智能体上：“只修改你被要求修改的内容。”不要重构相邻系统。不要删除你不完全理解的代码。不要因为碰到TODO就决定重写文件。

这听起来显而易见，直到你看到智能体决定修复一个错误需要现代化三个不相关的文件。范围纪律是决定智能体的PR是可合并还是必须撤销的最大单一因素。它也是最干净地映射到谷歌代码审查规范的原则，因为审查者会阻止执行多个操作的PR。

谷歌DNA

这些技能充满了来自《谷歌的软件工程》和谷歌公开工程文化的实践。这是刻意的。使谷歌规模软件工作的大部分内容都是文档化和公开的，而正是智能体最可能跳过的部分。

部分技能编码的实践映射：

• Hyrum定律在api-and-interface-design中。API的每个可观察行为最终都会被某人依赖，所以设计时要考虑到这一点。
• 测试金字塔（~80/15/5）和Beyoncé规则在test-driven-development中。“如果你喜欢它，你应该为它写个测试。”基础设施更改不会捕获错误；测试才会。
• 测试中的DAMP over DRY。谷歌的测试哲学明确表示测试代码应该读起来像规范，即使以一些重复为代价。过度抽象的测试是已知的反模式。
• 约100行的PR大小，在code-review-and-quality中使用Critical/Nit/Optional/FYI严重级别标签。直接来自谷歌的代码审查规范。大的PR不会被审查；它们会被橡皮图章式批准。
• Chesterton's栅栏在code-simplification中。不要删除你不理解为什么存在的东西。
• 主干开发和原子提交在git-workflow-and-versioning中。
• 左移和功能标志在ci-cd-and-automation中。尽早捕获问题，将部署与发布解耦。
• 代码即负债在deprecation-and-migration中。你保留的每一行都需要永远维护，所以偏好更小的表面。

这些都不是新想法。关键是它们都不是智能体的默认行为。前沿模型在训练数据中读过“Hyrum定律”这个短语，但它在凌晨3点设计你的API时并不会应用Hyrum定律。技能就是确保它应用的方式。

实际使用方法

三种模式，按承诺程度递增。

模式1：通过市场安装。如果你使用Claude Code：

/plugin marketplace add addyosmani/agent-skills /plugin install agent-skills@addy-agent-skills

你将获得斜杠命令（/spec, /plan, /build, /test, /review, /ship, /code-simplify），智能体根据上下文自动激活相关技能。这是我推荐大多数人开始的路径。

模式2：将Markdown放入你选择的工具中。这些技能是带有前置元数据的纯Markdown。Cursor用户将它们放在.cursor/rules/中。Gemini CLI有自己的安装路径。Codex、Aider、Windsurf、OpenCode以及任何接受系统提示的工具都可以读取它们。工具不重要，底层的工作流才是关键。

模式3：作为规范阅读。即使你从未安装任何东西，这些技能也是关于AI智能体良好工程实践的文档化描述。阅读code-review-and-quality.md，将五轴框架应用到团队的审查流程中。阅读test-driven-development.md，用它来解决与初级工程师关于“是否需要先编写测试”的下一次争论。阅读元技能，将五个不可协商的要求偷用到你自己的AGENTS.md中。

这是我真的会开始的模式。选择最接近你当前痛点的四或五个技能。决定要强制执行哪些工作流。然后安装运行时，或自己编写一个来执行。

即使不安装也要借鉴的模式

项目中一些模式，无论你是否使用AI编码智能体，我都建议借鉴：

将反合理化作为团队实践。写下你的团队对自己说的谎言。“我们会在发布后修复测试。”“这个变更太小，不需要设计文档。”“没关系，我们有监控。”为每个谎言配上反驳。把它放在你的AGENTS.md或工程维基中。它将为你节省争论，并抓住下一个疲倦的周五下午的捷径。

内部编写的任何内容都采用流程重于散文。如果你发现自己正在写一篇2000字的名为“我们如何做X”的文档，你写的是参考材料。将其转换为带有检查点的工作流。文档会缩至400字，人们实际上会运行它。这一点同样适用于入职指南和运行手册，以及智能体技能。

将验证作为硬性退出标准。使“产生证据”成为每个任务的退出步骤。对于智能体、工程师、你自己。证据是任何证明工作已完成的东西：一个绿色的测试运行、一个屏幕截图、一个审查者的批准。如果不产生证据，任务就没有完成。

这些模式正是Agent Skills项目所提供的，即使你从未安装它。