本文是一份完整的Agent Skills指南，适合新手入门和开发者参考。内容涵盖Skills的基本概念、格式规范，以及如何将其集成到AI Agent中，所有内容通俗易懂，同时符合搜索引擎收录标准，帮助你快速掌握Agent Skills的核心用法。

第一章：什么是Skills？

Agent Skills的核心，就是一个包含SKILL.md文件的文件夹。这个文件是必需的，里面要包含元数据（至少要有name和description），还要写清楚让Agent执行特定任务的指令。除此之外，Skills还能捆绑脚本、模板和参考资料，方便Agent更好地完成任务。

一个标准的Skill文件夹结构如下（可直接复制使用）：

my-skill/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：可执行代码（如Python、Bash脚本）
├── references/       # 可选：文档资料（如技术说明、使用手册）
└── assets/           # 可选：模板、资源（如图片、配置模板）

Skills的工作原理

Skills用“渐进式披露”的方式管理上下文，这样能让Agent运行更快，同时按需获取所需信息，具体分为三个阶段：

1. 发现阶段：Agent启动时，只加载每个可用Skill的名称和描述，刚好能判断这个Skill是否和当前任务相关。

2. 激活阶段：如果用户的任务和某个Skill的描述匹配，Agent就会把这个Skill的完整SKILL.md指令加载到上下文里。

3. 执行阶段：Agent按照SKILL.md里的指令操作，需要时再加载参考文件或执行捆绑的脚本。

SKILL.md 文件详解

每个Skill都从SKILL.md文件开始，这个文件由两部分组成：YAML前端元数据和Markdown指令，格式固定，简单易写。

以下是一个完整的SKILL.md示例（PDF处理相关），可直接参考修改：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files, such as extracting text, getting tables from PDFs, filling PDF forms, or merging multiple PDF files.

## How to extract text
1. Use pdfplumber for text extraction. Install it first with "pip install pdfplumber" if not installed.
2. Open the PDF file using pdfplumber.open("file.pdf").
3. Iterate through each page of the PDF and extract text with page.extract_text().
4. Save the extracted text to a new file or return it directly to the user.

## How to fill forms
Use the pdfrw library to fill PDF forms. Follow these steps:
1. Install pdfrw with "pip install pdfrw".
2. Load the PDF form using pdfrw.PdfReader("form.pdf").
3. Fill the form fields by modifying the Annotations of the PDF.
4. Save the filled form with pdfrw.PdfWriter().write("filled_form.pdf", reader).

SKILL.md顶部的前端元数据是必需的，主要包含两个核心字段：

1. name：简短的标识符，用来区分不同的Skill，比如pdf-processing、>2. description：说明这个Skill能做什么、什么时候用，要写清楚，方便Agent识别相关任务。

前端元数据之后的Markdown正文，就是具体的执行指令，没有固定格式，只要能让Agent看懂、能顺利执行任务就行。

这种简单的格式有三个明显优势：

1. 自文档化：不管是Skill的作者还是使用者，看SKILL.md就能明白它的功能，方便检查和改进。

2. 可扩展：Skill的复杂程度可高可低，简单的只有纯文本指令，复杂的可以包含可执行代码、各类资源和模板。

3. 可移植：Skills就是普通的文件，编辑、版本控制（比如用Git）和共享都很方便。

第二章：Agent Skills 规范

这一章主要讲Agent Skills的格式规范，只要按照这些规范来创建Skill，就能保证兼容性，让不同的Agent都能正常识别和使用。

目录结构规范

一个合格的Skill，必须是一个包含SKILL.md文件的文件夹，最基础的结构如下：

skill-name/
└── SKILL.md          # 必需，不能缺少

你可以根据需要，选择性添加scripts/、references/和assets/这三个目录，来丰富Skill的功能：

- scripts/：放可执行代码，比如Python、Bash脚本，供Agent执行特定操作。

- references/：放额外的文档资料，比如详细的技术说明、领域相关的参考文件。

- assets/：放静态资源，比如文档模板、图片、配置文件等。

SKILL.md 格式规范

SKILL.md文件必须包含YAML前端元数据，后面跟Markdown正文，两者缺一不可。

前端元数据（必需）

最基础的前端元数据格式如下，不能省略任何一个字段：

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

除了必需字段，还可以添加可选字段，丰富元数据信息，示例如下：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

各字段详细要求

下面是每个字段的具体要求，一定要严格遵守，否则Agent可能无法识别Skill：

1. name（必需）

- 长度：1-64个字符。

- 内容：只能包含小写字母、数字和连字符（a-z、0-9、-）。

- 禁忌：不能以连字符开头或结尾，不能有连续的连字符（比如pdf--processing），必须和父文件夹名称完全一致。

有效示例：pdf-processing、>无效示例：PDF-Processing（有大写）、-pdf（以连字符开头）、pdf--processing（连续连字符）

2. description（必需）

- 长度：1-1024个字符，不能为空。

- 内容：要明确说明Skill的功能和使用场景，最好包含关键词，方便Agent识别相关任务。

好的示例：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.

不好的示例：Helps with PDFs.（太模糊，Agent无法判断何时使用）

3. license（可选）

- 作用：指定Skill的许可证。

- 要求：尽量简短，可以写许可证名称，或者引用捆绑的许可证文件。

示例：license: Proprietary. LICENSE.txt has complete terms

4. compatibility（可选）

- 长度：1-500个字符。

- 作用：只有Skill有特定环境要求时才需要写，比如需要的目标产品、系统包、网络访问等。

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

注意：大多数Skill不需要这个字段，只有有特殊要求时才添加。

5. metadata（可选）

- 作用：存储额外的元数据，是键值对的形式。

- 要求：键名要唯一，避免和其他字段冲突，比如作者、版本号等。

示例：

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

6. allowed-tools（可选）

- 作用：指定Agent可以使用的预批准工具，用空格分隔。

- 注意：这是实验性功能，不同Agent对这个字段的支持情况不一样。

示例：allowed-tools: Bash(git:*) Bash(jq:*) Read

Markdown正文规范

前端元数据之后的Markdown正文，就是Agent执行任务的具体指令，没有固定格式，但建议包含以下内容，让Agent更易执行：

- 分步指令：把任务拆分成一步一步的操作，清晰明了。

- 输入和输出示例：给出具体的输入例子和对应的输出结果，帮助Agent理解。

- 常见边界情况：说明遇到异常情况（比如文件不存在、格式错误）时该如何处理。

注意：Agent激活Skill后，会加载整个SKILL.md文件。如果文件太长，建议把详细内容拆分到references/目录下，按需加载。

可选目录规范

1. scripts/目录

里面放Agent可以运行的可执行代码，编写脚本时要注意：

- 要么自包含，要么清楚说明依赖的软件或库（比如需要安装哪些Python包）。

- 包含有用的错误消息，比如文件找不到时，提示“无法找到指定文件，请检查路径是否正确”。

- 能优雅处理边界情况，比如输入错误时不崩溃，而是给出提示。

- 支持的语言看Agent的实现，常见的有Python、Bash、JavaScript。

2. references/目录

里面放Agent需要时可以读取的额外文档，建议每个文件聚焦一个内容，方便按需加载，常见的有：

- REFERENCE.md：详细的技术参考，比如复杂的操作说明。

- FORMS.md：表单模板或结构化数据格式。

- 领域特定文件：比如finance.md（金融相关）、legal.md（法律相关）。

3. assets/目录

里面放静态资源，比如文档模板、图表图片、查找表等，供Agent调用。

渐进式披露规范

Skills的结构要符合“渐进式披露”原则，这样能减少Agent的上下文占用，提高运行速度：

- 元数据（约100个tokens）：所有Skill的name和description，在Agent启动时加载。

- 指令（建议不超过5000个tokens）：完整的SKILL.md正文，在Skill被激活时加载。

- 资源（按需加载）：scripts/、references/、assets/里的文件，只有Agent需要时才加载。

建议把SKILL.md文件控制在500行以内，详细的参考内容移到单独的文件中。

文件引用规范

在SKILL.md中引用其他文件时，要用从Skill根目录开始的相对路径，不要用绝对路径，示例如下：

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

Run the extraction script: scripts/extract.py

注意：文件引用最好控制在距SKILL.md一层深度以内，不要嵌套太深（比如references/docs/guide.md），避免Agent无法找到文件。

Skill验证方法

创建完Skill后，可以用skills-ref参考库来验证，确保符合所有规范。这个库是官方推荐的，使用方法很简单：

1. 先下载参考库：https://github.com/agentskills/agentskills/tree/main/skills-ref

2. 运行验证命令（在终端输入）：

skills-ref validate ./my-skill

这个命令会检查SKILL.md的前端元数据是否有效，以及是否遵循所有命名约定，有错误会及时提示。

第三章：将Skills集成到你的Agent中

这一章讲如何把Skills添加到你的AI Agent或开发工具中，主要有两种集成方式，适合不同的Agent类型，步骤清晰，新手也能快速上手。

两种主要集成方式

1. 基于文件系统的Agent

这种Agent在计算机环境（比如bash/unix）中运行，是最强大的集成方式。当模型发出shell命令（比如cat /path/to/my-skill/SKILL.md）时，Skill就会被激活，捆绑的资源也能通过shell命令访问。

优点：功能强大，能直接调用本地脚本和资源；缺点：需要Agent有访问文件系统的权限。

2. 基于工具的Agent

这种Agent没有专用的计算机环境，需要开发者实现专门的工具，让模型能触发Skills并访问捆绑的资产。具体的工具实现由开发者决定，比如通过api调用Skill的指令。

优点：不需要文件系统权限，兼容性强；缺点：功能相对有限，无法直接运行本地脚本。

集成核心步骤

一个兼容Skills的Agent，不管用哪种集成方式，都需要完成以下5个核心步骤：

1. 发现Skill：扫描配置的目录，找到所有包含SKILL.md文件的文件夹（也就是有效的Skills）。

2. 加载元数据：Agent启动时，只解析每个SKILL.md文件的前端元数据（name和description），这样能减少初始的上下文使用量，让Agent启动更快。

3. 匹配任务：把用户的任务和已加载的Skill元数据进行匹配，判断哪个Skill适合完成当前任务。

4. 激活Skill：找到匹配的Skill后，加载这个Skill的完整SKILL.md指令，注入到Agent的上下文里。

5. 执行任务：Agent按照SKILL.md的指令操作，需要时加载参考文件、执行脚本或访问资产。

关键步骤详解

1. Skill发现

Agent需要配置一个或多个目录，定期扫描这些目录，查找所有包含SKILL.md文件的文件夹。只要文件夹里有SKILL.md，就认定为一个有效的Skill，不管是否包含其他可选目录。

2. 加载元数据

加载元数据时，只需要解析SKILL.md的前端元数据，不需要加载整个文件。下面是一个简单的Python函数示例，用于解析元数据（可直接复用）：

def parseMetadata(skillPath):
    # 读取SKILL.md文件内容
    content = readFile(skillPath + "/SKILL.md")
    # 提取YAML前端元数据（需要安装pyyaml库）
    frontmatter = extractYAMLFrontmatter(content)
    
    # 返回元数据字典
    return {
        "name": frontmatter["name"],
        "description": frontmatter["description"],
        "path": skillPath
    }

注：extractYAMLFrontmatter函数需要自己实现，或使用pyyaml库解析YAML内容，核心是提取name和description字段。

3. 元数据注入上下文

解析完元数据后，需要把这些信息注入到Agent的系统提示中，让模型知道当前有哪些Skills可用。不同平台的注入格式不同，以Claude模型为例，推荐使用XML格式，示例如下：

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

说明：基于文件系统的Agent，需要包含location字段（SKILL.md的绝对路径）；基于工具的Agent，可以省略location字段。

注意：元数据要简洁，每个Skill的元数据建议控制在50-100个tokens，避免占用过多上下文。

安全考虑

如果集成的是基于文件系统的Agent，执行脚本时会有安全风险，一定要做好以下4点防护：

1. 沙箱化：在隔离的环境中运行脚本，不让脚本访问Agent的核心资源，防止恶意脚本破坏系统。

2. 白名单：只执行来自受信任来源的Skill脚本，禁止运行未知或不可信的脚本。

3. 确认机制：在运行潜在危险的操作（比如删除文件、修改系统配置）前，先询问用户，得到确认后再执行。

4. 日志记录：记录所有脚本的执行情况，包括执行时间、脚本路径、操作内容，方便后续审计和排查问题。

参考实现

如果不知道如何实现集成，可以参考skills-ref库，这个库提供了处理Skills的Python工具和命令行工具，是官方推荐的参考实现。

库的地址：https://github.com/agentskills/agentskills/tree/main/skills-ref

常用命令（可直接在终端运行）：

1. 验证Skill目录是否符合规范：

skills-ref validate <path>

2. 生成Agent提示所需的<available_skills> XML：

skills-ref to-prompt <path>...

你也可以查看这个库的源代码，参考它的实现逻辑，快速完成自己Agent的Skills集成。

总结

Agent Skills是让AI Agent完成特定任务的核心组件，它的结构简单、可扩展、可移植，只要遵循本文的规范，就能创建出兼容不同Agent的Skill。集成时，根据自己的Agent类型选择合适的集成方式，做好安全防护，就能让Agent的功能更强大、更实用。

本文涵盖了Skills的概念、规范和集成方法，内容通俗易懂，适合新手入门和开发者参考。如果在使用过程中遇到问题，可以参考skills-ref官方库，或留言咨询。

本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！

链接: https://fly63.com/article/detial/13399