Agent Skills

Agent Skills 概述

Agent Skills 是一种为 Agent 赋予全新功能与专业能力的标准化方案。

什么是 Agent Skills

Agent Skills 是一种轻量、开放的格式，可借助专业知识与工作流拓展 AI Agent 的能力。

从本质上来说，技能是一个存放着SKILL.md文件的文件夹。该文件包含元数据（至少需填写 name 与 description 两项）以及指引 Agent 完成特定任务的操作指令。技能包中还可整合脚本、参考资料、模板及其他各类资源。

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

为什么需要 Agent Skills

Agent 的能力正在不断提升，但它们往往缺少可靠完成实际工作所需的上下文信息。Skills 可解决这一问题：它将流程化知识以及企业、团队、用户专属的上下文信息封装为可移植、支持版本管理的文件夹，供 Agent 按需加载。这能为智能体带来如下优势：

领域专业能力：将各类专业知识 —— 从合规审核流程、数据分析流程到演示文稿排版规范 —— 整理为可重复使用的操作指引与配套资源。
可复用工作流：将多步骤任务转化为规范统一、可审计的流程。
跨产品复用：只需创建一次技能，即可在所有兼容该技能的智能体中使用。

Agent Skills 如何工作

Agent 通过渐进式加载机制加载技能，分为三个阶段：

发现阶段：启动时，Agent 仅加载每项可用 skill 的名称与描述，仅获取足以判断该 skill 是否适用的基础信息。
激活阶段：当任务与某项 skill 的描述匹配时，Agent 会将完整的 SKILL.md 指令加载至上下文。
执行阶段：Agent 按照指令执行操作，可根据需求运行配套代码或加载引用文件。

完整指令仅在任务需要时加载，Agent 因此可储备大量可用 skills，同时仅占用极小的上下文空间。

Agent Skills 规格说明

Agent Skills 完整格式规范。

目录结构

一项 Skill 是一个目录，其中至少包含一个 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 前置元数据，其后紧跟 Markdown 正文内容。

YAML 元数据

Field	Required	Constraints
`name`	Yes	最多 64 个字符。仅允许小写字母、数字与连字符，首尾不得使用连字符。
`description`	Yes	最多 1024 个字符，内容不可为空，用于说明该 skill 的功能以及适用场景。
`license`	No	License name or reference to a bundled license file.
`compatibility`	No	Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
`metadata`	No	Arbitrary key-value mapping for additional metadata.
`allowed-tools`	No	Space-separated string of pre-approved tools the skill may use. (Experimental)

最简单的 skill 示例

---
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` 字段

字符长度需为 1 至 64 位
仅可包含 Unicode 小写字母数字字符（a-z、0-9）与连字符（-）
不得以连字符（-）开头或结尾
不可出现连续连字符（--）
需与上级目录名称保持一致

name: pdf-processing

`description` 字段

字符长度需为 1 至 1024 个
需同时说明该技能的功能与适用场景
需包含可协助 Agent 识别相关任务的特定关键词

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.

`license` 字段

指定该 skill 所使用的许可证
建议填写简短内容（可为许可证名称或配套许可证文件名称）

license: Proprietary. LICENSE.txt has complete terms

`compatibility` 字段

若填写，字符长度需在 1 至 500 个之间
仅当你的工具存在特定环境要求时才需填写此项
可标注适配产品、所需系统软件包、网络访问需求等信息

compatibility: Requires git, docker, jq, and access to the internet

`metadata` 字段

字符串格式的 key-value 映射表
客户端可通过该字段存储 Agent Skills 规范中未定义的附加属性
建议设置辨识度较高的键名，防止出现意外冲突

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

`allowed-tools` 字段

以空格分隔、预先获准可运行的工具字符串
实验性功能。不同智能代理实现方案对该字段的支持程度存在差异

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

`SKILL.md` 正文

YAML 元数据之后的 Markdown 正文包含技能说明，无格式限制，可撰写一切能助力 Agent 高效完成任务的内容。

推荐板块：

分步操作指南
输入输出示例
常见边界场景

请注意，Agent 一旦确定启用某项 skill，就会加载整个文件。可考虑将篇幅较长的 SKILL.md 内容拆分至引用文件中。

可选目录

`scripts/`

包含 Agent 可运行的可执行代码。脚本需满足以下要求：

独立完整，或清晰说明依赖项
附带易懂的错误提示信息
妥善处理各类极端场景

支持的编程语言由 Agent 的实现方式决定，常用语言包括 Python、Bash 以及 JavaScript。

`references/`

存放 Agent 按需查阅的补充文档：

REFERENCE.md—— 详细技术参考文档
FORMS.md—— 表单模板或结构化数据格式文件
各专业领域专用文件（如finance.md、legal.md等）

每份reference 文件内容需主题专一。Agent 会按需加载这类文件，文件体积越小，占用上下文资源越少。

`assets/`

包含静态资源：

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

渐进式加载

Agent 逐步加载 skill，仅在任务需要时调取更多详细信息。skill 的结构设计应适配这一特性：

元数据（约 100 token）：所有 skill 启动时会加载 name 与 description 字段
操作指引（建议少于 5000 token）：激活对应 skill 时，完整加载 SKILL.md 全部内容
资源文件（按需加载）：仅在必要时读取各类文件（例如存放于scripts/、references/或assets/目录下的文件）

将主文件 SKILL.md 控制在 500 行以内。将详细参考资料拆分至独立文件中。

引用文件

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

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

Run the extraction script:
scripts/extract.py

文件引用路径需仅与 SKILL.md 相差一级目录，避免多层嵌套的引用链路。

内容来源：
Agent Skills Overview
Agent Skills Specification

Agent Skills 概述#

什么是 Agent Skills#

为什么需要 Agent Skills#

Agent Skills 如何工作#

Agent Skills 规格说明#

目录结构#

SKILL.md 格式#

YAML 元数据#

最简单的 skill 示例#

name 字段#

description 字段#

license 字段#

compatibility 字段#

metadata 字段#

allowed-tools 字段#

SKILL.md 正文#

可选目录#

scripts/#

references/#

assets/#

渐进式加载#

引用文件#