6.2 Skills 的结构与组成

一个 Skill 是一个工程化的文件夹，其核心是 SKILL.md 文件。本节详细介绍官方的文件格式和创建流程。

6.2.1 标准目录结构

一个典型的 Skill 文件夹结构如下：

my-skill/
├── SKILL.md             # 核心文件：元数据 + 指令
├── scripts/             # 可选：可执行脚本
│   └── process.py
├── resources/           # 可选：参考文档、模板
│   └── template.docx
└── examples/            # 可选：示例输入输出
    ├── input_1.txt
    └── output_1.txt

最简形式：一个 Skill 只需要一个 SKILL.md 文件即可，其他目录都是可选的。

6.2.2 SKILL.md 文件格式

SKILL.md 采用 YAML Frontmatter + Markdown Body 的格式：

---
name: my-skill-name
description: "Skill 的触发描述，决定何时被调用"
license: Complete terms in LICENSE.txt
---

# Skill 的核心指令

## Overview
这里描述 Skill 的功能概述...

## Instructions
具体的执行指令...

核心字段说明

字段	作用	要求
name	Skill 的唯一标识符	小写，使用连字符，如 pdf-editor
description	最关键字段：决定 Skill 何时被触发	详细描述能力、触发场景、边界条件
license	许可证信息	可选

重要提示：只有 name 和 description 会影响 Skill 的触发逻辑，正文内容只在 Skill 被激活后才会被读取。

6.2.3 Description 编写指南

description 是 Skill 最关键的部分，它决定了 Claude 何时会调用这个 Skill。

弱 Description 示例

This skill helps with PDFs and documents.

问题：太模糊，Claude 不知道具体能做什么、何时该用。

强 Description 示例

Comprehensive PDF manipulation toolkit for extracting text and tables, 
creating new PDFs, merging/splitting documents, and handling forms. 
When Claude needs to fill in a PDF form or programmatically process, 
generate, or analyze PDF documents at scale. Use for document workflows 
and batch operations. Not for simple PDF viewing or basic conversions.

这个强版本包含了：

• 具体能力：extract, create, merge, split, handle forms

• 触发场景：fill in forms, batch operations

• 明确边界：not for simple viewing（告诉 Claude 何时不该用）

6.2.4 创建 Skill 的五步流程

根据 Anthropic 官方博客的最佳实践：

步骤一：明确需求

在编写任何内容之前，回答以下问题：

• 这个 Skill 解决什么具体问题？

• 什么信号应该触发它？

• 成功的输出是什么样的？

• 有哪些边缘情况？

步骤二：编写 Name

• 使用小写字母和连字符

• 保持简短但描述性

• 示例：pdf-editor, brand-guidelines, code-reviewer

步骤三：编写 Description

这是最关键的步骤。从 Claude 的视角编写，聚焦于：

• 具体能力（动词优先）

• 触发场景（When to use）

• 边界条件（When NOT to use）

步骤四：编写 Instructions

正文部分应该：

• 结构清晰，使用 Markdown 标题层级

• 包含具体示例

• 说明 Skill 不能做什么

• 如有复杂流程，使用决策树引导

步骤五：测试与迭代

创建测试矩阵，覆盖三类场景：

场景类型	测试目的	示例
正常操作	验证核心功能	使用典型输入测试预期输出
边缘情况	验证健壮性	输入不完整、格式异常时的处理
越界请求	验证边界	相似但不应触发的请求

6.2.5 Skill 上传方式

根据使用场景，有三种上传方式：

Claude.ai（消费者）

进入 Settings → Features → Skills，上传自定义 Skill 文件夹。

Claude Code（开发者）

将 Skill 文件夹放置在以下任一位置：

~/.claude/skills/my-skill/SKILL.md      # 全局 Skill
./skills/my-skill/SKILL.md              # 项目级 Skill

Claude 会自动发现并加载这些 Skills。

API（开发者）

使用 /v1/skills 端点上传：

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F "display_title=My Skill Name" \
  -F "files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md"

6.2.6 高级模式：渐进式披露

对于复杂的 Skills，避免将所有信息放在一个巨大的 SKILL.md 中。采用菜单模式：

my-complex-skill/
├── SKILL.md              # 概述 + 目录索引
├── workflow-a.md         # 流程 A 的详细指令
├── workflow-b.md         # 流程 B 的详细指令
└── workflow-c.md         # 流程 C 的详细指令

在 SKILL.md 中使用相对路径引用：

## Available Workflows

### Workflow A
For creating new documents, read [`workflow-a.md`](workflow-a.md).

### Workflow B  
For editing existing documents, read [`workflow-b.md`](workflow-b.md).

Claude 会根据当前任务，只读取相关的子文件，保持上下文精简。

---

了解了 Skill 的结构后，让我们看看 Anthropic 官方提供了哪些开箱即用的内置 Skills。

➡️ 使用内置 Skills