当我们谈论 AI 编码 Agent 时，一个核心矛盾始终存在：Agent 能够快速生成代码，却默认跳过软件生命周期中那些「不在 diff 中体现」的工作 —— 编写规格说明、撰写测试、代码审查、提交可验证的证据。这些工作恰恰是资深工程师职业生涯中不断学习并刻意践行的内容，也是区分可靠软件交付与频繁故障团队的关键。Agent Skills 框架正是为了将这套资深工程师的思维框架编码为 Agent 可执行的工作流。
技能的本体论：工作流而非参考文档
在 Claude Code 与 Anthropic 的词汇体系中，「技能」（Skill）承载着精确的语义：技能是一个带有 frontmatter 的 Markdown 文件，当情境需要时被注入到 Agent 的上下文窗口中。它的定位介于系统提示片段与操作手册之间，但本质区别于传统的参考文档。一份两千字的测试最佳实践文档会被 Agent 浏览后产生看似合理的文本然后跳过实际测试执行；而一个具体的工作流 —— 先写失败的测试、运行并观察失败、编写最少代码使其通过、再次运行观察通过、最后重构 —— 则提供给 Agent 可执行的步骤和可验证的产出。
这种区分本身就是整个框架的核心洞察。过程优于文本，工作流优于参考，具备退出标准的步骤优于缺乏目标的论述。这解释了为何众多「AI 规则」代码库在实践中收效甚微：那些规则本质上都是论述而非可执行的工作流。技能的真正价值在于为 Agent 提供可行动的路径而非静态的知识。
技能编码的 SDLC 模型
仓库中二十项技能围绕六个软件生命周期阶段组织，辅以七个斜杠命令作为入口。Define（/spec）阶段决定实际构建的内容；Plan（/plan）将工作分解为可管理的块；Build（/build）以垂直切片方式实现功能；Verify（/test）证明功能正常工作；Review（/review）捕获遗漏的问题；Ship（/ship）将成果安全交付给用户。/code-simplify 则贯穿整个流程的底层。
这并非巧合，而是每一个正常运作的工程组织都在运行的相同生命周期，只是表述词汇不同。Google 称之为设计文档到评审到实现再到可读性评审到发布检查清单；Amazon 称之为逆向工作的备忘录和 bar raiser 机制。每个健康的团队都有某种版本的循环。AI 编码 Agent 的新问题在于默认跳过大多数阶段 —— 你请求一个功能，得到一个实现，而规格、计划、测试、评审和发布检查清单都不会自动发生。技能推动 Agent 穿越资深工程师强制自己经历的所有阶段，因为不经过这些阶段就交付代码正是生产事故的根源。一个复杂功能可能依次激活十一项技能；一个小 bug 修复可能仅使用三项。路由元技能（using-agent-skills）决定哪些技能适用于当前任务，工作流按实际范围而非假设范围伸缩。
五大支柱设计原则
框架中有五个设计决策支撑着整个系统，其余一切都由此衍生。
第一项原则「过程优于文本」已在前文充分展开。工作流对 Agent 可操作，论述则不可。这对人类团队同样适用 —— 如果团队手册有 200 页，人员在时间压力下无人阅读；如果是一小套带检查点的工作流，人们实际上会执行它们。
第二项原则「反合理化表格」是项目中最独特的设计决策，也是最值得其他团队借鉴的模式。每项技能包含一个表格，列出 Agent 或疲惫的工程师可能用来跳过工作流的常见借口，并附上书面的反驳。几个接近原文的例子包括：「这个任务太简单不需要规格说明」—— 验收标准仍然适用，五行可以，一行不行；「我稍后写测试」—— 稍后是承重词，没有「稍后」这回事，先写失败的测试；「测试通过了，发版」—— 通过测试是证据不是证明，你检查运行时行为了吗？你验证用户可见的行为了吗？有人读了 diff 吗？
这个设计生效的原因是大型语言模型擅长合理化。它们会产生看似合理的段落解释为什么这个特定任务不需要规格说明，或者为什么这个特定变更不需要评审就可以合并。反合理化表格是预先写好的反驳，针对 Agent 尚未说出的谎言。这个模式对人类团队同样有效。大多数工程衰退不是任何人选择做坏事，而是人们接受了看似合理的借口来跳过他们不想做的部分。一支写下自己反合理化清单的团队，这样的借口会更少。
第三项原则「验证不可妥协」意味着每项技能都以具体证据终止。测试通过。构建输出干净。运行时追踪显示预期行为。评审者批准。「看起来正确」永远不够。这与 Anthropic 的 harness 从失败中恢复、Cursor 的 planner/worker/judge 分离实际捕获 bug、任何长期运行的 Agent 可恢复的原理相同。Agent 是一个生成器，你需要独立的信号表明工作已完成。技能将这个信号烘焙到每个工作流中。
第四项原则「渐进式披露」要求不要在会话开始时将所有二十项技能加载到上下文中，而是根据阶段激活它们。一个小的元技能（using-agent-skills）充当路由器，决定当前任务适用哪项技能。这是 harness 工程教训在技能粒度上的应用。加载到上下文中的每个 token 都会在某处降低性能，所以只加载相关的，其余留在磁盘上。渐进式披露是如何将二十项技能的库装入 5K token 槽位而不污染上下文的答案。
第五项原则「范围约束」来自元技能中不可协商的规则：如果可以，我会把它钉在每个 Agent 上 ——「只触摸你被要求触摸的内容」。不要重构相邻系统。不要删除你不完全理解的代码。不要碰到一个 TODO 就决定重写整个文件。这听起来显而易见，直到你观察到一个 Agent 决定修复一个 bug 需要现代化三个无关文件。范围约束是决定 Agent 的 PR 是否可合并还是必须撤销的最大因素。它也是与 Google 代码评审规范映射最清晰的原则，评审者会阻止一个 PR 做超过一件事。
工程实践中的关键参数
将框架理念落地到工程实践需要关注几个可量化、可监控的维度。技能粒度方面，单个技能文件应控制在 400 到 800 词之间，包含明确的步骤序列、检查点和退出标准。反合理化表格建议每个技能维护 3 到 5 对「借口 - 反驳」组合，这些组合应定期根据团队实际遇到的拖延模式更新。上下文窗口管理上，路由元技能应在 500 词以内，单次激活的技能栈不超过 3 项，总 token 消耗控制在单次请求的 15% 到 20% 以内。验证阶段必须产生可存档的证据 —— 测试输出日志、构建产物校验和、运行时行为截图或评审者的明确批准标记，这些证据应作为任务关闭的前置条件。
技能的注册与路由机制采用 Markdown 加 frontmatter 的声明式格式，这意味着同一套技能定义可以在 Claude Code、Cursor（使用 .cursor/rules）、Gemini CLI、Codex、Aider、Windsurf、OpenCode 等多种支持系统提示的运行时中复用。技能的可移植性是这种设计模式相对于定制化提示工程的核心优势 —— 工作流写一次，运行时负责执行它。
从框架中提取可立即复用的实践，首先是反合理化作为团队惯例：写下团队告诉自己的谎言、「发布后修复测试」、「这个变更太小不需要设计文档」、「没关系，我们有监控」，为每个配上反驳，放进团队的 AGENTS.md 或工程维基，这会节省争论并捕捉下一个疲惫的周五下午的捷径。其次是任何内部写作都遵循过程优于文本的原则：如果发现自己在写一篇两千字标题为「我们如何处理 X」的文档，实际上写的是参考材料，将其转化为带检查点的工作流，文档会缩减到四百词而人们真正会执行它，这对入职指南和操作手册同样适用。第三是将验证作为硬性退出标准：使「产出证据」成为每项任务的退出步骤，对 Agent、工程师、自己都是如此。证据是证明工作完成的任何东西：一次通过的测试运行、截图、日志、评审批准。没有它，任务不算完成。「看起来正确」永远不关闭循环。第四是任何规则手册都采用渐进式披露：不要写 50 页手册，写一个小型路由器指向情况的对应小章节，这对 AGENTS.md、运行手册、事件应对剧本、任何人在时间压力下会阅读的内容都成立。
资料来源
本文核心内容来自 Addy Osmani 的博客文章《Agent Skills》（addyosmani.com/blog/agent-skills），该文详细阐述了技能框架的设计理念、五大原则及其与 Google 工程实践的关联。Agent Skills 仓库地址为 github.com/addyosmani/agent-skills，采用 MIT 许可证开源。