Skill 结构九要素：从「触发」到「输出」的完整骨架
本条目是「Skill Engineering」的第 4 部分，对应学习清单条目 4.2.1。
一、核心观点
一个能打的 Skill 不是长 Prompt，而是覆盖「触发 → 执行 → 输出 → 兜底」的九要素模块。 九要素：适用场景、不适用场景、输入要求、操作步骤、工具使用、输出格式、质量标准、失败处理、安全边界。
盖房子不能只画「客厅长什么样」，还得标承重墙、逃生通道、水电接口。Skill 也一样——光写「操作步骤」只是装修图，九要素才是完整的建筑结构图：哪里该触发、哪里绝对别碰、出事了怎么退。
二、定义 / 原理 / 实践 / 示例 / 优劣势
2.1 九要素全景
flowchart LR A[适用场景] --> B[不适用场景] B --> C[输入要求] C --> D[操作步骤] D --> E[工具使用] E --> F[输出格式] F --> G[质量标准] G --> H[失败处理] H --> I[安全边界]
| 要素 | 回答的问题 | 一句话作用 |
|---|---|---|
| 适用场景 | 什么时候自动激活 | 触发条件 |
| 不适用场景 | 什么时候别激活 | 防误触发 |
| 输入要求 | 期望收到什么 | 格式/内容契约 |
| 操作步骤 | 核心怎么走 | 执行流程 |
| 工具使用 | 依赖哪些工具/API | 能力清单 |
| 输出格式 | 产出长什么样 | 结果规范 |
| 质量标准 | 什么算「做好」 | 验收标准 |
| 失败处理 | 踩坑了怎么办 | 恢复策略 |
| 安全边界 | 什么禁止/需人确认 | 护栏 |
2.2 原理：为什么是「九」而不是「三」
前三个（适用/不适用/输入）解决「该不该做、拿什么做」；中间三个（步骤/工具/输出）解决「怎么做、产出啥」；后三个（质量/失败/安全）解决「做好没、出事咋办、别越界」。缺任何一段，Skill 在真实环境里都会露怯。
2.3 实践：每个要素怎么写（节选）
## 适用场景
- 用户要求 review diff；改了 src/ 下 .py 文件
## 不适用场景
- 不对测试文件做风格审查；不审查未提交临时文件
## 失败处理
- 空 diff：提示先 git add；工具未装：降级纯文本 review
## 安全边界
- 禁止任何修改命令；破坏性操作必须人确认
2.4 示例
完整九要素 SKILL.md 模板见 写第一个 SKILL 的第五章。其中失败处理与安全边界是新手最易漏的两块，也是 Gotchas 优先 强调的高价值内容。
2.5 优劣势
-
✅ 覆盖全流程，Agent 知道「该/不该/怎么/产出啥/出事咋办」；可评审、可迭代
-
❌ 一次写全九要素有成本；初期可先写核心 5 个，逐步补失败/安全
三、最新研究与企业数据（2025–2026）
-
Skill 的解剖结构官方定义：Anthropic 文档将 Skill 内容分为三类——指令（instructions）、代码（code）、资源（resources），分别在 Level 2 / Level 3 加载（docs.anthropic.com）。九要素中的「操作步骤/工具/输出」对应指令层，「脚本」对应代码层，「references」对应资源层。
-
好 Skill 的官方特征：聚焦单一可重复任务、清晰指令、明确何时用（support.anthropic.com）——这正是九要素中「适用/不适用场景 + 操作步骤」要落地的点。
四、学习资源
五、相关链接
-
系列内：对比工具Skill系统 · Gotchas优先 · 写第一个SKILL
-
系列清单：Agent 方法论与产品思维学习路线图
六、核心要点
-
🎯 九要素 = 适用 / 不适用 / 输入 / 步骤 / 工具 / 输出 / 质量 / 失败 / 安全。
-
💡 分三段记：该不该做 → 怎么做 → 做好没/出事咋办。
-
⚠️ 新手最爱漏「不适用场景」和「安全边界」，这俩恰恰是防翻车的护栏。
参考来源（一手链接 · 可溯源深挖）
-
Anthropic Agent Skills 文档（指令/代码/资源三层内容）：docs.anthropic.com/en/docs/agents-and-tools/agent-skills
-
Anthropic《How to create custom skills》（好 Skill 特征）：support.anthropic.com/en/articles/12512198-creating-custom-skills
速记卡（面试闪卡）
Q1：一句话讲清「Skill 结构九要素：从「触发」到「输出」的完整骨架」到底是什么？
A：好 Skill 不是长 Prompt，而是覆盖「触发→执行→输出→兜底」的九要素模块：场景、步骤、工具、输出、质量、失败、安全全管到。
Q2：核心观点：Skill 是完整建筑结构图 —— 怎么理解？ —— 怎么理解？
A：一个能打的 Skill 不是长 Prompt，而是覆盖「触发→执行→输出→兜底」的九要素模块。生活类比：光写”操作步骤”像只画客厅长啥样，九要素才是完整建筑图——哪里该触发（门）、哪里绝对别碰（承重墙）、出事了怎么退（逃生通道）、水电接口（工具）在哪。缺一块，真实环境里就露怯。英文术语：Skill、trigger（触发）、guardrail（护栏）。
Q3：九要素全景：分三段记 —— 怎么理解？ —— 怎么理解？
A：九要素：适用场景、不适用场景、输入要求、操作步骤、工具使用、输出格式、质量标准、失败处理、安全边界。生活类比：前三个（适用/不适用/输入）答”该不该做、拿啥做”；中间三个（步骤/工具/输出）答”怎么做、产出啥”；后三个（质量/失败/安全）答”做好没、出事咋办、别越界”。像菜谱分”何时做/怎么做/翻车咋救”三段。英文术语：input contract（输入契约）、output format（输出格式）。
Q4：为什么是九不是三 —— 怎么理解？ —— 怎么理解？
A：前中后三段缺任何一段，Skill 在真实环境都会露怯。生活类比：菜谱只写主料不写火候和禁忌，你真做就翻车；Skill 只写步骤不写失败处理，遇到空 diff、工具没装就傻眼。九要素让 Agent 知道”该/不该/怎么/产出啥/出事咋办”，且可评审、可迭代。英文术语：failure handling（失败处理）、safety boundary（安全边界）。
Q5：实践与新手易漏项 —— 怎么理解？ —— 怎么理解？
A：实践中失败处理（空 diff 提示先 git add、工具未装降级纯文本 review）和安全边界（禁止修改命令、破坏性操作必须人确认）是新手最爱漏的两块，也恰恰是防翻车的护栏。生活类比：新手只顾把功能写爽，忘了装刹车和警示牌。初期可先写核心 5 个要素，逐步补失败/安全。英文术语：degradation（降级）、human confirmation（人工确认）。
Q6：核心速记主线有哪些？
-
九要素：适用/不适用/输入/步骤/工具/输出/质量/失败/安全
-
三段记：该不该做 → 怎么做 → 做好没/出事咋办
-
新手易漏：不适用场景 + 安全边界，恰是护栏
-
实践：初期先写核心 5 个，逐步补失败/安全
口诀
A：Skill 九要素要全，触发执行兜底装；
适用不适输入先，步骤工具输出框；
质量失败安全守，三段结构不能忘；
新手最爱漏护栏，边界兜底才稳当。