智能体技能：可复用的能力包

到底什么是「技能」——一个包含指令、脚本与资源的文件夹，由智能体按需加载。

什么是技能

技能（Skill） 是一个自包含的软件包，用来教会智能体一项可重复的能力。你不必每次会话重复敲一遍指令，而是交付一个文件夹，由智能体在相关场景自动发现并加载。

一个结构良好的最小技能包含：

my-skill/
├── SKILL.md        # frontmatter（名称、描述）+ 操作指令
├── scripts/        # 智能体可直接执行的脚本
├── references/     # 仅在需要时加载的参考文档
└── assets/         # 模板、图片、脚手架文件

核心设计原则：渐进式披露

信息分三层加载，让上下文窗口始终保持精简：

1. 元数据（始终加载）——frontmatter 里的 name 与 description，足以判断相关性即可。
2. 正文（命中时加载）——SKILL.md 的主体指令。
3. 捆绑资源（按需加载）——脚本与参考文档，由正文引用。

若把全部内容都塞进第 1 层，就失去了意义：无论是否相关，每次请求都在烧上下文。

写出真正能触发的描述

description 字段是技能能否被触发的最大杠杆。它应该交代：

• 做什么（What）
• 何时用（When）——具体的触发条件、文件类型、用户意图
• 产出什么（What format）

反例：帮助处理文档。

正例：从 PDF 中提取文本与表格、填写表单、合并文档。当用户处理 PDF 文件，或提到 PDF、表单、文档抽取时使用。

常见故障模式