Agent Skills 入门：SKILL.md 怎么写才会被正确触发

Skill 的本质是一个目录 + 一份 SKILL.md。SKILL.md 由两部分组成：YAML frontmatter（元数据）和 markdown 正文（指令）。看起来简单，但「写得对」和「写得能被触发」是两回事。

目录结构

my-skill/
├── SKILL.md          # 必需：主指令
├── reference.md      # 可选：详细参考，按需加载
├── examples/         # 可选：示例输出
└── scripts/          # 可选：可执行脚本

frontmatter 的两个硬要求

---
name: optimizing-prompts
description: 分析并重写生图/生视频提示词，按模型差异调整结构。当用户提到提示词优化、改提示词、prompt 调优时使用。
---

• name：只能小写字母、数字、连字符；不超过 64 字符；不能用保留词。推荐动名词形式（optimizing-prompts），一眼看出这个 Skill 提供什么能力。
• description：这是决定能不能被触发的唯一字段。必须写清两件事 ——「做什么」+「什么时候用」，并且必须用第三人称。

✅ Processes Excel files and generates reports
❌ I can help you process Excel files      （第一人称，触发率差）
❌ You can use this to process Excel files （第二人称，同样有问题）
❌ Helps with documents                     （太模糊，模型无法判断何时用）

渐进式披露：三段加载

1. 启动时：只加载所有 Skill 的 name + description（元数据）。所以 description 必须自洽，不能依赖正文。
2. 触发时：加载 SKILL.md 正文。
3. 需要时：才加载 reference / examples / scripts。

这个机制的直接推论：SKILL.md 正文建议控制在 500 行以内，超了就拆到辅助文件里，在正文里写「详见 FORMS.md」。

自由度要匹配任务

• 高自由度（纯文字指令）：多种做法都行、依赖上下文判断 —— 例如代码审查流程。
• 中自由度（模板 + 参数）：有推荐模式但允许变化 —— 例如按模板生成报告。
• 低自由度（固定脚本）：步骤脆弱、必须按顺序 —— 例如数据库迁移，就写「原样执行这条命令，不要改参数」。

类比：两侧是悬崖的窄桥要装护栏（低自由度）；开阔田野只需要给方向（高自由度）。

一个完整示例

---
name: optimizing-prompts
description: 分析并重写生图 / 生视频提示词，按模型差异调整结构。当用户想要优化提示词、改写 prompt、或提示词效果不好时使用。
---

# 提示词优化

## 步骤
1. 先判断目标模型（Seedance / 海螺 / 可灵 / Veo / Midjourney 等）。
2. 按该模型的结构模板重写，不要跨模型套用结构。
3. 只改一个变量，保留其余部分，便于用户对比。

## 模型差异
- Seedance：主体调度在前，环境写氛围不写地理位置
- 海螺：方括号运镜指令，必须有 [保持] 子句
- 可灵：单镜头单动作，结尾给动作落定点
- Veo：环境细节写满，对白标注说话人与语气

## 输出格式
先给「问题诊断」三条以内，再给重写后的完整提示词。

最容易踩的两个坑

• description 写成自我介绍（「我是一个帮你写提示词的助手」）—— 模型无法据此判断何时调用。
• 正文写成教程：Skill 正文是给模型看的执行指令，不是给人看的科普。一句「做什么」胜过三段「为什么」。