Claude Code中英文系列教程34:再谈Skills

AwesomeAITools
0 阅读18分钟

Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant. Agent技能是模块化的功能，用于扩展 Claude 的功能。每个技能都打包了指令、元数据和可选资源（脚本、模板），Claude 在需要时会自动使用这些资源。

一，Why use Skills 为什么要使用技能

Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. 技能是可重用的、基于文件系统的资源，为 Claude 提供特定领域的专业知识：工作流程、上下文和最佳实践，这些可以将通用代理转化为专家。 与用于一次性任务的会话级指令（提示）不同，技能按需加载，并消除了在多个会话中重复提供相同指导的需要。

Key benefits: 主要优势：

1，Specialize Claude: Tailor capabilities for domain-specific tasks 专精 Claude：为特定领域任务定制能力

2，Reduce repetition: Create once, use automatically 减少重复：创建一次，自动使用

3，Compose capabilities: Combine Skills to build complex workflows 组合能力：结合 Skills 构建复杂工作流

二，Using Skills 使用技能

Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way. Claude automatically uses them when relevant to your request. Anthropic 提供了用于常见文档任务（PowerPoint、Excel、Word、PDF）的预构建 Agent 技能，你也可以创建自己的自定义技能。它们的工作方式相同。Claude 在相关请求时自动使用它们。

Pre-built Agent Skills are available to all users on claude.ai and via the Claude API. 预构建的 Agent 技能对所有用户在 claude.ai 和通过 Claude API 都可用。

Custom Skills let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them via the API, or add them in claude.ai settings. 自定义技能让你能够打包领域专业知识和组织知识。它们可在 Claude 的产品中使用：在 Claude Code 中创建它们，通过 API 上传它们，或在 claude.ai 设置中添加它们。

三，How Skills work Skills 的工作原理

Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member. 技能利用 Claude 的虚拟机环境来提供仅通过提示词无法实现的功能。Claude 在一个具有文件系统访问权限的虚拟机中运行，允许技能作为包含指令、可执行代码和参考资料的目录存在，就像为新团队成员创建的入职指南一样组织。

This filesystem-based architecture enables progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront. 这种基于文件系统的架构实现了渐进式披露：Claude 根据需要分阶段加载信息，而不是一次性消耗上下文。

3.1 Three types of Skill content, three levels of loading 三种技能内容类型，三种加载级别

Skills can contain three types of content, each loaded at different times: 技能可以包含三种类型的内容，每种内容加载的时间不同：

3.2 Level 1: Metadata (always loaded) 第一级：元数据（始终加载）

Content type: Instructions. The Skill's YAML frontmatter provides discovery information: 内容类型：指令。技能的 YAML 前导部分提供发现信息，如：

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

从 PDF 文件中提取文本和表格，填写表单，合并文档。在处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。

Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it. Claude 在启动时加载此元数据，并将其包含在系统提示中。这种轻量级方法意味着你可以安装许多 Skills 而无需承担上下文代价；Claude 只知道每个 Skill 的存在以及何时使用它。

3.3 Level 2: Instructions (loaded when triggered) 指令(触发时加载)

Content type: Instructions. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance: 内容类型：指令。SKILL.md 的主体部分包含程序性知识：工作流程、最佳实践和指导：

# PDF Processing

## Quick start  快速入门

Use pdfplumber to extract text from PDFs: 使用 pdfplumber 从 PDF 中提取文本：

```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).对于高级表单填写，请参阅FORMS.md。

When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window. 当你请求的内容与某个技能的描述相匹配时，Claude 通过 bash 从文件系统中读取 SKILL.md。只有到那时，这些内容才会进入上下文窗口。

3.4 Level 3: Resources and code (loaded as needed) 资源和代码（按需加载）

Content types: Instructions, code, and resources. Skills can bundle additional materials: 内容类型：指令、代码和资源。技能可以捆绑额外的材料：

pdf-skill/
├── SKILL.md (main instructions) 主指令文件
├── FORMS.md (form-filling guide) 表单填写指南
├── REFERENCE.md (detailed API reference) 详细 API 参考
└── scripts/
    └── fill_form.py (utility script) 实用脚本

其中 Instructions: Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows 指令: 包含专业指导和工作流的附加 markdown 文件（FORMS.md, REFERENCE.md）

Code: Executable scripts (fill_form.py, validate.py) that Claude runs via bash; scripts provide deterministic operations without consuming context 代码: 可执行的脚本（fill_form.py, validate.py），Claude 通过 bash 运行；脚本提供确定性操作而不消耗上下文

Resources: Reference materials like database schemas, API documentation, templates, or examples 资源: 数据库模式、API 文档、模板或示例等参考材料

Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup. Claude 仅在引用时访问这些文件。文件系统模型意味着每种内容类型都有不同的优势：用于灵活指导的指令、用于可靠性的代码、用于事实查证的资源。

LevelWhen LoadedToken CostContent
Level 1: MetadataAlways (at startup)~100 tokens per Skillname and description from YAML frontmatter
Level 2: InstructionsWhen Skill is triggered技能被触发时Under 5k tokensSKILL.md body with instructions and guidance包含指令和指导的 SKILL.md 正文
Level 3+: ResourcesAs needed按需加载Effectively unlimitedBundled files executed via bash without loading contents into context

Progressive disclosure ensures only relevant content occupies the context window at any given time. 渐进式披露确保在任何给定时间，上下文窗口中仅占用相关内容。

3.5 The Skills architecture 技能架构

Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Think of it like this: Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer. 技能在代码执行环境中运行，在这个环境里面Claude 具有文件系统访问权限、bash 命令和代码执行能力。可以这样理解：技能作为虚拟机上的目录存在，Claude 使用与在计算机上导航文件相同的 bash 命令与之交互。

下图是Agent Skills Architecture架构，

showing how Skills integrate with the agent's configuration and virtual machine 展示技能如何与agent的配置和虚拟机集成

Agent Skills Architecture - showing how Skills integrate with the agent's configuration and virtual machine转存失败，建议直接上传图片文件

How Claude accesses Skill content: Claude 如何访问技能内容

When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (like FORMS.md or a database schema),

Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them via bash and receives only the output (the script code itself never enters context). 当技能被触发时，Claude 使用 bash 从文件系统中读取 SKILL.md，将其指令带入上下文窗口。如果这些指令引用其他文件（如 FORMS.md 或数据库模式），

Claude 使用额外的 bash 命令读取这些文件。当指令提到可执行脚本时，Claude 通过 bash 运行它们，并仅接收输出（脚本代码本身不会进入上下文）。

What this architecture enables: 这种架构带来的优势

On-demand file access: Claude reads only the files needed for each specific task. A Skill can include dozens of reference files, but if your task only needs the sales schema, Claude loads just that one file. The rest remain on the filesystem consuming zero tokens. 按需文件访问：Claude 仅读取每个特定任务所需的文件。一个技能可以包含几十个参考文件，但如果你的任务只需要销售模式，Claude 仅加载该文件。其余文件仍保留在文件系统中，消耗零个 token。

Efficient script execution: When Claude runs validate_form.py, the script's code never loads into the context window. Only the script's output (like "Validation passed" or specific error messages) consumes tokens.

This makes scripts far more efficient than having Claude generate equivalent code on the fly. 高效的脚本执行：当 Claude 运行validate_form.py时，脚本代码不会加载到上下文窗口中。只有脚本的输出（如"验证通过"或特定的错误消息）会消耗 token。

这使得脚本比让 Claude 动态生成等效代码要高效得多。

No practical limit on bundled content: Because files don't consume context until accessed, Skills can include comprehensive API documentation, large datasets, extensive examples, or any reference materials you need. There's no context penalty for bundled content that isn't used. 没有捆绑内容的限制：由于文件在访问之前不会消耗上下文，Skills 可以包含全面的 API 文档、大型数据集、大量的示例或任何你需要的参考材料。对于未使用的捆绑内容，没有上下文惩罚。

This filesystem-based model is what makes progressive disclosure work. Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires. 这种基于文件系统的模型使得渐进式披露成为可能。Claude 像你参考入职指南的特定章节一样导航你的 Skill，访问每个任务所需的确切内容。

3.6 Example: Loading a PDF processing skill 示例：加载 PDF 处理技能

Here's how Claude loads and uses a PDF processing skill: 下面是 Claude 加载和使用 PDF 处理技能的方式：

  1. Startup启动: System prompt includes: PDF Processing - Extract text and tables from PDF files, fill forms, merge documents
  2. User request: "Extract the text from this PDF and summarize it"
  3. Claude invokes调用: bash: read pdf-skill/SKILL.md → Instructions loaded into context指令加载到上下文中
  4. Claude determines判断: Form filling is not needed, so FORMS.md is not read
  5. Claude executes: Uses instructions from SKILL.md to complete the task

下图展示了技能加载到上下文窗口 - 显示技能元数据和内容的逐步加载

Skills loading into context window - showing the progressive loading of skill metadata and content转存失败，建议直接上传图片文件

The diagram shows:

  1. Default state with system prompt and skill metadata pre-loaded 默认状态下系统提示和技能元数据已预加载
  2. Claude triggers the skill by reading SKILL.md via bash //Claude 通过 bash 读取 SKILL.md 来触发技能
  3. Claude optionally reads additional bundled files like FORMS.md as needed //Claude 根据需要可选地读取额外的捆绑文件
  4. Claude proceeds with the task //Claude 继续执行任务

This dynamic loading ensures only relevant skill content occupies the context window. 这种动态加载确保只有相关的技能内容占用上下文窗口。

四， Where Skills work 技能在哪些地方可以使用

Skills are available across Claude's agent products: 技能在 Claude 的代理产品中均可使用：

4.1 Claude API

The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant skill_id in the container parameter along with the code execution tool. Claude API 支持预构建的代理技能和自定义技能。两者工作方式相同：在 container 参数中指定相关的 skill_id 以及代码执行工具。

Prerequisites: Using Skills via the API requires three beta headers: 通过 API 使用技能需要三个测试版头信息

  • code-execution-2025-08-25 - Skills run in the code execution container 技能在代码执行容器中运行
  • skills-2025-10-02 - Enables Skills functionality 启用技能功能
  • files-api-2025-04-14 - Required for uploading/downloading files to/from the container 需要从容器里面上传下载文件

Use pre-built Agent Skills by referencing their skill_id (e.g., pptx, xlsx), or create and upload your own via the Skills API (/v1/skills endpoints). Custom Skills are shared organization-wide. 通过引用它们的 skill_id（例如，pptx，xlsx）使用预构建的代理技能，或通过 Skills API（/v1/skills 端点）创建并上传自己的技能。自定义技能在整个组织中共享。

4.2 Claude Code

Claude Code supports only Custom Skills. 仅支持自定义技能。

Custom Skills: Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically. 自定义技能：将技能创建为包含 SKILL.md 文件的目录。Claude 会自动发现并使用它们。

Custom Skills in Claude Code are filesystem-based and don't require API uploads. 自定义技能基于文件系统，无需 API 上传。

4.3 Claude Agent SDK

The Claude Agent SDK supports custom Skills through filesystem-based configuration.支持通过基于文件系统的配置来使用自定义技能。

Custom Skills: Create Skills as directories with SKILL.md files in .claude/skills/. Enable Skills by including "Skill" in your allowed_tools configuration. 自定义技能: 将技能创建为目录，并在 .claude/skills/ 中包含 SKILL.md 文件。通过在 allowed_tools 配置中包含 "Skill" 来启用技能。

Skills in the Agent SDK are then automatically discovered when the SDK runs. 当 SDK 运行时，Agent SDK 中的技能将自动被发现。

4.4 Claude.ai

Claude.ai supports both pre-built Agent Skills and custom Skills. 支持预构建的代理技能和自定义技能。

Pre-built Agent Skills: These Skills are already working behind the scenes when you create documents. Claude uses them without requiring any setup. 预构建的代理技能：当您创建文档时，这些技能已经在后台运行。Claude 使用它们而无需任何设置。

Custom Skills: Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled. Custom Skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins. 自定义技能：通过设置 > 功能，将您自己的技能作为 zip 文件上传。在启用了代码执行的 Pro、Max、团队和企业计划中可用。自定义技能是每个用户的专属；它们不会跨组织共享，管理员也无法集中管理。

五，Skill structure 技能结构

Every Skill requires a SKILL.md file with YAML frontmatter: 每个技能都需要一个 SKILL.md 文件，并带有 YAML 前置内容：

---
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] 使用此技能的具体示例

Required fields: name and description 必需字段

Field requirements: 字段要求：

name:

  • Maximum 64 characters
  • Must contain only lowercase letters, numbers, and hyphens 只能包含小写字母、数字和连字符
  • Cannot contain XML tags
  • Cannot contain reserved words: "anthropic", "claude" 不能包含保留词

description:

  • Must be non-empty 不能为空
  • Maximum 1024 characters 最大 1024 个字符
  • Cannot contain XML tags

The description should include both what the Skill does and when Claude should use it. description应包含技能的作用以及 Claude 何时应使用它。

六，Security considerations 安全事项

We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills provide Claude with new capabilities through instructions and code, and while this makes them powerful, it also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose. 强烈建议仅使用来自可信来源的技能：那些您自己创建的或从 Anthropic 获取的。技能通过指令和代码为 Claude 提供新功能，虽然这使它们非常强大，但也意味着一个恶意的技能可以指示 Claude 调用工具或以与技能声明目的不符的方式执行代码。

Key security considerations:关键安全注意事项

  • Audit thoroughly: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns like unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose 彻底审计：检查 Skill 目录下捆绑的所有文件：SKILL.md、脚本、图片和其他资源。寻找异常模式，如意外的网络调用、文件访问模式或与 Skill 声明目的不符的操作

  • External sources are risky: Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time 外部来源有风险：从外部 URL 获取数据的 Skill 存在特殊风险，因为获取的内容可能包含恶意指令。即使可信的 Skill 也可能被攻破，如果其外部依赖随时间变化

  • Tool misuse: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways 工具误用：恶意 Skill 可能以有害方式调用工具（文件操作、bash 命令、代码执行）

  • Data exposure: Skills with access to sensitive data could be designed to leak information to external systems 数据泄露：具有访问敏感数据的 Skill 可能被设计为向外部系统泄露信息

  • Treat like installing software: Only use Skills from trusted sources. Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations 像安装软件一样谨慎处理：仅从可信来源使用技能。在将技能集成到可访问敏感数据或关键操作的生产行为中时，请特别小心

七，Available Skills 可用 Skill

7.1 Pre-built Agent Skills 预构建的 Agent Skill

The following pre-built Agent Skills are available for immediate use: 以下预构建的 Agent Skill 可供立即使用：

  • PowerPoint (pptx): Create presentations, edit slides, analyze presentation content 创建演示文稿，编辑幻灯片，分析演示内容
  • Excel (xlsx): Create spreadsheets, analyze data, generate reports with charts 创建电子表格，分析数据，使用图表生成报告
  • Word (docx): Create documents, edit content, format text 创建文档，编辑内容，格式化文本
  • PDF (pdf): Generate formatted PDF documents and reports 生成格式化 PDF 文档和报告

These Skills are available on the Claude API and claude.ai. 这些技能可在 Claude API 和 claude.ai 上使用。

八，Limitations and constraints 限制与约束

Understanding these limitations helps you plan your Skills deployment effectively. 了解这些限制有助于您有效地规划技能部署。

8.1 Cross-surface availability 跨工具可用性

Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others: 自定义技能不会跨工具同步。上传到某一工具的技能不会自动在其他工具可用：

  • Skills uploaded to Claude.ai must be separately uploaded to the API 上传到 Claude.ai 的技能必须单独上传到 API
  • Skills uploaded via the API are not available on Claude.ai 通过 API 上传的技能在 Claude.ai 上不可用
  • Claude Code Skills are filesystem-based and separate from both Claude.ai and API 与 Claude.ai 和 API 都分开

You'll need to manage and upload Skills separately for each surface where you want to use them. 您需要为每个想要使用的工具分别管理和上传技能。

8.2 Sharing scope 分享范围

Skills have different sharing models depending on where you use them: 技能的共享模式根据使用地点不同而有所差异

  • Claude.ai: Individual user only; each team member must upload separately 仅限个人用户；每个团队成员必须单独上传
  • Claude API: Workspace-wide; all workspace members can access uploaded Skills 整个工作区；所有工作区成员都可以访问上传的技能
  • Claude Code: Personal (~/.claude/skills/) or project-based (.claude/skills/); can also be shared via Claude Code Plugins 也可以通过 Claude 代码插件共享

Claude.ai does not currently support centralized admin management or org-wide distribution of custom Skills. Claude.ai 目前不支持集中式管理员管理或组织范围内的自定义技能分发。

8.3 Runtime environment constraints运行时环境限制

The exact runtime environment available to your skill depends on the product surface where you use it. 你的技能可用的确切运行时环境取决于您使用它的产品。

  • Claude.ai:
    • Varying network access: Depending on user/admin settings, Skills may have full, partial, or no network access. 网络访问权限不同：根据用户/管理员设置，技能可能具有完全、部分或不具备网络访问权限。
  • Claude API:
    • No network access: Skills cannot make external API calls or access the internet 无网络访问权限：技能无法进行外部 API 调用或访问互联网
    • No runtime package installation: Only pre-installed packages are available. You cannot install new packages during execution. 无法在运行时安装包：仅提供预安装的包。执行期间无法安装新包。
    • Pre-configured dependencies only: Check the code execution tool documentation for the list of available packages 仅预配置的依赖项：可查阅代码执行工具文档以获取可用包的列表
  • Claude Code:
    • Full network access: Skills have the same network access as any other program on the user's computer 完全网络访问：技能与用户计算机上的任何其他程序具有相同的网络访问权限
    • Global package installation discouraged: Skills should only install packages locally in order to avoid interfering with the user's computer 不建议全局安装包：技能应仅本地安装包，以避免干扰用户计算机

小结： 提供特定领域的专业知识：工作流程、上下文和最佳实践

像为新团队成员创建的入职指南

内容包括 工作流程、最佳实践和指导

Claude 通过 bash 从文件系统中读取 SKILL.md。

资源里面可以放API documentation, 或 examples,一个技能可以包含几十个参考文件

渐进式披露

技能在代码执行环境中运行

在 container 参数中指定相关的 skill_id 以及代码执行工具。

/v1/skills创建并上传自己的技能

cc里面使用的自定义技能基于文件系统

Claude Agent SDK 支持通过基于文件系统的配置来使用自定义技能。

description: 最大 1024 个字符

Claude API 无网络访问权限，无法在运行时安装包

avatar
文章
阅读
粉丝