Logoclaudeskills文档

概览

理解 Claude Agent Skills 的架构与优势。

Agent Skills 是扩展 Claude 能力的模块化组件。每个 Skill 都打包了指令、元数据，以及可选资源（脚本、模板），在任务匹配时由 Claude 自动调用。

为什么使用 Skills

Skills 是基于文件系统的可复用资源，为 Claude 提供领域专长：标准化流程、上下文与最佳实践，帮助通用型智能体蜕变为专业选手。与只在单次对话生效的 prompt 不同，Skills 会按需加载，不必在多轮对话中重复输入相同指引。

核心优势：

  • 让 Claude 专业化：针对特定领域或任务定制能力
  • 减少重复劳动：一次创建，长期复用
  • 组合能力：将多个 Skill 组合成更复杂的工作流

Note

如需深入了解 Agent Skills 的架构与实际案例，可阅读工程博客：Equipping agents for the real world with Agent Skills。

如何使用 Skills

Anthropic 提供涵盖常见文档任务（PowerPoint、Excel、Word、PDF）的预置 Agent Skills，同时你也可以创建自定义技能。两类技能的工作方式完全一致：当你的请求符合触发条件时，Claude 会自动调用。

预置 Agent Skills 在 claude.ai 与 Claude API 上对所有用户开放，完整列表见下方 可用 Skill。

自定义 Skills 可以封装组织知识与领域经验。你可以在 Claude Code 中创建、通过 API 上传，或在 claude.ai 的设置界面中添加。

Note

入门建议：

  • 想使用预置 Agent Skills：参见 快速入门，在 API 中启用 PowerPoint、Excel、Word 与 PDF 技能
  • 想编写自定义 Skills：参考 Agent Skills Cookbook

Skills 的工作原理

Skills 借助 Claude 的虚拟机环境，提供远超 prompt 的能力。Claude 在具有文件系统访问权限的虚拟机中运行，技能可以以目录形式存放指令、可执行代码与参考资料，类似你为新人准备的入职指南。

这种基于文件系统的架构实现了 渐进式加载：Claude 仅在需要时分阶段读取信息，而不是一次性填满上下文窗口。

三类 Skill 内容与三个加载层级

Skill 可包含三种内容，每种在不同阶段加载：

第 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 在启动时加载这些元数据并放入系统提示。这种轻量机制允许你安装大量技能而不占用上下文——Claude 只需知道技能存在，以及何时使用。

第 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).

当请求与技能描述匹配时，Claude 会通过 bash 读取文件系统中的 SKILL.md，此时内容才进入上下文窗口。

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

内容类型：指令、代码、资源。 Skill 可以打包额外资料：

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 只有在指令引用时才读取这些文件。文件系统模型让不同内容类型各展所长：指令提供灵活指导，代码确保执行稳定，资源满足精确信息查询。

层级加载时机Token 成本内容
第 1 级：元数据启动时常驻约每个 Skill 100 tokensYAML frontmatter 中的 name 与 description
第 2 级：指令正文Skill 被触发时通常 < 5k tokensSKILL.md 主体的流程与指引
第 3 级+：资源按需加载几乎无限通过 bash 执行或读取的文件，原文不进入上下文

渐进式加载确保任意时刻只有相关内容占据上下文窗口。

Skills 架构示意

技能运行在代码执行环境中，Claude 可以访问文件系统、执行 bash 命令并运行脚本。你可以把技能视作虚拟机中的一个目录，Claude 通过 bash 像在本地电脑上一样浏览文件。

Agent Skills 架构示意图

Claude 访问 Skill 内容的步骤：

当技能被触发时，Claude 会通过 bash 读取 SKILL.md，并把指令加载到上下文。如果指令引用了其他文件（例如 FORMS.md 或数据库结构），Claude 会继续读取对应文件。若指令提到可执行脚本，Claude 通过 bash 运行脚本，只有运行结果进入上下文。

该架构带来的优势：

  • 按需读取：只加载当前任务需要的文件，其余资源不会占用上下文
  • 脚本执行高效：脚本代码本身不进入上下文，只有输出结果消耗 token
  • 资源容量充足：可以打包完整 API 文档、数据集或示例，而无需担心上下文限制

示例：加载 PDF 处理技能

  1. 启动阶段：系统提示包含 PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
  2. 用户请求：“Extract the text from this PDF and summarize it”
  3. Claude 操作：执行 bash: read pdf-skill/SKILL.md 将指令加载到上下文
  4. 指令判断：若无需填写表单，则不会读取 FORMS.md
  5. 任务执行：Claude 按照 SKILL.md 中的流程完成任务
Skills 渐进式加载示意图

该流程展示了元数据常驻、指令按需加载、资源进一步按需加载的整个链路。

Skills 可用的平台

Skills 在 Claude 的各个产品线均可使用：

Claude API

Claude API 同时支持预置与自定义 Skills。调用时，在启用代码执行工具的同时，在 container 参数中指定 skill_id。

前置请求头（均需启用测试版）：

  • code-execution-2025-08-25：启用代码执行容器
  • skills-2025-10-02：启用 Skills 功能
  • files-api-2025-04-14：允许在容器内上传/下载文件

预置技能可直接引用官方 skill_id（如 pptx、xlsx）。若需自定义技能，可通过 Skills API（/v1/skills）创建并上传，组织内成员共享。

详见 在 Claude API 中使用 Skills。

Claude Code

Claude Code 当前仅支持自定义 Skills。

创建技能时，将包含 SKILL.md 的目录放置在 ~/.claude/skills/ 或项目根目录的 .claude/skills/ 中，Claude 会自动发现并调用。无需通过 API 上传。

更多说明参见 在 Claude Code 中使用 Skills。

Claude.ai

Claude.ai 同时支持预置与自定义技能。

  • 预置 Agent Skills：创建文档时已在后台自动生效，无需额外配置
  • 自定义 Skills：可在 Settings > Features 中上传 zip 包，需订阅 Pro、Max、Team 或 Enterprise，并启用代码执行功能。自定义技能按用户隔离，暂不支持组织级统一管理

更多帮助文档：

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。这是 frontmatter 唯一支持的字段。

字段限制：

  • name 最长 64 个字符
  • description 最长 1024 个字符

请在 description 中同时说明技能的作用及触发条件。更多写作建议请阅读 最佳实践指南。

安全注意事项

强烈建议仅使用可信来源的技能（自建或来自 Anthropic）。Skill 通过指令与代码扩展 Claude 的能力，这也意味着恶意技能可能引导 Claude 执行与声明不符的操作。

Warning

如必须启用来源不明的技能，请务必彻底审计后再使用。根据 Claude 在执行技能时拥有的权限，恶意技能可能导致数据泄露、越权访问或其他安全风险。

关键提醒：

  • 全面审计：检查技能包含的所有文件（SKILL.md、脚本、图片、资源等），留意异常的网络请求、文件操作或与声明目的不符的行为
  • 警惕外部依赖：从外部 URL 拉取内容的技能风险更高，即便是可信技能也可能因依赖更新而受影响
  • 防止工具滥用：恶意技能可能滥用文件操作、bash 命令或代码执行功能
  • 谨防数据泄露：访问敏感数据的技能可能被设计成向外部系统泄露信息
  • 像安装软件一样谨慎：仅信任可信来源的技能，尤其在生产环境或涉及敏感数据时更要小心

可用 Skill

预置 Agent Skills

以下技能可立即使用：

  • PowerPoint (pptx)：创建演示文稿、编辑幻灯片、分析演示内容
  • Excel (xlsx)：创建表格、分析数据、生成带图表的报告
  • Word (docx)：撰写与编辑文档、设置格式
  • PDF (pdf)：生成排版良好的 PDF 文档与报表

这些技能已在 Claude API 与 claude.ai 中上线。参见 快速入门 获取 API 示例。

自定义技能示例

想查看完整案例，请浏览 Skills cookbook。

限制与约束

理解以下限制，有助于你合理部署技能。

跨平台可用性

自定义技能不会在不同平台间自动同步：

  • 上传到 Claude.ai 的技能需要另行上传到 API
  • 通过 API 上传的技能不会出现在 Claude.ai
  • Claude Code 中的技能基于本地文件系统，与上述平台互不共享

共享范围

不同平台的共享模式不同：

  • Claude.ai：按用户独立管理，团队成员需各自上传
  • Claude API：按工作区共享，所有成员可使用已上传技能
  • Claude Code：支持个人 (~/.claude/skills/) 与项目 (.claude/skills/) 级配置

目前 Claude.ai 尚不支持管理员集中管理或组织级分发自定义技能。

运行环境限制

技能运行在代码执行容器中，需要遵守以下约束：

  • 无法访问外网：不能调用外部 API 或互联网资源
  • 无法临时安装依赖：仅能使用预装软件包
  • 仅限预配置依赖：完整列表参见 代码执行工具文档

请在这些限制内设计技能逻辑。

下一步

快速上手 Agent Skills

创建你的第一个 Skill

API 指南

在 Claude API 中调用 Skills

在 Claude Code 中使用 Skills

创建并管理自定义 Skills

写作最佳实践

让 Claude 更好理解你的 Skill

快速入门

使用 Claude Agent Skills API 创建文档。