## 引言随着人工智能技术的飞速发展，大型语言模型（LLMs）在理解和生成人类语言方面展现出惊人的能力。然而，为了让这些模型能够更准确、高效地执行特定任务，并与外部环境进行交互，Anthropic 提出了 **Agent Skills**（代理技能）的概念。本文将深入探讨 Anthropic Claude Code Skills，详细阐述其定义、作用、编写规范以及如何在代理中集成和使用这些技能，并完整翻译 agentskills.io 网站中的相关章节内容。 ## 什么是 Skills？根据 Anthropic 的定义，**Skills** 是一系列指令、脚本和资源的集合，以文件夹的形式组织，Claude 等代理可以动态加载这些集合，从而提高在专业任务上的表现。Skills 的核心作用在于教会 Claude 如何以可重复的方式完成特定任务，例如根据公司品牌指南创建文档、使用组织特定工作流分析数据，或者自动化个人任务 [^1]。 ### Skills 的核心组成部分每个 Skill 都由一个必需的 `SKILL.md` 文件和可选的捆绑资源组成 [^2] [^5]： ```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 时，遵循以下核心原则至关重要 [^5]： * **简洁是关键 (Concise is Key)**：上下文窗口是公共资源。Skills 与 Claude 所需的其他内容共享上下文窗口，包括系统提示词、对话历史、其他 Skills 的元数据以及用户的实际请求。因此，只添加 Claude 尚未拥有的上下文，并质疑每一条信息是否值得其消耗的 Token 成本。优先使用简洁的示例，而非冗长的解释。 * **设置适当的自由度 (Set Appropriate Degrees of Freedom)**：根据任务的脆弱性和多变性匹配特异性水平。将 Claude 想象成在探索一条路径：带有悬崖的窄桥需要特定的护栏（低自由度），而开阔的田野则允许许多路线（高自由度）。 * **高自由度（基于文本的指令）**：当多种方法都有效、决策取决于上下文或启发式方法指导方法时使用。 * **中等自由度（带参数的伪代码或脚本）**：当存在首选模式、允许某些变化或配置影响行为时使用。 * **低自由度（特定脚本，极少参数）**：当操作脆弱且易出错、一致性至关重要或必须遵循特定顺序时使用。 ### Skills 的工作原理：渐进式披露 (Progressive Disclosure) Skills 采用**渐进式披露**的机制来高效管理上下文，确保代理在需要时才加载相关信息，从而保持运行速度 [^2] [^5]。这种机制通过三级加载系统实现： 1. **元数据 (Metadata)**：`name` 和 `description` 字段在所有 Skill 启动时加载，始终在上下文中（约 100 字）。这足以让代理判断何时可能需要该 Skill。 2. **`SKILL.md` 正文 (Body Content)**：当任务与某个 Skill 的描述匹配时，代理会将完整的 `SKILL.md` 指令加载到上下文中（<5k 字）。 3. **捆绑资源 (Bundled Resources)**：`scripts/`、`references/` 或 `assets/` 中的文件仅在需要时加载，根据 Claude 的需要进行（无限制，因为脚本可以在不读入上下文窗口的情况下执行）。代理遵循指令执行任务，并根据需要选择性地加载引用的文件或执行捆绑的代码。 #### 渐进式披露模式为了高效利用上下文，建议将 `SKILL.md` 正文保持在 500 行以内。当接近此限制时，应将内容拆分为独立文件。在 `SKILL.md` 中引用这些文件，并清晰描述何时阅读它们，以确保技能的阅读者知道它们的存在以及何时使用 [^5]。 **关键原则**：当一个 Skill 支持多种变体、框架或选项时，在 `SKILL.md` 中仅保留核心工作流和选择指南。将特定变体的细节（模式、示例、配置）移至单独的参考文件中 [^5]。 * **模式 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` 文件以其简洁的格式带来了多项关键优势 [^2]： * **自文档化 (Self-documenting)**：Skill 的作者或用户可以通过阅读 `SKILL.md` 文件来理解其功能，这使得 Skill 易于审计和改进。 * **可扩展性 (Extensible)**：Skill 的复杂性可以从纯文本指令扩展到包含可执行代码、资产和模板。 * **可移植性 (Portable)**：Skill 仅仅是文件，因此易于编辑、版本控制和共享。 ## Skills 的作用 Agent Skills 旨在解决代理在执行实际工作时常常缺乏必要上下文的问题，从而使代理能够更可靠地完成任务。它为代理提供了按需加载的程序性知识以及公司、团队和用户特定的上下文 [^1]。 ### 为什么需要 Agent Skills？ * **对于技能作者 (For skill authors)**：可以一次性构建能力，并将其部署到多个代理产品中。 * **对于兼容代理 (For compatible agents)**：支持 Skills 的代理允许最终用户即时赋予代理新的能力。 * **对于团队和企业 (For teams and enterprises)**：可以将组织知识封装在可移植、版本控制的软件包中。 ### Agent Skills 能够实现什么？ Agent Skills 能够赋能代理实现以下功能 [^1]： * **领域专业知识 (Domain expertise)**：将专业知识打包成可重用的指令，例如从法律审查流程到数据分析管道。 * **新能力 (New capabilities)**：赋予代理新的能力，例如创建演示文稿、构建 MCP 服务器、分析数据集等。 * **可重复工作流 (Repeatable workflows)**：将多步骤任务转化为一致且可审计的工作流。 * **互操作性 (Interoperability)**：在不同的兼容 Skills 的代理产品中重用相同的 Skill。 ## 编写规范 (Specification) Agent Skills 的规范定义了 Skill 的目录结构和 `SKILL.md` 文件的格式 [^3]。 ### 目录结构一个 Skill 至少是一个包含 `SKILL.md` 文件的目录 [^3] [^5]： ```bash skill-name/ └── SKILL.md # 必需 ``` 您可以选择性地包含 `scripts/`、`references/` 和 `assets/` 等附加目录来支持您的 Skill。 #### 技能中不应包含的内容 Skills 应仅包含直接支持其功能的必要文件。**不要**创建无关的文档或辅助文件，例如 `README.md`、`INSTALLATION_GUIDE.md`、`QUICK_REFERENCE.md`、`CHANGELOG.md` 等。Skills 应仅包含 AI 智能体完成手头工作所需的信息，不应包含关于创建过程、设置和测试程序、面向用户的文档等辅助上下文。创建额外的文档文件只会增加混乱和困惑 [^5]。 ### `SKILL.md` 格式 `SKILL.md` 文件必须包含 YAML 前置内容，后跟 Markdown 内容 [^3]。 #### 前置内容 (Frontmatter) (必需) 前置内容是 YAML 格式，至少包含 `name` 和 `description` 字段 [^3] [^5]： ```yaml --- name: skill-name description: A description of what this skill does and when to use it. --- ``` 这些是 Claude 阅读以确定何时使用该技能的唯一字段，因此清晰、全面地描述技能是什么以及何时应使用它非常重要 [^5]。可选字段包括 `license`、`compatibility`、`metadata` 和 `allowed-tools` [^3]： ```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 在决定是否使用该技能时拥有的唯一信息。一个好的描述必须清晰说明技能**做什么**、**何时**使用它（以及何时不使用它），并提到它提供的关键**工具或资源** [^5]。 * **糟糕的描述示例**：“一个用于处理 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 的指令。没有格式限制，可以编写任何有助于代理有效执行任务的内容。建议包含以下部分 [^3] [^5]： * 分步说明 * 输入和输出示例 * 常见边缘情况请注意，一旦代理决定激活某个 Skill，它将加载整个 `SKILL.md` 文件。因此，建议将较长的 `SKILL.md` 内容拆分到引用的文件中。 #### 使用示例，而非解释 Claude 从示例中学习的效果比从抽象指令中学习更好。与其提供冗长的解释，不如使用代码示例来清晰地展示操作 [^5]。 **与其说**：“创建图表时，确保标题具有描述性，坐标轴有标签，且颜色是易于辨认的。” **不如使用**： ```md ## 示例：易于辨认的图表 import matplotlib.pyplot as plt # 使用描述性的标题和标签 plt.title("月度收入增长 (2023年第三季度)") plt.xlabel("月份") plt.ylabel("收入 (美元)") # 使用易于辨认的调色板 colors = ['#0072B2', '#009E73', '#D55E00'] ``` #### 处理大文件当 Skill 包含大型参考文件（>10k 字）时，Claude 可能难以找到特定信息。在这种情况下，在 `SKILL.md` 中提供 `grep` 搜索模式，以帮助 Claude 定位相关部分 [^5]。 **示例**： ```md ## 搜索 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 等）。脚本应 [^3] [^5]： * 自包含或清晰地记录依赖项。 * 包含有用的错误消息。 * 优雅地处理边缘情况。 * 支持的语言取决于代理实现，常见选项包括 Python、Bash 和 JavaScript。 * **何时包含**：当相同的代码被反复重写或需要确定性可靠性时。 * **优点**：Token 效率高、确定性强，可以在不加载到上下文窗口的情况下执行。 * **注意**：Claude 可能仍需要读取脚本以进行补丁或针对特定环境的调整。 * **`references/`**：包含代理在需要时可以阅读的额外文档和参考材料，旨在根据需要加载到上下文中以告知 Claude 的过程和思考 [^3] [^5]： * `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 生成的输出中的静态资源 [^3] [^5]： * 模板（文档模板、配置模板）。 * 图像（图表、示例）。 * 数据文件（查找表、模式）。 * **何时包含**：当技能需要将在最终输出中使用的文件时。 * **用例**：模板、图像、图标、样板代码、字体、被复制或修改的示例文档。 * **优点**：将输出资源与文档分离，使 Claude 能够在不加载文件到上下文的情况下使用它们。 ### 渐进式披露 (Progressive Disclosure) Skills 的结构应旨在高效利用上下文 [^3]： 1. **元数据** (Metadata) (~100 tokens)：`name` 和 `description` 字段在所有 Skill 启动时加载。 2. **指令** (Instructions) (< 5000 tokens 推荐)：当 Skill 被激活时，加载完整的 `SKILL.md` 主体。 3. **资源** (Resources) (按需加载)：`scripts/`、`references/` 或 `assets/` 中的文件仅在需要时加载。建议将主要的 `SKILL.md` 文件保持在 500 行以下。将详细的参考材料移至单独的文件中。 ### 文件引用在 Skill 中引用其他文件时，请使用相对于 Skill 根目录的相对路径 [^3]： ``` See [the reference guide](references/REFERENCE.md) for details. Run the extraction script: scripts/extract.py ``` 文件引用应保持在 `SKILL.md` 文件的一级深度。避免深度嵌套的引用链。 ### 验证可以使用 `skills-ref` 参考库来验证您的 Skill [^3]： ```bash skills-ref validate ./my-skill ``` 这将检查您的 `SKILL.md` 前置内容是否有效并遵循所有命名约定。 ## 集成 Skills (Integrate skills into your agent) 本指南解释了如何向 AI 代理或开发工具添加 Skills 支持 [^4]。 ### 集成方法集成 Skills 的两种主要方法是 [^4]： * **基于文件系统的代理 (Filesystem-based agents)**：在计算机环境（bash/unix）中运行，代表了功能最强大的选项。当模型发出 `cat /path/to/my-skill/SKILL.md` 等 shell 命令时，Skills 会被激活。捆绑的资源通过 shell 命令访问。 * **基于工具的代理 (Tool-based agents)**：在没有专用计算机环境的情况下运行。它们实现工具，允许模型触发 Skills 并访问捆绑的资产。具体的工具实现由开发人员决定。 ### 集成概述一个兼容 Skills 的代理需要 [^4]： 1. **发现 (Discover)**：在配置的目录中发现 Skills。 2. **加载元数据 (Load metadata)**：在启动时加载元数据（名称和描述）。 3. **匹配 (Match)**：将用户任务与相关 Skills 匹配。 4. **激活 (Activate)**：通过加载完整指令来激活 Skills。 5. **执行 (Execute)**：根据需要执行脚本和访问资源。 ### 技能发现 Skills 是包含 `SKILL.md` 文件的文件夹。您的代理应扫描配置的目录以查找有效的 Skills [^4]。 ### 加载元数据和解析前置内容在启动时，仅解析每个 `SKILL.md` 文件的前置内容。这可以保持初始上下文使用量较低 [^4]： ```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 [^4]： ```xml pdf-processing Extracts text and tables from PDF files, fills forms, merges documents. /path/to/skills/pdf-processing/SKILL.md data-analysis Analyzes datasets, generates charts, and creates summary reports. /path/to/skills/data-analysis/SKILL.md ``` 对于基于文件系统的代理，请包含 `location` 字段，其中包含 `SKILL.md` 文件的绝对路径。对于基于工具的代理，可以省略 `location`。保持元数据简洁。每个 Skill 大约会向上下文添加 50-100 个 token。 ### 安全考虑脚本执行会带来安全风险。请考虑以下几点 [^4]： * **沙盒化 (Sandboxing)**：在隔离环境中运行脚本。 * **白名单 (Allowlisting)**：仅执行来自受信任 Skills 的脚本。 * **确认 (Confirmation)**：在运行潜在危险操作之前征求用户同意。 * **日志记录 (Logging)**：记录所有脚本执行以进行审计。 ### 参考实现 `skills-ref` 库提供了用于处理 Skills 的 Python 工具和命令行界面。例如 [^4]： * **验证 Skill 目录**： ```bash skills-ref validate ``` * **为代理提示生成 `` XML**： ```bash skills-ref to-prompt ... ``` 可以使用库源代码作为参考实现。 ## Claude Code 中的应用 Anthropic 的 GitHub 仓库提供了在 Claude Code、Claude.ai 和 Claude API 中使用 Skills 的指南 [^1]。 ### Claude Code 您可以通过在 Claude Code 中运行以下命令，将此仓库注册为 Claude Code 插件市场 [^1]： ```bash /plugin marketplace add anthropics/skills ``` 然后，要安装特定的技能集： 1. 选择 `Browse and install plugins`。 2. 选择 `anthropic-agent-skills`。 3. 选择 `document-skills` 或 `example-skills`。 4. 选择 `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`" 的操作。 ### Claude.ai 这些示例 Skills 都已在 Claude.ai 的付费计划中提供 [^1]。要使用此仓库中的任何 Skill 或上传自定义 Skill，请遵循 [Using skills in Claude](https://github.com/anthropics/skills#using-skills-in-claude) 中的说明。 ### Claude API 您可以通过 Claude API 使用 Anthropic 预构建的 Skills 并上传自定义 Skills。有关更多信息，请参阅 [Skills API Quickstart](https://github.com/anthropics/skills#skills-api-quickstart) [^1]。 ## 总结 Anthropic Agent Skills 提供了一种强大而灵活的机制，使大型语言模型能够扩展其能力，更高效、准确地执行复杂任务。通过结构化的 `SKILL.md` 文件、可选的脚本和资源，以及渐进式披露的工作原理，Skills 确保了代理在需要时能够访问到精确的上下文和工具。无论是对于技能作者、代理开发者还是企业用户，Agent Skills 都提供了一个开放且可扩展的框架，以构建和集成更智能、更可靠的 AI 代理。 ## 参考文献 [^1]: [GitHub - anthropics/skills: Public repository for Agent Skills](https://github.com/anthropics/skills) [^2]: [What are skills? - Agent Skills](https://agentskills.io/what-are-skills) [^3]: [Specification - Agent Skills](https://agentskills.io/specification) [^4]: [Integrate skills into your agent - Agent Skills](https://agentskills.io/integrate-skills) [^5]: [SKILL.md](upload/SKILL.md) ## 总结清单为了确保您的 Skill 高效且符合最佳实践，请参考以下清单进行检查 [^5]： * `SKILL.md` 是否简洁且聚焦？ * YAML frontmatter 描述是否清晰且全面？ * 复杂程序是否已移至脚本？ * 详细的参考材料是否已移至独立文件？ * 是否使用了示例而非长篇解释？ * 技能是否遵循渐进式披露原则？ * 是否仅包含必要文件（无 README 等）？

搜索结果: 代码技能