Skip to content
Agent Skills 中文翻译

Agent Skills 规范

本页为 Agent Skills 规范的非官方中文翻译。

Agent Skills 规范

Section titled “Agent Skills 规范”

本页定义 Agent Skills 格式的完整规范。

目录结构

Section titled “目录结构”

一个 Skill 是一个目录，至少包含一个 SKILL.md 文件：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考资料
├── assets/           # 可选：模板、资源
└── ...               # 任意其他文件或目录

SKILL.md 格式

Section titled “SKILL.md 格式”

SKILL.md 文件 MUST 包含 YAML frontmatter，后接 Markdown 内容。

Frontmatter

Section titled “Frontmatter”
字段是否必需约束
name是最多 64 个字符。仅允许小写字母、数字和连字符。不能以连字符开头或结尾。
description是最多 1024 个字符。非空。描述该 Skill 的功能以及何时使用它。
license否许可名称或对打包的许可文件的引用。
compatibility否最多 500 个字符。说明环境要求（预期产品、系统包、网络访问等）。
metadata否任意键值映射，用于附加元数据。
allowed-tools否由空格分隔的字符串，列出 Skill 可使用的预先批准的工具。（实验性）

最小示例：

---
name: skill-name
description: 描述该 Skill 的功能以及何时使用它。
---

包含可选字段的示例：

---
name: pdf-processing
description: 提取 PDF 文本、填写表单、合并文件。处理 PDF 时使用。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

name 字段

Section titled “name 字段”

必需的 name 字段：

  • MUST 为 1-64 个字符
  • MAY 仅包含 unicode 小写字母数字字符（a-z、0-9）和连字符（-）
  • MUST 不以连字符（-）开头或结尾
  • MUST 不包含连续的连字符（--）
  • MUST 与父目录名称一致

有效示例：

name: pdf-processing
name: data-analysis
name: code-review

无效示例：

name: PDF-Processing  # 不允许大写
name: -pdf  # 不能以连字符开头
name: pdf--processing  # 不允许连续的连字符

description 字段

Section titled “description 字段”

必需的 description 字段：

  • MUST 为 1-1024 个字符
  • SHOULD 同时描述该 Skill 的功能以及何时使用它
  • SHOULD 包含帮助智能体识别相关任务的具体关键词

良好的示例：

description: 从 PDF 文件提取文本和表格，填写 PDF 表单，并合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单、文档提取时使用。

不佳的示例：

description: 协助处理 PDF。

license 字段

Section titled “license 字段”

可选的 license 字段：

  • 指定应用于该 Skill 的许可证
  • 建议保持简短（许可名称或打包的许可文件名称）

示例：

license: Proprietary. LICENSE.txt has complete terms

compatibility 字段

Section titled “compatibility 字段”

可选的 compatibility 字段：

  • 提供时 MUST 为 1-500 个字符
  • SHOULD 仅在你的 Skill 具有特定环境要求时包含
  • 可以说明预期产品、所需的系统包、网络访问需求等

示例：

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv

译者注：大多数 Skill 不需要 compatibility 字段。

metadata 字段

Section titled “metadata 字段”

可选的 metadata 字段：

  • 由字符串键到字符串值的映射
  • 客户端可以用它存储 Agent Skills 规范未定义的附加属性
  • 建议让键名具有合理的唯一性，以避免意外冲突

示例：

metadata:
  author: example-org
  version: "1.0"

allowed-tools 字段

Section titled “allowed-tools 字段”

可选的 allowed-tools 字段：

  • 由空格分隔的字符串，列出预先批准运行的工具
  • 实验性。不同智能体实现对该字段的支持程度可能不同

示例：

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

正文内容

Section titled “正文内容”

frontmatter 之后的 Markdown 正文包含 Skill 指令。没有格式限制。编写任何有助于智能体有效完成任务的内容即可。

推荐章节：

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

请注意，一旦智能体决定激活某个 Skill，它将加载整个文件。建议将较长的 SKILL.md 内容拆分为引用的文件。

可选目录

Section titled “可选目录”

scripts/

Section titled “scripts/”

包含智能体可以运行的可执行代码。脚本 SHOULD：

  • 自包含或清晰地记录依赖
  • 包含有用的错误消息
  • 优雅地处理边界情况

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

references/

Section titled “references/”

包含智能体在需要时可以阅读的附加文档：

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

请保持各个 引用文件 内容聚焦。智能体按需加载这些文件，因此文件越小，消耗的上下文越少。

assets/

Section titled “assets/”

包含静态资源：

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

Progressive Disclosure / 渐进式披露

Section titled “Progressive Disclosure / 渐进式披露”

智能体以 渐进 方式加载 Skills，仅在任务需要时才引入更多细节。Skills SHOULD 进行相应的结构化以利用这一点：

  1. 元数据（约 100 tokens）：启动时为所有 Skills 加载 name 和 description 字段
  2. 指令（建议小于 5000 tokens）：激活 Skill 时加载完整的 SKILL.md 正文
  3. 资源（按需）：仅在需要时加载文件（例如 scripts/、references/ 或 assets/ 中的文件）

请将主 SKILL.md 控制在 500 行以内。将详细的参考资料移至单独的文件。

文件引用

Section titled “文件引用”

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

详见 [参考指南](references/REFERENCE.md)。


运行提取脚本：
scripts/extract.py

请保持文件引用与 SKILL.md 仅一层深度。避免深度嵌套的引用链。

验证

Section titled “验证”

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

Terminal window
skills-ref validate ./my-skill

这会检查你的 SKILL.md frontmatter 是否有效，并遵循所有命名约定。