Anthropic Claude Code Skills 深度解析

引言

随着人工智能技术的飞速发展，大型语言模型（LLMs）在理解和生成人类语言方面展现出惊人的能力。然而，为了让这些模型能够更准确、高效地执行特定任务，并与外部环境进行交互，Anthropic 提出了 Agent Skills（代理技能）的概念。本文将深入探讨 Anthropic Claude Code Skills，详细阐述其定义、作用、编写规范以及如何在代理中集成和使用这些技能，并完整翻译 agentskills.io 网站中的相关章节内容。

什么是 Skills？

根据 Anthropic 的定义，Skills 是一系列指令、脚本和资源的集合，以文件夹的形式组织，Claude 等代理可以动态加载这些集合，从而提高在专业任务上的表现。Skills 的核心作用在于教会 Claude 如何以可重复的方式完成特定任务，例如根据公司品牌指南创建文档、使用组织特定工作流分析数据，或者自动化个人任务 ¹。

Skills 的核心组成部分

每个 Skill 都由一个必需的 SKILL.md 文件和可选的捆绑资源组成 ² ³：

text


skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令 (必需)
└── 捆绑资源 (可选)
    ├── scripts/          - 可执行代码 (Python/Bash 等)
    ├── references/       - 旨在根据需要加载到上下文中的文档
    └── assets/           - 输出中使用的文件 (模板、图标、字体等)

其中，SKILL.md 文件是每个 Skill 的核心，它包含 YAML 前置内容（frontmatter）和 Markdown 格式的指令，用于告诉代理如何执行特定任务。可选的 scripts/ 目录可以存放可执行代码，references/ 目录用于存放额外文档，而 assets/ 目录则可以包含模板、图像等静态资源。

核心原则

在编写 Skills 时，遵循以下核心原则至关重要 ³：

简洁是关键 (Concise is Key)：上下文窗口是公共资源。Skills 与 Claude 所需的其他内容共享上下文窗口，包括系统提示词、对话历史、其他 Skills 的元数据以及用户的实际请求。因此，只添加 Claude 尚未拥有的上下文，并质疑每一条信息是否值得其消耗的 Token 成本。优先使用简洁的示例，而非冗长的解释。
设置适当的自由度 (Set Appropriate Degrees of Freedom)：根据任务的脆弱性和多变性匹配特异性水平。将 Claude 想象成在探索一条路径：带有悬崖的窄桥需要特定的护栏（低自由度），而开阔的田野则允许许多路线（高自由度）。
- 高自由度（基于文本的指令）：当多种方法都有效、决策取决于上下文或启发式方法指导方法时使用。
- 中等自由度（带参数的伪代码或脚本）：当存在首选模式、允许某些变化或配置影响行为时使用。
- 低自由度（特定脚本，极少参数）：当操作脆弱且易出错、一致性至关重要或必须遵循特定顺序时使用。

Skills 的工作原理：渐进式披露 (Progressive Disclosure)

Skills 采用渐进式披露的机制来高效管理上下文，确保代理在需要时才加载相关信息，从而保持运行速度 ² ³。这种机制通过三级加载系统实现：

元数据 (Metadata)：name 和 description 字段在所有 Skill 启动时加载，始终在上下文中（约 100 字）。这足以让代理判断何时可能需要该 Skill。
SKILL.md 正文 (Body Content)：当任务与某个 Skill 的描述匹配时，代理会将完整的 SKILL.md 指令加载到上下文中（<5k 字）。
捆绑资源 (Bundled Resources)：scripts/、references/ 或 assets/ 中的文件仅在需要时加载，根据 Claude 的需要进行（无限制，因为脚本可以在不读入上下文窗口的情况下执行）。代理遵循指令执行任务，并根据需要选择性地加载引用的文件或执行捆绑的代码。

渐进式披露模式

为了高效利用上下文，建议将 SKILL.md 正文保持在 500 行以内。当接近此限制时，应将内容拆分为独立文件。在 SKILL.md 中引用这些文件，并清晰描述何时阅读它们，以确保技能的阅读者知道它们的存在以及何时使用 ³。

关键原则：当一个 Skill 支持多种变体、框架或选项时，在 SKILL.md 中仅保留核心工作流和选择指南。将特定变体的细节（模式、示例、配置）移至单独的参考文件中 ³。

模式 1：带参考的顶层指南：在 SKILL.md 中提供高级指南，并将详细信息链接到参考文件。例如，PDF 处理的高级功能（如表单填写、API 参考、示例）可以链接到 FORMS.md、REFERENCE.md 和 EXAMPLES.md。Claude 仅在用户的请求需要这些特定功能时才加载这些参考文件。
模式 2：选择逻辑：在 SKILL.md 中提供选择不同框架或工具的逻辑，并将每个选项的详细模式链接到单独的参考文件。例如，数据可视化可以根据用户需求链接到 MATPLOTLIB.md、PLOTLY.md 或 LEAFLET.md。Claude 仅根据用户需求加载其选择的框架的参考文件。

`SKILL.md` 文件的优势

SKILL.md 文件以其简洁的格式带来了多项关键优势 ²：

自文档化 (Self-documenting)：Skill 的作者或用户可以通过阅读 SKILL.md 文件来理解其功能，这使得 Skill 易于审计和改进。
可扩展性 (Extensible)：Skill 的复杂性可以从纯文本指令扩展到包含可执行代码、资产和模板。
可移植性 (Portable)：Skill 仅仅是文件，因此易于编辑、版本控制和共享。

Skills 的作用

Agent Skills 旨在解决代理在执行实际工作时常常缺乏必要上下文的问题，从而使代理能够更可靠地完成任务。它为代理提供了按需加载的程序性知识以及公司、团队和用户特定的上下文 ¹。

为什么需要 Agent Skills？

对于技能作者 (For skill authors)：可以一次性构建能力，并将其部署到多个代理产品中。
对于兼容代理 (For compatible agents)：支持 Skills 的代理允许最终用户即时赋予代理新的能力。
对于团队和企业 (For teams and enterprises)：可以将组织知识封装在可移植、版本控制的软件包中。

Agent Skills 能够实现什么？

Agent Skills 能够赋能代理实现以下功能 ¹：

领域专业知识 (Domain expertise)：将专业知识打包成可重用的指令，例如从法律审查流程到数据分析管道。
新能力 (New capabilities)：赋予代理新的能力，例如创建演示文稿、构建 MCP 服务器、分析数据集等。
可重复工作流 (Repeatable workflows)：将多步骤任务转化为一致且可审计的工作流。
互操作性 (Interoperability)：在不同的兼容 Skills 的代理产品中重用相同的 Skill。

编写规范 (Specification)

Agent Skills 的规范定义了 Skill 的目录结构和 SKILL.md 文件的格式 ⁴。

目录结构

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

bash


skill-name/
└── SKILL.md          # 必需

您可以选择性地包含 scripts/、references/ 和 assets/ 等附加目录来支持您的 Skill。

技能中不应包含的内容

Skills 应仅包含直接支持其功能的必要文件。不要创建无关的文档或辅助文件，例如 README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md 等。Skills 应仅包含 AI 智能体完成手头工作所需的信息，不应包含关于创建过程、设置和测试程序、面向用户的文档等辅助上下文。创建额外的文档文件只会增加混乱和困惑 ³。

`SKILL.md` 格式

SKILL.md 文件必须包含 YAML 前置内容，后跟 Markdown 内容 ⁴。

前置内容 (Frontmatter) (必需)

前置内容是 YAML 格式，至少包含 name 和 description 字段 ⁴ ³：

yaml


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

这些是 Claude 阅读以确定何时使用该技能的唯一字段，因此清晰、全面地描述技能是什么以及何时应使用它非常重要 ³。

可选字段包括 license、compatibility、metadata 和 allowed-tools ⁴：

yaml


---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

以下是各个字段的详细要求：

name 字段：
- 必须是 1-64 个字符。
- 只能包含 Unicode 小写字母数字字符和连字符 (a-z 和 -)。
- 不能以 - 开头或结尾。
- 不能包含连续的连字符 (--)。
- 必须与父目录名称匹配。
- 有效示例：pdf-processing, data-analysis, code-review。
- 无效示例：PDF-Processing (不允许大写), -pdf (不能以连字符开头), pdf--processing (不允许连续连字符)。
description 字段：
- 必须是 1-1024 个字符。
- 应描述 Skill 的功能以及何时使用它。
- 应包含有助于代理识别相关任务的特定关键词。
- 良好示例：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.
编写有效的描述：YAML frontmatter 中的 description 是技能最关键的部分。它是 Claude 在决定是否使用该技能时拥有的唯一信息。一个好的描述必须清晰说明技能做什么、何时使用它（以及何时不使用它），并提到它提供的关键工具或资源 ³。
- 糟糕的描述示例：“一个用于处理 PDF 文件的技能。”（太模糊）
- 好的描述示例：“使用 pdfplumber 从 PDF 文件中提取文本、表格和元数据。当用户上传 PDF 并需要分析其内容或将其转换为另一种格式时使用此技能。不要用于简单的文件预览。”
license 字段 (可选)：
- 指定应用于 Skill 的许可证。
- 建议保持简短（可以是许可证名称或捆绑许可证文件的名称）。
- 示例：Proprietary. LICENSE.txt has complete terms。
compatibility 字段 (可选)：
- 如果提供，必须是 1-500 个字符。
- 仅当 Skill 具有特定环境要求时才应包含。
- 可以指示预期的产品、所需的系统包、网络访问需求等。
- 示例：Designed for Claude Code (or similar products), Requires git, docker, jq, and access to the internet。
- 大多数 Skill 不需要 compatibility 字段。
metadata 字段 (可选)：
- 从字符串键到字符串值的映射。
- 客户端可以使用它来存储 Agent Skills 规范未定义的额外属性。
- 建议使键名具有合理的唯一性，以避免意外冲突。
- 示例：
  yaml
  metadata: author: example-org version: "1.0"
allowed-tools 字段 (可选)：
- 一个以空格分隔的预批准运行工具列表。
- 实验性功能，对该字段的支持可能因代理实现而异。
- 示例：Bash(git:*) Bash(jq:*) Read。
name 字段：
- 必须是 1-64 个字符。
- 只能包含 Unicode 小写字母数字字符和连字符 (a-z 和 -)。
- 不能以 - 开头或结尾。
- 不能包含连续的连字符 (--)。
- 必须与父目录名称匹配。
- 有效示例：pdf-processing, data-analysis, code-review。
- 无效示例：PDF-Processing (不允许大写), -pdf (不能以连字符开头), pdf--processing (不允许连续连字符)。
description 字段：
- 必须是 1-1024 个字符。
- 应描述 Skill 的功能以及何时使用它。
- 应包含有助于代理识别相关任务的特定关键词。
- 良好示例：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.
license 字段 (可选)：
- 指定应用于 Skill 的许可证。
- 建议保持简短（可以是许可证名称或捆绑许可证文件的名称）。
- 示例：Proprietary. LICENSE.txt has complete terms。
compatibility 字段 (可选)：
- 如果提供，必须是 1-500 个字符。
- 仅当 Skill 具有特定环境要求时才应包含。
- 可以指示预期的产品、所需的系统包、网络访问需求等。
- 示例：Designed for Claude Code (or similar products), Requires git, docker, jq, and access to the internet。
- 大多数 Skill 不需要 compatibility 字段。
metadata 字段 (可选)：
- 从字符串键到字符串值的映射。
- 客户端可以使用它来存储 Agent Skills 规范未定义的额外属性。
- 建议使键名具有合理的唯一性，以避免意外冲突。
- 示例：
  yaml
  metadata: author: example-org version: "1.0"
allowed-tools 字段 (可选)：
- 一个以空格分隔的预批准运行工具列表。
- 实验性功能，对该字段的支持可能因代理实现而异。
- 示例：Bash(git:*) Bash(jq:*) Read。

主体内容 (Body Content)

前置内容之后的 Markdown 主体包含 Skill 的指令。没有格式限制，可以编写任何有助于代理有效执行任务的内容。建议包含以下部分 ⁴ ³：

分步说明
输入和输出示例
常见边缘情况

请注意，一旦代理决定激活某个 Skill，它将加载整个 SKILL.md 文件。因此，建议将较长的 SKILL.md 内容拆分到引用的文件中。

使用示例，而非解释

Claude 从示例中学习的效果比从抽象指令中学习更好。与其提供冗长的解释，不如使用代码示例来清晰地展示操作 ³。

与其说：“创建图表时，确保标题具有描述性，坐标轴有标签，且颜色是易于辨认的。”

不如使用：


## 示例：易于辨认的图表

import matplotlib.pyplot as plt

# 使用描述性的标题和标签
plt.title("月度收入增长 (2023年第三季度)")
plt.xlabel("月份")
plt.ylabel("收入 (美元)")

# 使用易于辨认的调色板
colors = ['#0072B2', '#009E73', '#D55E00']

处理大文件

当 Skill 包含大型参考文件（>10k 字）时，Claude 可能难以找到特定信息。在这种情况下，在 SKILL.md 中提供 grep 搜索模式，以帮助 Claude 定位相关部分 ³。

示例：


## 搜索 API 文档

API 文档 ([API_DOCS.md](API_DOCS.md)) 很大。使用 grep 查找特定端点：
- `grep -i "GET /users" references/api_docs.md`
- `grep -i "POST /orders" references/api_docs.md`

。

可选目录

scripts/：包含代理可以运行的可执行代码，用于需要确定性可靠性或会被重复重写的任务（Python/Bash 等）。脚本应 ⁴ ³：
- 自包含或清晰地记录依赖项。
- 包含有用的错误消息。
- 优雅地处理边缘情况。
- 支持的语言取决于代理实现，常见选项包括 Python、Bash 和 JavaScript。
- 何时包含：当相同的代码被反复重写或需要确定性可靠性时。
- 优点：Token 效率高、确定性强，可以在不加载到上下文窗口的情况下执行。
- 注意：Claude 可能仍需要读取脚本以进行补丁或针对特定环境的调整。
references/：包含代理在需要时可以阅读的额外文档和参考材料，旨在根据需要加载到上下文中以告知 Claude 的过程和思考 ⁴ ³：
- REFERENCE.md - 详细技术参考。
- FORMS.md - 表单模板或结构化数据格式。
- 领域特定文件（finance.md, legal.md 等）。
- 何时包含：供 Claude 在工作时参考的文档。
- 用例：数据库模式、API 文档、领域知识、公司政策、详细的工作流指南。
- 优点：保持 SKILL.md 精简，仅在 Claude 确定需要时才加载。
- 最佳实践：如果文件很大（>10k 字），在 SKILL.md 中包含 grep 搜索模式。信息应存在于 SKILL.md 或参考文件中，而不是两者都有。除非确实是技能的核心，否则优先将详细信息放在参考文件中——这可以保持 SKILL.md 精简，同时使信息可被发现且不占用上下文窗口。在 SKILL.md 中仅保留基本的程序指令和工作流指南；将详细的参考材料、模式和示例移至参考文件。
assets/：包含不打算加载到上下文中，而是用于 Claude 生成的输出中的静态资源 ⁴ ³：
- 模板（文档模板、配置模板）。
- 图像（图表、示例）。
- 数据文件（查找表、模式）。
- 何时包含：当技能需要将在最终输出中使用的文件时。
- 用例：模板、图像、图标、样板代码、字体、被复制或修改的示例文档。
- 优点：将输出资源与文档分离，使 Claude 能够在不加载文件到上下文的情况下使用它们。

渐进式披露 (Progressive Disclosure)

Skills 的结构应旨在高效利用上下文 ⁴：

元数据 (Metadata) (~100 tokens)：name 和 description 字段在所有 Skill 启动时加载。
指令 (Instructions) (< 5000 tokens 推荐)：当 Skill 被激活时，加载完整的 SKILL.md 主体。
资源 (Resources) (按需加载)：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 文件的一级深度。避免深度嵌套的引用链。

验证

可以使用 skills-ref 参考库来验证您的 Skill ⁴：

bash


skills-ref validate ./my-skill

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

集成 Skills (Integrate skills into your agent)

本指南解释了如何向 AI 代理或开发工具添加 Skills 支持 ⁵。

集成方法

集成 Skills 的两种主要方法是 ⁵：

基于文件系统的代理 (Filesystem-based agents)：在计算机环境（bash/unix）中运行，代表了功能最强大的选项。当模型发出 cat /path/to/my-skill/SKILL.md 等 shell 命令时，Skills 会被激活。捆绑的资源通过 shell 命令访问。
基于工具的代理 (Tool-based agents)：在没有专用计算机环境的情况下运行。它们实现工具，允许模型触发 Skills 并访问捆绑的资产。具体的工具实现由开发人员决定。

集成概述

一个兼容 Skills 的代理需要 ⁵：

发现 (Discover)：在配置的目录中发现 Skills。
加载元数据 (Load metadata)：在启动时加载元数据（名称和描述）。
匹配 (Match)：将用户任务与相关 Skills 匹配。
激活 (Activate)：通过加载完整指令来激活 Skills。
执行 (Execute)：根据需要执行脚本和访问资源。

技能发现

Skills 是包含 SKILL.md 文件的文件夹。您的代理应扫描配置的目录以查找有效的 Skills ⁵。

加载元数据和解析前置内容

在启动时，仅解析每个 SKILL.md 文件的前置内容。这可以保持初始上下文使用量较低 ⁵：

javascript


function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)

    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

注入上下文

将 Skill 元数据包含在系统提示中，以便模型知道哪些 Skills 可用。请遵循您平台关于系统提示更新的指南。例如，对于 Claude 模型，推荐的格式使用 XML ⁵：

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>

对于基于文件系统的代理，请包含 location 字段，其中包含 SKILL.md 文件的绝对路径。对于基于工具的代理，可以省略 location。保持元数据简洁。每个 Skill 大约会向上下文添加 50-100 个 token。

安全考虑

脚本执行会带来安全风险。请考虑以下几点 ⁵：

沙盒化 (Sandboxing)：在隔离环境中运行脚本。
白名单 (Allowlisting)：仅执行来自受信任 Skills 的脚本。
确认 (Confirmation)：在运行潜在危险操作之前征求用户同意。
日志记录 (Logging)：记录所有脚本执行以进行审计。

参考实现

skills-ref 库提供了用于处理 Skills 的 Python 工具和命令行界面。例如 ⁵：

验证 Skill 目录：
bash
```
skills-ref validate <path>
```
为代理提示生成 <available_skills> XML：
bash
```
skills-ref to-prompt <path>...
```

可以使用库源代码作为参考实现。

Claude Code 中的应用

Anthropic 的 GitHub 仓库提供了在 Claude Code、Claude.ai 和 Claude API 中使用 Skills 的指南 ¹。

Claude Code

您可以通过在 Claude Code 中运行以下命令，将此仓库注册为 Claude Code 插件市场 ¹：

bash


/plugin marketplace add anthropics/skills

然后，要安装特定的技能集：

选择 Browse and install plugins。
选择 anthropic-agent-skills。
选择 document-skills 或 example-skills。
选择 Install now。

或者，可以直接通过以下方式安装任一插件：

bash


/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

安装插件后，您只需提及即可使用该 Skill。例如，如果您从市场安装了 document-skills 插件，您可以要求 Claude Code 执行类似 "Use the PDF skill to extract the form fields from path/to/some-file.pdf" 的操作。