skillshubskillshub

Agent Skills

Agent Skills 是扩展 Claude 功能的模块化能力。每个 Skill 包含指令、元数据和可选资源（脚本、模板），Claude 会在相关时自动使用它们。

为什么要使用 Skills

Skills 是可复用的、基于文件系统的资源，为 Claude 提供特定领域的专业知识：工作流、上下文和最佳实践，将通用 AI 代理转化为专家。与 Prompts（针对一次性任务的会话级指令）不同，Skills 按需加载，无需在多个会话中重复提供相同的指导。

核心优势：

  • 业化 Claude：为特定领域的任务定制能力
  • 减少重复：一次创建，自动使用
  • 组合能力：结合多个 Skills 构建复杂的工作流

如果想深入了解 Agent Skills 的架构和实际应用，请阅读我们的工程博客：Equipping agents for the real world with Agent Skills。

使用 Skills

Anthropic 提供了用于常见文档任务（PowerPoint, Excel, Word, PDF）的预置 Agent Skills，您也可以创建自定义 Skills。它们的工作方式相同。当与您的请求相关时，Claude 会自动使用它们。

预置 Agent Skills 可供 claude.ai 上的所有用户和通过 Claude API 使用。请参阅下方的 用 Skills 部分查看完整列表。

自定义 Skills 让您可以封装领域专长和组织知识。它们可在 Claude 的产品中使用：在 Claude Code 中创建，通过 API 上传，或在 claude.ai 设置中添加。

开始使用：

  • 预置 Agent Skills：查看 快速开始教程 开始在 API 中使用 PowerPoint, Excel, Word 和 PDF skills
  • 自定义 Skills：查看 Agent Skills Cookbook 学习如何创建您自己的 Skills

Skills 如何工作

Skills 利用 Claude 的虚拟机环境提供超越单纯 Prompts 的能力。Claude 在具有文件系统访问权限的虚拟机中运行，允许 Skills 以目录形式存在，包含指令、可执行代码和参考资料，就像您为新团队成员创建的入职指南一样。

这种基于文件系统的架构实现了渐进式披露：Claude 根据需要分阶段加载信息，而不是预先消耗上下文。

三种 Skill 内容类型，级加载

Skills 可以包含三种类型的内容，每种内容在不同时间加载：

第 1 级：元数据（始终加载）

内容类型：指令。Skill 的 YAML frontmatter 提供发现信息：

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

Claude 在启动时加载此元数据并将其包含在系统提示词中。这种轻量级方法意味着您可以安装许多 Skills 而不会产生上下文惩罚；Claude 只知道每个 Skill 的存在以及何时使用它。

第 2 级：指令（触发时加载）

内容类型：指令。SKILL.md 的主体包含程序性知识：工作流、最佳实践和指导：

# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
\```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
   text = pdf.pages[0].extract_text()
\```
For advanced form filling, see [FORMS.md](FORMS.md).

当您请求的内容匹配 Skill 的描述时，Claude 会通过 bash 从文件系统读取 SKILL.md。只有这时，这些内容才会进入上下文窗口。

第 3 级：资源和代码（按需加载）

内容类型：指令、代码和资源。Skills 可以捆绑额外的材料：

pdf-skill/
├── SKILL.md        (main instructions)
├── FORMS.md        (form-filling guide)
├── REFERENCE.md    (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)
  • 指令：额外的 markdown 文件（FORMS.md, REFERENCE.md），包含专门的指导和工作流
  • 代码：可执行脚本（fill_form.py, validate.py），Claude 通过 bash 运行它们；脚本提供确定性的操作而不消耗上下文
  • 资源：参考资料，如数据库模式、API 文档、模板或示例

Claude 仅在被引用时访问这些文件。文件系统模型意味着每种内容类型都有不同的优势：用于灵活指导的指令，用于可靠性的代码，用于事实查找的资源。

渐进式披露确保任何给定时间只有相关内容占据上下文窗口。

Skills 在哪里工作

Skills 可在 Claude 的 agent 产品中使用：

Claude API

Claude API 支持预置 Agent Skills 和自定义 Skills。两者工作原理相同：在 container 参数中指定相关的 skill_id 以及代码执行工具。

前提条件：通过 API 使用 Skills 需要三个 beta headers：

  • code-execution-2025-08-25 - Skills 在代码执行容器中运行
  • skills-2025-10-02 - 启用 Skills 功能
  • files-api-2025-04-14 - 将文件上传/下载到容器所必需

通过引用 skill_id（例如 pptx, xlsx）使用预置 Agent Skills，或通过 Skills API（/v1/skills 端点）创建并上传您自己的 Skills。自定义 Skills 在组织范围内共享。

要了解更多信息，请参阅 在 Claude API 中使用 Skills。

Claude Code

Claude Code 仅支持自定义 Skills。

自定义 Skills：创建包含 SKILL.md 文件的目录作为 Skills。Claude 会自动发现并使用它们。

Claude Code 中的自定义 Skills 基于文件系统，不需要 API 上传。 要了解更多信息，请参阅 在 Claude Code 中使用 Skills。

Claude Agent SDK

Claude Agent SDK 支持基于文件系统配置的自定义 Skills。

自定义 Skills：在 .claude/skills/ 中创建包含 SKILL.md 文件的目录作为 Skills。通过在 allowed_tools 配置中包含 "Skill" 来启用 Skills。

Agent SDK 中的 Skills 随后会在 SDK 运行时自动发现。 要了解更多信息，请参阅 SDK 中的 Agent Skills。

Claude.ai

Claude.ai 支持预置 Agent Skills 和自定义 Skills。

  • 预置 Agent Skills：这些 Skills 在您创建文档时已在幕后工作。Claude 无需任何设置即可使用它们。
  • 自定义 Skills：通过 设置 > 功能 (Settings > Features) 上传 zip 文件形式的 Skills。适用于启用了代码执行的 Pro, Max, Team 和 Enterprise 计划。自定义 Skills 针对每个用户独立；它们不在组织范围内共享，也不能由管理员集中管理。

要了解关于在 Claude.ai 中使用 Skills 的更多信息，请参阅 Claude 帮助中心中的以下资源：

Skill 结构

每个 Skill 都需要一个带有 YAML frontmatter 的 SKILL.md 文件：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

必填字段：name 和 description

字段要求：

name:

  • 最多 64 个字符
  • 必须仅包含小写字母、数字和连字符
  • 不能包含 XML 标签
  • 不能包含保留字："anthropic", "claude"

description:

  • 必须非空
  • 最多 1024 个字符
  • 不能包含 XML 标签

描述应包括 Skill 做什么以及 Claude 何时应使用它。有关完整的创作指南，请参阅 最佳实践指南。

安全注意事项

我们强烈建议仅使用来自可信来源的 Skills：您自己创建的或从 Anthropic 获取的。Skills 通过指令和代码为 Claude 提供了新能力，虽然这使它们变得强大，但也意味着恶意 Skill 可能会引导 Claude 以不符合 Skill 声称目的的方式调用工具或执行代码。

如果您必须使用来自不可信或未知来源的 Skill，请在使用前极其谨慎并彻底审核。根据 Claude 执行 Skill 时拥有的权限，恶意 Skills 可能导致数据泄露、未经授权的系统访问或其他安全风险。

关键安全注意事项：

  • 彻底审核：审查 Skill 中捆绑的所有文件：SKILL.md、脚本、图像和其他资源。寻找异常模式，如意外的网络调用、文件访问模式或不符合 Skill 声称目的的操作
  • 外部来源有风险：从外部 URL 获取数据的 Skills 风险特别大，因为获取的内容可能包含恶意指令。如果外部依赖项随时间变化，即使是可信的 Skills 也可能受到损害
  • 工具滥用：恶意 Skills 可能以有害方式调用工具（文件操作、bash 命令、代码执行）
  • 数据暴露：有权访问敏感数据的 Skills 可能被设计为向外部系统泄露信息
  • 像安装软件一样对待：仅使用来自可信来源的 Skills。在将 Skills 集成到具有敏感数据访问权限或关键操作的生产系统中时要特别小心