Skip to main content

​
目录结构

技能是一个包含至少一个 SKILL.md 文件的目录：

​
SKILL.md 格式

SKILL.md 文件必须包含 YAML 前置元数据，后跟 Markdown 内容。

​
前置元数据

最小示例：
SKILL.md
包含可选字段的示例：
SKILL.md

​
name 字段

必需的 name 字段：
  • 必须为 1-64 个字符
  • 仅可包含 Unicode 小写字母数字字符（a-z、0-9）和连字符（-）
  • 不得以连字符（-）开头或结尾
  • 不得包含连续连字符（--）
  • 必须与父目录名称匹配
有效示例：
无效示例：

​
description 字段

必需的 description 字段：
  • 必须为 1-1024 个字符
  • 应描述技能的作用以及何时使用它
  • 应包含帮助代理识别相关任务的具体关键词
好示例：
差示例：

​
license 字段

可选的 license 字段：
  • 指定应用于技能的许可证
  • 我们建议保持简短（要么是许可证名称，要么是捆绑许可证文件的名称）
示例：

​
compatibility 字段

可选的 compatibility 字段：
  • 如果提供，必须为 1-500 个字符
  • 仅当您的技能有特定环境要求时才应包含
  • 可以指示预期产品、所需的系统包、网络访问需求等。
示例：
大多数技能不需要 compatibility 字段。

​
metadata 字段

可选的 metadata 字段：
  • 从字符串键到字符串值的映射
  • 客户端可使用此字段存储 Agent Skills 规范未定义的附加属性
  • 我们建议使键名具有合理的独特性，以避免意外冲突
示例：

​
allowed-tools 字段

可选的 allowed-tools 字段：
  • 一个以空格分隔的工具字符串，这些工具是预先批准可运行的
  • 实验性。不同的代理实现对该字段的支持可能不同
示例：

​
正文内容

前置元数据后的 Markdown 正文包含技能指令。没有格式限制。编写任何能帮助代理有效执行任务的内容。 推荐部分：
  • 分步指令
  • 输入和输出示例
  • 常见边缘情况
请注意，代理一旦决定激活技能，将加载整个文件。考虑将较长的 SKILL.md 内容拆分到引用文件中。

​
可选目录

​
scripts/

包含代理可运行的可执行代码。脚本应：
  • 自包含或清楚记录依赖项
  • 包含有帮助的错误消息
  • 优雅地处理边缘情况
支持的语言取决于代理实现。常见选项包括 Python、Bash 和 JavaScript。

​
references/

包含代理在需要时可阅读的附加文档：
  • REFERENCE.md - 详细技术参考
  • FORMS.md - 表单模板或结构化数据格式
  • 特定领域文件（finance.md、legal.md 等）
保持单个 参考文件 专注。代理按需加载这些文件，因此较小的文件意味着更少占用上下文。

​
assets/

包含静态资源：
  • 模板（文档模板、配置模板）
  • 图像（图表、示例）
  • 数据文件（查找表、模式）

​
渐进式披露

代理会逐步加载技能，只有在任务需要时才引入更多细节。技能应设计为充分利用这一点：
  1. 元数据（约 100 个 token）：启动时会为所有技能加载 name 和 description 字段
  2. 指令（建议 < 5000 个 token）：在技能激活时加载 SKILL.md 正文
  3. 资源（按需）：仅在需要时加载 scripts/、references/ 或 assets/ 中的文件
将主 SKILL.md 保持在 500 行以下。将详细参考材料移至单独的文件。

​
文件引用

在技能中引用其他文件时，使用相对于技能根目录的路径：
SKILL.md
保持文件引用从 SKILL.md 起只有一层深度。避免深层嵌套的引用链。

​
验证

使用 skills-ref 参考库来验证您的技能：
这将检查您的 SKILL.md 前置元数据是否有效并遵循所有命名约定。