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：

1. Understand (理解)

在动手之前，先明确 Skill 的核心目标。问自己：

• 解决什么痛点？

• "Best result" 是什么样的？

• "Worst case" 可能发生什么？

2. Plan (规划)

设计 Skill 的架构，特别是文件结构：

• 哪些内容应该放在 SKILL.md（Prompt）？

• 哪些逻辑应该写成 Python 脚本（Script）？

• 哪些参考文档需要放入 resources/ 目录？ 设计原则：优先使用脚本处理确定性任务（Low DoF），使用 Prompt 处理创造性任务（High DoF）。

3. Init (初始化)

不要从零手写 YAML。使用脚本（如 init_skill.py）生成标准脚手架，确保元数据格式正确。

python scripts/init_skill.py my-new-skill

4. Edit (编写)

按正确顺序填充内容：

1. 先写资源：编写 scripts/*.py 和 resources/。这确保 Prompt 可以指向真实存在的文件。

2. 后写指令：编写 SKILL.md，即“胶水层”。

5. Validate (验证)

在提交之前，必须通过验证脚本（如 quick_validate.py）：

• 检查 YAML 语法

• 检查文件引用路径

• 模拟基本调用

6. Iterate (迭代)

Skill 不是一次性工作。根据使用反馈（如“为什么这个 Skill 没被触发？”或“为什么执行错了？”）不断微调 description 和 instructions。

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