0%

skills 规范说明

Posted on In

目录结构

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

1
2
3
4
5
6
技能名称/
├── SKILL.md          # 必需：元数据 + 使用说明
├── scripts/          # 可选：可执行代码脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...               # 任何其他文件或目录

官网地址： https://agentskills.io/specification

SKILL.md格式

SKILL.md文件必须包含 YAML 前言（frontmatter），后接 Markdown 内容。

前言 （frontmatter）

字段 是否必需 约束条件
name 是 最多 64 个字符。仅限小写字母、数字和连字符（-）。不能以连字符开头或结尾。
description 是 最多 1024 个字符。非空。描述此技能的功能及何时使用它。
license 否 许可证名称或指向捆绑许可证文件的引用。
compatibility 否 最多 500 个字符。说明环境要求（预期产品、系统包、网络访问等）。
metadata 否 用于存储额外元数据的任意键值映射。
allowed-tools 否 技能可以使用的预批准工具的空格分隔列表。（实验性功能）

最小示例：

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

包含可选字段的示例：

1
2
3
4
5
6
7
8
---
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 个字符
  • 只能包含小写字母数字字符（a-z）和连字符（-）
  • 不能以连字符（-）开头或结尾
  • 不能包含连续的连字符（--）
  • 必须与父目录名称匹配

有效示例：

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

无效示例：

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

description字段

必需的 description字段：

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

良好示例：

1
description: 从PDF文件中提取文本和表格，填充PDF表单，并合并多个PDF。在需要处理PDF文档、或用户提到PDF、表单或文档提取时使用。

较差示例：

1
description: 处理PDF。

license字段

可选的 license字段：

  • 指定应用于此技能的许可证
  • 建议保持简短（许可证名称或捆绑的许可证文件名）

示例：

1
license: Proprietary. LICENSE.txt 文件包含完整条款

compatibility字段

可选的 compatibility字段：

  • 如果提供，必须为 1-500 个字符
  • 仅在您的技能有特定环境要求时应包含
  • 可说明目标产品、必需的系统包、网络访问需求等

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

示例：

1
compatibility: 专为 Claude Code（或类似产品）设计
1
compatibility: 需要 git、docker、jq 以及互联网访问权限
1
compatibility: 需要 Python 3.14+ 和 uv

metadata字段

可选的 metadata字段：

  • 一个从字符串键到字符串值的映射
  • 客户端可用此字段存储 Agent Skills 规范未定义的其他属性
  • 建议使您的键名具有合理的唯一性，以避免意外冲突

示例：

1
metadata:author: example-orgversion: "1.0"

allowed-tools字段

可选的 allowed-tools字段：

  • 一组被预先批准可以运行的工具的空格分隔列表
  • 实验性功能。对此字段的支持可能因智能体实现而异

示例：

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

正文内容

前言之后的 Markdown 正文包含技能的使用说明。没有格式限制。编写任何有助于智能体有效执行任务的内容。

推荐章节：

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

请注意，智能体决定激活某个技能后会一次性加载此文件的全部内容。如果 SKILL.md内容较长，请考虑将其拆分为引用的文件。

可选目录

scripts/

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

  • 自包含，或清晰记录依赖项
  • 包含有用的错误信息
  • 妥善处理边界情况

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

references/

包含智能体在需要时可以读取的额外文档：

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

保持各个参考文件内容专注。智能体按需加载这些文件，因此文件越小，占用的上下文越少。

assets/

包含静态资源：

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

渐进式披露

技能结构应便于高效使用上下文：

  1. 元数据（约 100 个词元）：所有技能的 name和 description字段在启动时加载
  2. 使用说明（建议小于 5000 个词元）：完整的 SKILL.md正文在技能激活时加载
  3. 资源（按需）：文件（例如 scripts/、references/或 assets/中的文件）仅在需要时加载

保持主 SKILL.md文件在 500 行以内。将详细的参考材料移至单独的文件。

文件引用

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

1
2
3
4
详细信息请参阅[参考指南](references/REFERENCE.md)。

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

文件引用应保持在 SKILL.md文件下一级深度。避免深层嵌套的引用链。

验证

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

1
skills-ref validate ./my-skill

这将检查您的 SKILL.md前言是否有效并遵循所有命名约定。