深度剖析 Addy Osmani 的 Agent Skills：如何写出让 AI 真正遵守的操作规程

油画

@addyosmani
89.4K 🌟 agent-skills 开源项目中的核心规范文档，明确定义了 Skills 的结构与写作标准。是一套面向 AI 行为工程的提示设计方法论，用最小的上下文开销，换取最可靠的行为改变。

Skill Anatomy
https://github.com/addyosmani/agent-skills/blob/HEAD/docs/skill-anatomy.md

# 结构规范：最小必需 + 按需扩展

skills/skill-name/
  SKILL.md      # 唯一必需文件
  scripts/      # 可选：可执行脚本
  references/   # 可选：按需加载的参考文档

关键设计意图：反对仪式感。文档明确禁止为了"看起来整齐"而创建空的 scripts/ 目录——结构必须服务于实际需求，而非镜像其他技能。

# Skill 规范核心设计要点

1. Frontmatter：发现机制的全部赌注
description 是唯一常驻系统提示的部分，因此规则极其严格：
· 必须同时回答 what（做什么）和 when（何时触发）；
· 不得包含流程摘要——否则 Agent 可能直接按摘要行动，而不去读完整技能。这是一条很深刻的教训：摘要会"短路"正文。

2. 正文各段落的行为学功能
· Overview / When to Use：帮 Agent 做激活判断（含反向排除条件）
· Core Process：必须具体可执行——"运行 npm test 并确认通过"合格，"确保测试没问题"不合格
· Common Rationalizations：全文最有特色的设计：预演 Agent 的偷懒借口（"这个很简单不用写规格""测试回头再补"），并逐条给出反驳
· Red Flags：可观察的违规信号，供审查和自监控
· Verification：退出标准清单，每项都必须有证据支撑（测试输出、构建结果、截图）

Common Rationalizations 值得单独强调：它承认了一个现实——LLM 会像人一样为跳过步骤找理由。与其假设 Agent 会严格执行，不如预先封堵它的"合理化路径"。这是把对人类心理（如纪律清单、检查表文化）的理解迁移到了 Agent 工程。

3. 脚本约定：上下文经济学
脚本要求 JSON 输出到 stdout、状态信息到 stderr、set -e 快速失败。背后的核心原则：
执行脚本不消耗上下文，只有输出消耗；而内联代码块每次加载都要付费。
这条原则同样解释了"SKILL.md 控制在 500 行以内""引用层级不超过一层"等规则。

# 共享引用的工程权衡

跨技能共用的清单（测试、安全、性能等）放在仓库根部的 references/，而非按 Agent Skills 规范塞进各技能目录。文档罕见地坦承了这是一个有意识的取舍：
· 复制到每个技能 → 必然漂移；
· 指定某个技能"拥有"它 → 同样漂移；
· 根部单副本 → 保证唯一事实源，但牺牲了单技能独立安装时的可移植性（已知缺陷，issue #361 跟踪中）。

这种"明确记录 tradeoff 并挂账跟踪"的写法，本身是成熟工程文档的范例。

# 六条写作原则（全文精华）

1. 流程优于知识——Skill 是工作流，不是百科；
2. 具体优于笼统——可执行命令胜过正确废话；
3. 证据优于假设——每个验收项都要可验证；
4. 反合理化——每个容易被跳过的步骤，都要预置反驳；
5. 渐进披露——主文件是入口，细节按需加载；
6. Token 意识——每个段落都要证明自身价值，删掉不影响行为就删掉。