技术参考· 教程
SKILL.md 结构详解
SKILL.md 的元数据、描述、指令与可选目录的参考说明。
入门阅读约 7 分钟更新于 2026年5月4日
一句话回答
Skill 本质上是一个目录，SKILL.md 是必备文件。它需要 name、description，以及代理在选中该 Skill 后要遵循的指令。
最小可用 Skill
---
name: focused-skill
description: Use when this exact repeatable workflow is needed. Explain when not to use it.
---
Instructions for the agent to follow.
元数据帮代理判断要不要加载完整 Skill；指令告诉代理在选中之后该怎么做。
description 是匹配契约
- 把会触发该 Skill 的任务写在最前面。
- 明确说明预期输出。
- 包含用户自然会输入的常见触发词。
- 在邻近 Skill 或 prompt 更合适时，写明排除条件。
渐进式加载让上下文保持精简
代理初始只看到可用 Skill 的名字、描述与路径，只有任务匹配时才会读取完整 SKILL.md。这就是为什么描述需要简洁、关键信息前置。
SKILL.md 越精简越好
高信号工作流写进 SKILL.md；长示例、长策略与体量大的参考资料放进 references/，按需加载。
可选目录
| 目录 | 用途 |
|---|---|
| scripts/ | 用于确定性检查或转换的可执行脚本。 |
| references/ | 长篇文档、示例、策略或领域备注。 |
| assets/ | 模板、起始文件、图片或可复用资源。 |
| agents/ | 可选的 OpenAI 元数据：展示信息、工具依赖等。 |