Claude Agent Skills(技能)是一种可复用的文件系统资源,为Claude提供特定领域的专业知识、工作流程和最佳实践。与传统的提示词不同,Skills可以按需加载,无需在每次对话中重复提供相同的指导。

为什么需要Skills

Skills的核心价值在于将通用AI助手转变为领域专家。主要优势包括:

• 专业化能力: 针对特定任务定制Claude的能力
• 减少重复: 创建一次,自动使用
• 组合能力: 结合多个Skills构建复杂工作流

Skills的工作原理

Skills利用Claude的虚拟机环境,提供超越传统提示词的能力。Claude运行在一个具有文件系统访问权限的虚拟机中,Skills以目录形式存在,包含指令、可执行代码和参考资料。

三层加载机制

Skills包含三种类型的内容,每种在不同时机加载:

第一层:元数据(始终加载)

Skills的YAML前置配置提供发现信息。Claude在启动时加载这些元数据并包含在系统提示中。轻量级的方法意味着可以安装许多Skills而不会产生上下文开销。

---
name: pdf-processing
description: 从PDF文件中提取文本和表格、填写表单、合并文档。当处理PDF文件或用户提及PDF、表单或文档提取时使用。
---

第二层:指令(触发时加载)

SKILL.md的主体包含程序性知识:工作流程、最佳实践和指导。当请求与Skills描述匹配时,Claude通过bash从文件系统读取SKILL.md,此时内容才进入上下文窗口。

# PDF处理

## 快速开始

使用pdfplumber从PDF提取文本:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()

高级表单填充请参见FORMS.md。

第三层:资源和代码(按需加载)

Skills可以打包额外材料:
pdf-skill/
├── SKILL.md (主要指令)
├── FORMS.md (表单填写指南)
├── REFERENCE.md (详细API参考)
└── scripts/
    └── fill_form.py (工具脚本)

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

层级	加载时机	Token成本	内容
第一层:元数据	始终(启动时)	每个Skill约100 tokens	YAML前置配置中的name和description
第二层:指令	Skills触发时	5k tokens以内	SKILL.md主体的指令和指导
第三层+:资源	按需	实际上无限制	通过bash执行的打包文件,无需加载内容到上下文

Skills架构

Skills在代码执行环境中运行,Claude可以访问文件系统、bash命令和代码执行能力。可以这样理解:Skills作为目录存在于虚拟机上,Claude使用bash命令与它们交互。

Claude如何访问Skills内容:

当Skills被触发时,Claude使用bash从文件系统读取SKILL.md,将其指令带入上下文窗口。如果这些指令引用其他文件(如FORMS.md或数据库架构),Claude也会使用额外的bash命令读取这些文件。当指令提到可执行脚本时,Claude通过bash运行它们,只接收输出(脚本代码本身从不进入上下文)。

这种架构的优势:

• 按需文件访问: Claude只读取每个特定任务所需的文件。Skills可以包含数十个参考文件,但如果任务只需要销售模式,Claude就只加载那一个文件
• 高效脚本执行: 当Claude运行validate_form.py时,脚本代码不会加载到上下文窗口。只有脚本的输出消耗tokens
• 打包内容无实际限制: 因为文件在访问前不消耗上下文,Skills可以包含全面的API文档、大型数据集、大量示例或任何需要的参考资料

Skills的应用场景

Skills在Claude的各个产品中都可用:

Claude API

Claude API同时支持预构建的Agent Skills和自定义Skills。使用时在container参数中指定相关的skill_id以及代码执行工具。

使用Skills需要三个beta头:

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

Claude Code

Claude Code仅支持自定义Skills。创建包含SKILL.md文件的目录,Claude会自动发现并使用它们。

Claude Agent SDK

Claude Agent SDK通过文件系统配置支持自定义Skills。在.claude/skills/中创建Skills目录,在allowed_tools配置中包含"Skill"即可启用。

Claude.ai

Claude.ai同时支持预构建的Agent Skills和自定义Skills。预构建Skills在创建文档时已在后台工作,无需设置。自定义Skills可通过设置>功能上传zip文件。

Skill结构与编写

每个Skill都需要一个包含YAML前置配置的SKILL.md文件:

---
name: your-skill-name
description: 简要描述这个Skill的功能和使用场景
---

# Skill名称

## 指令
[为Claude提供清晰的分步指导]

## 示例
[使用该Skill的具体示例]

必需字段: name和description

字段要求:

name:

• 最多64个字符
• 只能包含小写字母、数字和连字符
• 不能包含XML标签
• 不能包含保留词: “anthropic”, “claude”

description:

• 不能为空
• 最多1024个字符
• 不能包含XML标签

Skills编写最佳实践-PDF处理Skill

完整代码：https://github.com/anthropics/skills/tree/main/skills/pdf

以下展示Claude如何加载和使用PDF处理Skill:

1. 启动: 系统提示包含: PDF处理 - 从PDF文件提取文本和表格、填写表单、合并文档
2. 用户请求: “从这个PDF提取文本并总结”
3. Claude调用: bash: read pdf-skill/SKILL.md → 指令加载到上下文
4. Claude判断: 不需要表单填充,所以不读取FORMS.md
5. Claude执行: 使用SKILL.md中的指令完成任务

对于特别复杂的工作流，提供一个清单，Claude 可以将其复制到其响应中并在进行时检查。