skills 简单介绍
2026-03-25 23:47:41 # LLM #LLM #Anthropic

写在前面：

本文章是关于 Anthropic 公司开源标准 Skills 的部分学习笔记。碍于本人学识有限，部分叙述难免存在纰漏，请读者注意甄别。

参考文档：

什么是 Skills

Agent Skills（技能） 是一种轻量级、开放格式，用于为 AI Agent 扩展能力，使其具备特定领域的知识和工作流程。

简单来说，Agent Skills 就是一种“带目录的说明书”。是一种渐进式披露提示词的机制。

从本质上讲，一个 Skill 就是一个文件夹，其中包含一个 SKILL.md 文件。

这个文件包含：

  • 元数据（Metadata，必定加载，至少包括 name 和 description，可类比为目录）
  • 操作指令（Instruction，按需加载，告诉 Agent 如何完成某个任务，可类比为正文）

此外，一个 Skill 还可以包含（按需加载，可类比为附录）：

  • 脚本（scripts）
  • 参考资料（references）
  • 模板或资源（assets）

示例结构：

1
2
3
4
5
my-skill/
├── SKILL.md          # 必需：说明 + 元数据
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
└── assets/           # 可选：模板、资源

使用 Agent Skills 的时候，会先把元数据（目录）加载进提示词，然后根据需要，再决定是否需要渐进式地加载指令（正文）和资源（附录）。使用这种机制可以大幅降低 Token/上下文窗口 的消耗和 Prompt 的复杂程度。

Skills 的工作方式

Skills 使用一种叫做 “渐进式披露（progressive disclosure）” 的机制来优化上下文：

1. Discovery（发现阶段）

Agent 启动时：

  • 只加载每个 Skill 的 name + description
  • 用于判断这个 Skill 是否可能有用

类似：只加载索引，不加载全文

2. Activation（激活阶段）

当任务匹配 Skill 描述时：

  • Agent 才会读取完整的 SKILL.md

类似：命中后再加载详细说明

3. Execution（执行阶段）

Agent 在执行阶段：

  • 按 SKILL.md 的步骤执行
  • 可以加载引用文件/执行脚本

类似：运行 playbook / SOP（标准操作流程）

这个机制的核心好处：让 Agent 既轻量（快）又有能力（强）

SKILL.md 文件

每个 Skill 都必须包含一个 SKILL.md 文件，结构如下：

元数据

1
2
3
4
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

必须包含：

  • name：技能标识
  • description：什么时候用这个技能

Markdown 内容（自由格式）

1
2
3
4
5
6
7
8
9
10
# PDF Processing

## When to use this skill
当用户需要处理 PDF 文件时使用...

## How to extract text
1. 使用 pdfplumber 提取文本...

## How to fill forms
...

这里本质就是：写给 AI 的操作手册

这种设计的优势：

  1. 自解释（Self-documenting）：看 SKILL.md 就能理解这个 Skill 做什么；易审计、易维护。类似技术设计文档 / API说明文档。
  2. 可扩展（Extensible）：Skill 可以从简单到复杂，纯文本指令、脚本、模板都可以。
  3. 可移植（Portable）：因为 Skill 的本质是文件，可以使用 Git 管理、版本控制、共享复用等。

Skills 规范说明

目录结构

一个 Skill 至少是一个包含 SKILL.md 的目录：

1
2
3
4
5
6
skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：文档
├── assets/           # 可选：模板、资源
└── ...               # 其他文件

SKILL.md 格式

SKILL.md 必须包含：

YAML frontmatter + Markdown 内容

元数据

字段 必需 说明
name ✅ 技能名
description ✅ 描述用途
license ❌ 许可证
compatibility ❌ 运行环境要求
metadata ❌ 自定义字段
allowed-tools ❌ 允许调用的工具

例如：

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: gdai
  version: "1.0"
---

其中，标准对部分字段做出了规范：

  1. name 字段：

    • 长度：1～64 字符
    • 只能：小写字母 + 数字 + -，不能以 - 开头或结尾或连续 --
    • 必须与目录名一致
    1
    2
    3
    name: pdf-processing	# ✅
    ---
    name: PDF-Processing	# ❌ 大写不允许

  2. description 字段：（这是 Agent 的“路由规则”）

    • 长度：1～1024 字符
    • 必须描述这个 Skills 要做什么（What），以及什么时候用（When）
    1
    2
    3
    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.	# ❌ 差例子

  3. license（可选）：

    说明许可证相关信息。

    1
    license: Proprietary. LICENSE.txt has complete terms

  4. compatibility（可选）:

    说明运行环境要求。

    1
    compatibility: Requires Python 3.14+ and uv

  5. metadata（可选）：

    任意 key-value：

    1
    2
    3
    metadata:
      author: gdai
      version: "1.0"

  6. allowed-tools（实验特性）：

    用于允许/限制 Agent 可调用工具。

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

正文内容（Markdown）

没有格式限制，但建议包含：

  • 步骤说明
  • 输入输出示例
  • 边界情况

scripts/ 目录

包含 Agent 可以运行的代码/脚本。scripts 应该：

  • 是自包含（self-contained）或者明确的文档应用（document dependencies）；
  • 包含有用的错误信息
  • 完善的边界处理情况

语言取决于 Agent 可以实现的语言，通常为 bash、python、javascript 等

references/ 目录

应当包含，当 Agent 需要时，一些额外补充的文档。包括：

  • REFERENCE.md：“详细技术说明书”，用于按需加载的补充知识文件
  • FORMS.md：一些表格或者格式化数据的模版。
  • 一些领域给规定的文档，例如 finance.md、legal.md 等

assets/ 目录

包含一些静态资源，例如：

  • Templates 模版文件：文件模版、配置模版；
  • Images 图片文件
  • Datas 数据文件：查找表（look-up table）或 schemas 等

渐进式披露

Skill 设计要考虑上下文优化：

层级 内容 何时加载 Tokens
Metadata name + description 启动时 ~100 tokens
Instructions SKILL.md 激活时 < 5000 tokens recommended
Resources scripts / references 按需 as needed

建议：SKILL.md的长度应该小于 500 行，并且应该将复杂内容拆分到不同的文件中，通过引用渐进式的加载。

文件的引用：当在 SKILL.md 文件（根）中引用其他文件时，需要使用相对路径。应该确保引用文件与 SKILL.md 的层级，避免出现嵌套/循环引用的情况。

1
2
3
4
See [the reference guide](references/REFERENCE.md)

Run:
scripts/extract.py

校验

可以使用 skills-ref 库（点击跳转）来检查我们的 Skill 文件是否合规，SKILL.md 元数据是否有效，并遵循所有命名规范。

1
skills-ref validate ./my-skill
上一页
2026-03-25 23:47:41 # LLM #LLM #Anthropic