Skill 驱动的 Agent 行为编排

学习目标

读完本章后，你将能够：

理解 Skill 文档如何替代传统硬编码规则来控制 Agent 行为
设计 Skill 的三层优先级体系（用户指令 > Skill > 默认系统提示）
实现 SessionStart hook 的 bootstrap 注入与运行时 Skill 工具调用的双层触发
构建反合理化表格与 Red Flags 列表，防止 Agent 自行绕过纪律
使用 Hard-Gate 机制强制门控关键工作流步骤

核心概念

Skill 作为”行为代码”

传统 AI Agent 的行为由系统提示中的软规则引导，Agent 可以自由选择是否遵循。Skill 系统将纪律编码为结构化的 Markdown 文档，通过两个机制强制执行：

自动发现：SessionStart hook 在每个会话启动时注入 bootstrap，告诉 Agent 有哪些 Skill 可用以及何时必须调用它们
强制调用：当任务与 Skill description 匹配时，Agent 必须先调用 Skill 工具获取完整指令，才能执行任何操作

Skill 不是建议，而是行为契约。description 字段定义何时触发，正文定义如何执行。

三层优先级体系

用户指令始终最高。Skill 覆盖默认系统提示但不覆盖用户指令。这个设计确保用户始终掌控，同时 Skill 能纠正 Agent 的默认行为偏差。

双层触发机制

第一层：SessionStart bootstrap

会话启动时，hook 脚本检测当前平台（Claude Code / Cursor / Copilot CLI 等），将 using-superpowers Skill 的完整内容注入为系统上下文。这确保 Agent 在第一条用户消息前就知道 Skill 系统的存在。

第二层：运行时 Skill 工具

Agent 在收到用户消息后，根据 description 判断是否有适用的 Skill。“1% 规则”规定：即使只有 1% 的可能性认为某个 Skill 适用，也必须调用它。这防止 Agent 以”这很简单”为由跳过纪律。

反合理化设计

Agent 善于找到绕过规则的理由。反合理化设计预识别这些推理模式并显式封锁：

Agent 的想法	封锁对策
”这太简单了不需要设计"	"简单项目最容易被未检验的假设浪费最多工作"
"我记得这个 Skill 怎么用"	"Skill 会演进，读当前版本"
"先探索代码再检查 Skill"	"Skill 告诉你如何探索，先检查"
"这个 Skill 太重了"	"简单事情变复杂，使用它”

关键原则：不在 Skill 中列出所有可能的例外。使用”没有例外”和”违反字母就是违反精神”等基础原则，切断整类”我遵循的是精神而非字面”的推理。

Hard-Gate 门控

Hard-Gate 是 Skill 中显式声明的强制门控，Agent 不得绕过：

<HARD-GATE>
在呈现设计并获得用户批准之前，不得调用任何实现 Skill、编写任何代码、搭建任何项目或采取任何实现行动。这适用于每一个项目，无论其表面简单程度如何。
</HARD-GATE>

Gate 用 XML 标签标记以增强视觉显著性。门控失败意味着整个 Skill 流程失败。

设计权衡

为什么用文档而非代码

优势：

平台无关：Markdown 在任何 AI 编程 Agent 中都可读
人类可审计：任何开发者都能理解和修改 Skill 内容
版本控制友好：diff 清晰，code review 直接
热更新：修改 Markdown 即可改变 Agent 行为，无需重新构建

代价：

依赖 Agent 的理解力，不如硬编码可靠
需要反复测试和迭代来堵住 Agent 的绕过路径
无法用类型系统验证正确性

为什么 description 不总结工作流

一个经过验证的教训：当 Skill description 总结工作流时（如”每个任务分派子代理 + 代码审查”），Agent 会遵循 description 而非阅读 Skill 正文。因为 description 是 Agent 首先读取的内容，它提供了一个”捷径”。

对策：description 只写触发条件（when to use），不写执行流程（how to do）。例如：

# 错误：总结工作流
description: 执行计划时每个任务分派子代理，进行规格和代码质量两阶段审查

# 正确：只写触发条件
description: 在当前会话中执行独立任务的实现计划时使用

为什么需要反合理化表格

测试表明，即使有清晰的规则，Agent 在压力下（时间压力、沉没成本、疲劳）仍会找到绕过的理由。反合理化表格的价值在于：

预识别：不等 Agent 发现漏洞，提前封锁常见推理路径
模式匹配：Agent 可以在自己产生某个想法时快速识别”这是 Red Flag”
去个性化：将”我在找借口”转化为”这个借口在表格中被列为无效”

陷阱与对策

陷阱	表现	对策
Skill 过大	单个 SKILL.md 超过 500 词，Agent 在每次会话中浪费 token	分离参考文件，SKILL.md 保持精简，用交叉引用替代重复
触发描述模糊	”处理异步问题时使用” — 什么是”异步问题”？	用具体症状描述：“测试有时通过有时失败、涉及 setTimeout 的竞态条件时使用”
Skill 间冲突	两个 Skill 对同一情况给出矛盾指令	建立明确的优先级体系，用户指令 > Skill > 默认提示
过度工程化	Skill 试图预见所有边缘情况	只写基线测试中发现的失败模式，不写假设场景

补充：Agent Skills 的全技能反合理化模式库

来源：Addy Osmani / agent-skills v0.6.1，23 个 skills/*/SKILL.md 中的 Common Rationalizations 表，commit 6ce0298

agent-skills 项目将反合理化表标准化为每个 Skill 的必选章节，并积累了跨 23 个技能的反合理化模式库。

跨技能的共性反合理化模式

模式	出现频率	典型表现
”太简单不需要 X”	15+ 技能	”这个很简单，不需要规格”、“这是单行修改，不需要审查"
"稍后再做 X”	10+ 技能	”我会稍后补测试”、“以后再加 feature flag"
"一次全做更快”	8+ 技能	”一次性写完再测试更快”、“全部实现完再审查"
"我知道 API，不需要查”	5+ 技能	”我对这个 API 有信心”、“不需要查文档"
"X 会拖慢我们”	5+ 技能	”规格会拖慢速度”、“启动审查器太贵"
"以后反正会变”	3+ 技能	”需求反正会变化”、“我们以后再加分页”

反驳论证的设计原则

agent-skills 的反合理化表遵循以下原则：

具体反驳，不是抽象说教：
- ❌ “测试很重要”
- ✅ “Bug 会复合。Slice 1 的 Bug 让 Slice 2-5 都错。每片都测试。”
量化代价，不是模糊警告：
- ❌ “这会花费更多时间”
- ✅ “15 分钟的规格防止数小时的重做。15 分钟内的瀑布胜过 15 小时的调试。”
承认有效边界，不是绝对化：
- ❌ “永远不要跳过规格”
- ✅ “简单任务不需要长规格，但仍需要验收标准。两行规格也可以。”
区分跳过和静默跳过：
- “跳过没问题；静默跳过不行。”
- 这是一个反复出现的模式——允许用户做出决策，但要求决策可见。

“1% 规则”

agent-skills 的 using-agent-skills 技能中定义了一条元规则：即使只有 1% 的可能性某个技能适用，也必须检查它。这条规则防止了最常见的反合理化——“这个情况看起来不像需要 X 技能”——通过设置极低的触发阈值来覆盖边缘情况。

与 Hard-Gate 的配合

反合理化表是认知层面的防御（改变 Agent 的推理），Hard-Gate 是流程层面的防御（通过 XML 标签强制停止点）。两者缺一不可：

只有反合理化表：Agent 可能找到绕过表格的理由
只有 Hard-Gate：Agent 在 Gate 之间仍然可能跳过步骤

验证的非协商性

每个 Skill 以 Verification 检查清单结束。“看起来对”永远不够——必须有证据。这是 Agent Skills 区别于普通提示工程的核心设计：

每个验证检查框都需要证据（测试输出、构建结果、截图、运行时数据）。没有证据的检查框不算通过。

参考来源

Agent Skills Specification — Skill 文档格式规范（name / description 字段要求）
Claude Code Hooks 文档 — SessionStart hook 的配置与输出格式
Cialdini, R. (2021). Influence — 权威、承诺一致性等说服力原则在反合理化设计中的应用
Meincke, et al. (2025). 关于 AI Agent 在压力下合规性的实证研究

版本信息

📅 2026-05-22