企业官网建设流程全解析

title: “Agent Skills 规范说明”
description: “Agent Skills 的完整格式规范。”

目录结构

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

skill-name/ ├── SKILL.md # Required: metadata + instructions (必需：元数据 + 指令) ├── scripts/ # Optional: executable code (可选：可执行代码) ├── references/ # Optional: documentation (可选：文档) ├── assets/ # Optional: templates, resources (可选：模板、资源) └── ... # Any additional files or directories (任何其他的文件或目录)

SKILL.md格式

SKILL.md文件必须包含 YAML frontmatter，其后是 Markdown 内容。

Frontmatter

Frontmatter 是内容文件的头部元数据，是整个内容系统的数据基础。
你可以在 Markdown 文件的顶部添加 front matter。它是一个使用 YAML 格式定义元数据的块，位于文件顶部的三个连字符---之间。

最小示例：

--- name: skill-name description: A description of what this skill does and when to use it. ---

带可选字段的示例：

--- name: pdf-processing description: Extract PDF text, fill forms, merge files. Use when handling PDFs. license: Apache-2.0 metadata: author: example-org version: "1.0" ---

name字段

必需的name字段：

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

有效示例：

name:pdf-processing

name:data-analysis

name:code-review

无效示例：

name:PDF-Processing# uppercase not allowed

name:-pdf# cannot start with hyphen

name:pdf--processing# consecutive hyphens not allowed

description字段

必需的description字段：

• 必须为 1-1024 个字符
• 应同时描述技能的用途以及使用时机
• 应包含有助于智能体识别相关任务的具体关键词

良好示例：

description:Extracts text and tables from PDF files,fills PDF forms,and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs,forms,or document extraction.

欠佳示例：

description:Helps with PDFs.

license字段

可选的license字段：

• 指明应用于该技能的许可证
• 我们建议保持简短（许可证名称或打包的许可证文件名）

示例：

license:Proprietary. LICENSE.txt has complete terms

compatibility字段

可选的compatibility字段：

• 若提供，必须为 1-500 个字符
• 仅当技能有特定环境要求时才应包含
• 可标明目标产品、所需的系统软件包、网络访问需求等

示例：

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

大多数技能不需要compatibility字段。

metadata字段

可选的metadata字段：

• 一个从字符串键到字符串值的映射
• 客户端可借此存储 Agent Skills 规范未定义的额外属性
• 我们建议让键名具备一定的唯一性，以避免意外的冲突

示例：

metadata:author:example-orgversion:"1.0"

allowed-tools字段

可选的allowed-tools字段：

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

示例：

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

正文内容

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

推荐章节：

• 分步指令
• 输入与输出示例
• 常见边界情况

请注意，一旦智能体决定激活某个技能，就会加载该文件的全部内容。对于较长的SKILL.md，建议将部分内容拆分到被引用的文件中。

可选目录

scripts/

存放智能体可执行的可运行代码。脚本应：

• 自包含，或清晰地记录其依赖
• 包含有用的错误提示
• 妥善处理边界情况

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

references/

存放智能体可按需阅读的补充文档：

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

保持各个参考文件聚焦。智能体按需加载这些文件，因此文件越小，上下文消耗越少。

assets/

存放静态资源：

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

渐进式披露

智能体渐进式地加载技能，仅在任务需要时才拉取更多细节。技能的结构应充分利用这一点：

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

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

文件引用

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

See [the reference guide](references/REFERENCE.md) for details. Run the extraction script: scripts/extract.py

文件引用请保持在距SKILL.md一层以内。避免过深的嵌套引用链。

验证

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

skills-ref validate ./my-skill

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