Skill 是什么？
Skill 不是一段 prompt，而是一份 带触发条件的可复用指令包。把它的内部结构画出来，5 分钟就能看明白。
- 核心观点：skill = 触发条件 + 指令正文 + 可选资源三层结构，和 prompt 的区别在「可被自动加载」。
- 第一层：YAML frontmatter 里的
name/description决定何时触发，决定 agent 是否"看见"它。 - 第二层：Markdown 正文是 agent 真正读到并执行的内容，等价于一段 system prompt 补丁。
- 第三层：
references/scripts/assets/是按需调用的工具集，不进 context。
Skill 和 prompt 最大的区别是什么？
prompt 是你手动粘进对话窗口的话，skill 是 agent 自动加载的话。
一个 skill 文件本质上是一个 Markdown 文件夹，但它有三个明确的层次：
这张图就是 Token杰-自然智群 在 2 分钟视频里讲清楚的核心：skill 不是一坨文本，而是 触发层 + 内容层 + 资源层 的组合。
第一层：YAML frontmatter 决定"何时触发"
文件最开头 --- 包裹的部分，是 agent loader 的入口。它通常长这样：
---
name: pdf-extract
description: 从 PDF 抽取表格和文字，支持 OCR 识别扫描件。当用户上传 PDF 或提到「解析 PDF」「提取表格」时使用。
---
两个字段的作用不同：
| 字段 | 决定什么 | 写错会怎样 |
|---|---|---|
name | skill 在文件系统里的标识 | agent 找不到文件 |
description | 何时 自动加载 这个 skill | 描述太抽象 → agent 永远不调用；太具体 → 漏掉变体场景 |
description 是整个 skill 设计里 最容易被低估的一行。它本质上是一段「自然语言触发规则」——agent 在决定要不要读这个 skill 时，唯一依据就是这段话。
判断标准：把
description单独抽出来给一个不懂这个 skill 的人看，如果他/她能判断「该用 / 不该用」，就合格。
第二层：Markdown 正文是真正执行的指令
去掉 frontmatter 后剩下的 Markdown，是 agent 加载后会读进 context 的内容。它和写 prompt 看起来很像，但有三点关键差异：
- 结构化：用 H2/H3 拆分阶段，每个阶段有明确输入输出。
- 可执行步骤：用编号列表写「先做 A、再做 B、最后检查 C」，不要写「请你……」这种礼貌句。
- 边界条件：明确写出「不 做什么」、「何时停下来问用户」、「失败时怎么 fallback」。
正文长度通常在 100-500 行 之间。太短说明没想清楚边界，太长说明没拆步骤。
一个反例：
❌ 错误：把 skill 写成一封说明信
"你好，我是 PDF 抽取助手。我很擅长处理 PDF 文件。如果你有 PDF 需要处理，
请告诉我，我会帮你抽取里面的内容..."
正确写法：
✅ 正确：把 skill 写成操作手册
## 输入
- 单个 PDF 文件路径（必填）
- 输出格式：json / markdown（默认 markdown）
## 处理流程
1. 用 `pdftotext` 提取文本层
2. 若文本层为空，调用 `tesseract` OCR 扫描件
3. 抽取表格 → 转成 markdown 表格
## 失败处理
- 文件 > 50MB：报错并提示「请先压缩」
- 加密 PDF：返回错误，不要尝试破解
第三层：references / scripts / assets 按需加载
SKILL.md 同级目录里通常有三个可选文件夹：
| 文件夹 | 用途 | 何时被加载 |
|---|---|---|
references/ | 长文档、API 手册、领域知识 | agent 在 SKILL.md 里读到「参考 X」时 主动 Read |
scripts/ | 可执行脚本（Python / Bash / Node） | agent 决定「跑一下」时 调用工具执行 |
assets/ | 模板文件、图片、配置文件 | agent 需要生成同类内容时 复制使用 |
这层的核心设计原则是 「不进 context」——只有在 agent 真正需要时才加载，避免 token 浪费。
举个例子，一个「写周报」skill 的目录：
weekly-report/
├── SKILL.md # 主入口（必读）
├── references/
│ ├── company-okr.md # 公司 OKR 文档（按需读）
│ └── last-quarter.md # 上季度总结（按需读）
├── scripts/
│ └── fetch-jira.py # 拉取 Jira 数据（按需跑）
└── assets/
└── template.md # 周报模板（按需复制）
agent 加载这个 skill 时，只读 SKILL.md（约 50 行）。等它决定要写周报时，才会去 read references 里的 OKR 文档、run fetch-jira.py、copy template.md。