1.1 字段的详细要求#

name 字段：

• 必须为 1-64 个字符；
• 只能包含：a-z, 0-9, -；
• 不能以 - 开头或结尾；
• 不能包含连续的连字符 --；
• 必须与 parent directory name 保持一致。

description 字段：

• 必须为 1-1024 个字符；
• 应该同时描述：
  • 这个 skill 是做什么的；
  • 什么时候该调用它；
• 应该包含特定的关键词，帮助 Agent 识别相关的任务。

license 字段示例：

1
license: Proprietary. LICENSE.txt has complete terms

compatiability 字段：

• 大多数 skill 不需要该字段，仅当 skill 有特定环境要求的时候才应包含。

metadata 字段：

• 包含从字符串键到字符串值的映射；
• 客户端可以用该字段存储 agentskills.io 规范未定义的其他属性；
• 建议使用相对唯一的键名，以免冲突。

1
metadata:
2
  author: example-org
3
  version: "1.0"

allowed-tools 字段：

• 以空格分隔的字符串，列出预先批准可运行的工具；
• 实验性功能，不同 Agent 对该字段的支持可能不同。

1
allowed-tools: Bash(git:*) Bash(jq:*) Read

1.2 正文内容#

前置元数据之后的 Markdown 正文包含技能指令。没有格式限制。编写任何有助于代理有效执行任务的内容。

建议包含的部分：

• 分步说明
• 输入和输出示例
• 常见边缘情况

请注意，一旦代理决定激活技能，它将加载整个 SKILL.md 文件。如果内容较长，建议将部分内容拆分到引用的文件中。

2.1 scripts/#

包含代理可以运行的可执行代码。脚本应：

• 自包含或清楚说明依赖项
• 包含有用的错误信息
• 优雅地处理边缘情况

支持的语言取决于代理实现。常见选项包括 Python、Bash 和 JavaScript。

2.2 references/#

包含代理在需要时可读取的附加文档：

• REFERENCE.md - 详细技术参考
• FORMS.md - 表单模板或结构化数据格式
• 领域特定文件（finance.md、legal.md 等）

保持每个参考文件内容聚焦。代理按需加载这些文件，文件越小，占用的上下文就越少。

2.3 assets/#

包含静态资源：

• 模板（文档模板、配置模板）
• 图片（图表、示例）
• 数据文件（查找表、模式）

3.1 文件引用#

在技能中引用其他文件时，请使用相对于技能根目录的路径：

1
See [the reference guide](references/REFERENCE.md) for details.
2

3
Run the extraction script:
4
scripts/extract.py

请保持从 SKILL.md 出发的文件引用深度不超过一层。避免深层嵌套的引用链。

3.2 验证#

使用 skills-ref 参考库来验证你的技能：

1
skills-ref validate ./my-skill

该命令会检查你的 SKILL.md 前置元数据是否有效，并遵循所有命名约定。