Agent Skills 是一种用来给智能体（agents）提供新能力和专业知识的开放格式。本质上是：把指令、脚本和资源整理成“技能文件夹”，让智能体在需要时按需加载。
为什么需要 Agent Skills？
Agents 的能力越来越强，但在真实场景中经常缺少可靠执行任务所必需的上下文。Skills 通过提供可按需加载的流程知识以及公司、团队和个人的专属背景信息来解决这个问题。
有了 Skills，智能体可以根据当前任务动态扩展自己的能力。
- 对技能作者来说：只需构建一次能力，就能在多个智能体产品中复用。
- 对兼容的智能体来说：支持 Skills 之后，终端用户可以“开箱即用”地为智能体增加新能力。
- 对团队和企业来说：可以把组织知识沉淀成可移植、可版本控制的包。
Agent Skills 能实现什么？
- 领域专业知识：把专门领域的知识打包成可复用的指令，比如法务审查流程、数据分析流水线等。
- 全新能力：为智能体新增能力（例如制作演示文稿、构建 MCP 服务器、分析数据集）。
- 可重复的工作流：把多步骤任务变成标准化、可审计的工作流程。
- 互操作性：在不同支持 Skills 的智能体产品之间复用同一套技能。
技能如何工作
一个技能就是一个包含 SKILL.md 文件的文件夹。这个文件至少包含元数据（name 和 description），以及指导代理如何执行某个具体任务的说明。
示例结构
1my-skill/2├── SKILL.md # 必需：说明 + 元数据3├── scripts/ # 可选：可执行代码4├── references/ # 可选：文档与参考5└── assets/ # 可选：模板与资源
技能使用“逐步披露”（progressive disclosure）来高效管理上下文：
- 发现（Discovery）：启动时，代理只加载每个可用技能的名称与描述，刚好足够判断何时可能相关。
- 激活（Activation）：当任务与技能的描述匹配时，代理将把完整的 SKILL.md 说明读入上下文。
- 执行（Execution）：代理按照说明进行操作，并可按需加载引用文件或执行捆绑的代码。
这种方式让代理保持快速，同时在需要时获取更丰富的上下文。
SKILL.md 文件
每个技能都以一个包含 YAML 头信息和 Markdown 说明的 SKILL.md 文件开始：
示例
1---2name: pdf-processing3description: 从 PDF 文件中提取文本和表格、填写表单、合并文档。4---56# PDF 处理78## 何时使用此技能9当用户需要处理 PDF 文件时使用该技能……1011## 如何提取文本121. 使用 pdfplumber 进行文本提取……1314## 如何填写表单15...
这种简单格式的关键优势：
- 自我文档化：技能作者或用户可以直接阅读 SKILL.md 来理解其功能，便于审计与改进。
- 可扩展：技能可以从纯文本说明扩展到包含可执行代码、资源与模板的复杂形态。
- 可移植：技能就是文件，易于编辑、版本化与分享。
规范说明
目录结构
一个技能是一个至少包含 SKILL.md 文件的目录：
1skill-name/2└── SKILL.md # 必需
你可以按需添加其他目录（如 scripts/、references/、assets/）来支持技能。
SKILL.md 格式
SKILL.md 文件必须包含 YAML 前置头信息（frontmatter），后接 Markdown 正文内容。
前置头信息（必需）
1---2name: skill-name3description: 该技能的作用以及何时使用的描述。4---
可选字段示例：
1---2name: pdf-processing3description: 从 PDF 文件中提取文本与表格、填写表单、合并文档。4license: Apache-2.05metadata:6 author: example-org7 version: "1.0"8---
字段说明：
- name（必需）：最多 64 个字符。仅允许小写字母、数字和连字符。不得以连字符开头或结尾。
- description（必需）：最多 1024 个字符。非空。描述技能的作用与使用场景。
- license（可选）：许可证名称或指向随附许可证文件的引用。
- compatibility（可选）：最多 500 个字符。指明环境要求（目标产品、系统软件包、网络访问等）。
- metadata（可选）：用于附加元数据的键值映射。
- allowed-tools（可选）：技能可使用的预先批准工具的用空格分隔列表（实验性）。
name 字段
必需的 name 字段要求：
- 长度为 1–64 个字符
- 仅包含 Unicode 小写字母数字与连字符（a-z 与 -）
- 不得以连字符开头或结尾
- 不得包含连续连字符（–）
- 必须与父目录名称一致
有效示例：
name: pdf-processingname: data-analysisname: code-review
无效示例：
name: PDF-Processing, 不允许大写name: -pdf, 不得以连字符开头name: pdf--processing, 不允许连续连字符
description 字段
必需的 description 字段要求：
- 长度为 1–1024 个字符
- 应同时描述技能做什么、何时使用
- 建议包含有助于代理识别相关任务的关键词
良好示例：
1description: 从 PDF 文件中提取文本和表格、填写 PDF 表单并合并多个 PDF。用于处理 PDF 文档，或当用户提到 PDFs、表单、文档提取时使用。
较差示例：
1description: 帮助处理 PDF。
license 字段
可选的 license 字段：
- 指定应用于技能的许可证
- 建议保持简短（许可证名称或随附许可证文件名）
示例：
1license: Proprietary. LICENSE.txt has complete terms
compatibility 字段
可选的 compatibility 字段：1
- 若提供，长度为 1–500 个字符
- 仅在技能有特定环境要求时包含
- 可指明目标产品、需要的系统软件包、网络访问等
示例：
1compatibility: Designed for Claude Code (or similar products)
1compatibility: Requires git, docker, jq, and access to the internet
大多数技能无需 compatibility 字段。
metadata 字段
可选的 metadata 字段：
- 符串键到字符串值的映射
- 客户端可用来存储规范未定义的附加属性
- 建议使键名足够独特以避免冲突
示例：
1metadata:2 author: example-org3 version: "1.0"
allowed-tools 字段
可选的 allowed-tools 字段：
- 以空格分隔的可预先批准运行的工具列表
- 实验性。不同代理实现的支持情况可能不同
示例：
1allowed-tools: Bash(git:*) Bash(jq:*) Read
正文内容
frontmatter 之后的 Markdown 正文包含技能说明。没有格式限制。写下能帮助代理有效完成任务的内容。建议包含：
- 步骤式操作指南
- 输入与输出示例
- 常见边界情况
注意：当技能被激活后，代理会加载整个文件。对于较长的内容，建议拆分到引用文件中。
可选目录
scripts/
包含可供代理运行的可执行代码。脚本应当：
- 自包含或清楚记录依赖
- 包含有用的错误信息
- 能够优雅处理边界情况
支持语言取决于代理实现，常见选项包括 Python、Bash、JavaScript。
references/
包含代理在需要时可阅读的额外文档：
- REFERENCE.md—— 详细技术参考
- FORMS.md —— 表单模板或结构化数据格式
- 领域特定文件（如 finance.md]、legal.md 等）
保持单个参考文件聚焦。代理按需加载，文件更小意味着更少的上下文占用。
assets/
包含静态资源：
- 模板（文档模板、配置模板）
- 图片（图示、示例）
- 数据文件（查找表、模式）
渐进披露（Progressive disclosure）
技能应围绕高效使用上下文来组织：
- 元数据（约 100 tokens）：所有技能在启动时加载 name 与 description
- 说明（建议 < 5000 tokens）：当技能被激活时加载完整 SKILL.md 正文
- 资源（按需）：仅在需要时加载文件（如 `scripts/`、`references/`、`assets/` 中的内容）
建议将主 SKILL.md 控制在 500 行以内。详细的参考材料移动到独立文件。
文件引用
在技能中引用其他文件时，使用自技能根目录的相对路径：
1参见详细参考指南：2references/REFERENCE.md34运行提取脚本：5scripts/extract.py
保持从 SKILL.md 的文件引用深度为一级。避免深层的引用链。
校验
使用 skills-ref 库来校验你的技能：
1skills-ref validate ./my-skill
该命令会检查 SKILL.md 的前置头信息是否有效，并是否遵循所有命名约定。