目录结构
一个 skill 至少是一个包含SKILL.md 文件的目录：
SKILL.md 格式
SKILL.md 文件必须包含 YAML frontmatter，后面跟着 Markdown 内容。
Frontmatter
最小示例：包含可选字段的示例：
SKILL.md
SKILL.md
name 字段
必填的 name 字段：
- 必须为 1 到 64 个字符
- 只能包含 unicode 小写字母数字字符（
a-z）和连字符（-） - 不能以连字符（
-）开头或结尾 - 不能包含连续连字符（
--） - 必须与父目录名称一致
有效示例：无效示例：
description 字段
必填的 description 字段：
- 必须为 1 到 1024 个字符
- 应同时说明这个 skill 做什么，以及什么时候使用它
- 应包含有助于 agent 识别相关任务的具体关键词
良好示例：较差示例：
license 字段
可选的 license 字段：
- 用于声明这个 skill 适用的许可证
- 建议保持简短（许可证名称，或随 skill 一起打包的许可证文件名即可）
示例：
compatibility 字段
可选的 compatibility 字段：
- 如果提供，长度必须为 1 到 500 个字符
- 只有当你的 skill 存在明确环境要求时才应填写
- 可用于说明目标产品、所需系统包、网络访问需求等
示例：
大多数 skills 都不需要
compatibility 字段。metadata 字段
可选的 metadata 字段：
- 是一个从字符串键到字符串值的映射
- 客户端可以用它存储 Agent Skills 规范中未定义的附加属性
- 建议让键名具备一定唯一性，以避免意外冲突
示例：
allowed-tools 字段
可选的 allowed-tools 字段：
- 一个以空格分隔的工具列表，表示这些工具已被预批准可执行
- 该字段属于实验性能力，不同 agent 实现对它的支持程度可能不同
示例：
正文内容
frontmatter 之后的 Markdown 正文包含 skill 的实际说明。正文没有固定格式限制，只要能帮助 agent 有效完成任务即可。 推荐包含的部分：- 分步骤说明
- 输入与输出示例
- 常见边界情况
SKILL.md，应考虑把内容拆分到被引用的文件中。
可选目录
scripts/
包含 agent 可执行的代码。脚本应当：
- 尽量自包含，或者清晰说明依赖项
- 提供有帮助的错误信息
- 对边界情况做出稳妥处理
references/
包含 agent 在需要时可以读取的附加文档：
REFERENCE.md- Detailed technical referenceFORMS.md- Form templates or structured data formats- Domain-specific files (
finance.md,legal.md, etc.)
assets/
包含静态资源：
- 模板（文档模板、配置模板）
- 图片（图示、示例）
- 数据文件（查找表、schema）
渐进式披露
skills 应当围绕“高效使用上下文”来组织：- 元数据（约 100 tokens）：启动时会为所有 skills 加载
name和description字段 - 说明（建议少于 5000 tokens）：skill 被激活时会加载完整的
SKILL.md正文 - 资源（按需加载）：只有在确实需要时，才会加载
scripts/、references/或assets/等目录中的文件
SKILL.md 控制在 500 行以内。更详细的参考材料应拆到独立文件中。
文件引用
当在 skill 中引用其他文件时，应使用相对于 skill 根目录的路径：SKILL.md
SKILL.md 的一层深度内，避免形成过深的引用链。
校验
使用 skills-ref 参考库来校验你的 skills：SKILL.md frontmatter 是否有效，并确认是否遵循了所有命名约定。