Anthropic 官方文档《The Complete Guide to Building Skills for Claude》

一、全文概览

这份指南是 Anthropic 官方发布的 Claude Skill 构建完全手册，覆盖从概念理解、规划设计、测试迭代到分发共享的全生命周期。Skill 是 Claude 生态中一种轻量但强大的定制化机制——本质上就是一个包含指令的文件夹，教会 Claude 如何执行特定任务或工作流。

全文分为 6 章：

章节	核心内容
第1章 基础概念	Skill 的定义、文件结构、核心设计原则、与 MCP 的关系
第2章 规划与设计	用例分类、成功标准、技术要求、YAML 前言、指令编写
第3章 测试与迭代	三层测试方法、skill-creator 工具、反馈迭代
第4章 分发与共享	分发模型、API 使用、定位策略
第5章 模式与排障	5 种设计模式、常见问题排查
第6章 资源与参考	官方文档、示例仓库、验证清单

---

二、核心概念解读

2.1 Skill 是什么？

Skill = 一个文件夹，包含：

• SKILL.md（必须）：YAML 前言 + Markdown 指令
• scripts/（可选）：可执行脚本（Python、Bash 等）
• references/（可选）：按需加载的参考文档
• assets/（可选）：模板、字体、图标等资源

关键特性：

• 跨平台可移植：同一 Skill 在 Claude.ai、Claude Code、API 上均可运行
• 可组合：多个 Skill 可同时加载，互不冲突
• 渐进式披露：三层信息加载机制，最小化 token 消耗

2.2 三层渐进式披露架构

这是 Skill 最核心的设计理念——不是一次性把所有内容塞进上下文，而是按需逐层加载：

graph TB
    subgraph "三层渐进式披露架构"
        L1["第一层：YAML Frontmatter<br/>始终加载到系统提示词<br/>提供触发判断的最少信息"]
        L2["第二层：SKILL.md 正文<br/>Claude 判断相关时加载<br/>包含完整指令和引导"]
        L3["第三层：关联文件<br/>按需导航发现<br/>scripts/ references/ assets/"]
    end

    User["用户输入"] --> L1
    L1 -->|"匹配触发条件"| L2
    L2 -->|"执行中需要更多信息"| L3

    style L1 fill:#e8f5e9,stroke:#4caf50
    style L2 fill:#fff3e0,stroke:#ff9800
    style L3 fill:#e3f2fd,stroke:#2196f3

解读：这个设计非常精巧。系统提示词空间寸土寸金，如果 20 个 Skill 各塞 5000 字就会严重挤压对话空间。三层架构让 Claude 只用一句 description 就能判断何时激活某个 Skill，激活后才加载完整指令，执行中才去读参考文件。这与微服务中的"懒加载"思想一脉相承。

2.3 Skill 与 MCP 的关系

Anthropic 用了一个很生动的比喻——厨房与菜谱：

graph LR
    subgraph "MCP = 专业厨房"
        A1["工具访问"] 
        A2["实时数据"]
        A3["API 调用能力"]
    end

    subgraph "Skill = 菜谱"
        B1["工作流程"]
        B2["最佳实践"]
        B3["领域知识"]
    end

    subgraph "最终效果"
        C["用户无需自己摸索<br/>每一步该怎么做"]
    end

    A1 --> C
    A2 --> C
    A3 --> C
    B1 --> C
    B2 --> C
    B3 --> C

维度	MCP（连接层）	Skill（知识层）
作用	连接 Claude 到外部服务	教 Claude 如何高效使用服务
提供	实时数据访问与工具调用	工作流与最佳实践
回答	Claude 能做什么	Claude 该怎么做

解读：没有 Skill 的 MCP 就像把一个新手丢进专业厨房——工具都在，但不知道该做什么菜、什么顺序。Skill 填补了"能力"到"效能"之间的鸿沟。这也意味着 MCP 开发者应该把 Skill 视为产品的一部分，而非附加品。

---

三、三类典型用例

Anthropic 基于内部观察总结了三类核心 Skill 类别：

graph TB
    subgraph "Category 1: 文档与资产创建"
        C1["生成一致的高质量输出"]
        C1a["嵌入风格指南和品牌标准"]
        C1b["模板结构 + 质量清单"]
        C1c["无需外部工具"]
    end

    subgraph "Category 2: 工作流自动化"
        C2["多步骤流程的一致执行"]
        C2a["分步工作流 + 验证门"]
        C2b["模板 + 迭代优化循环"]
        C2c["可跨多个 MCP 协调"]
    end

    subgraph "Category 3: MCP 增强"
        C3["为已有 MCP 添加工作流指导"]
        C3a["串联多个 MCP 调用"]
        C3b["嵌入领域专业知识"]
        C3c["错误处理 + 上下文补充"]
    end

    style C1 fill:#c8e6c9
    style C2 fill:#fff9c4
    style C3 fill:#bbdefb

典型案例：

• Category 1：frontend-design skill — 创建生产级前端界面
• Category 2：skill-creator skill — 交互式引导用户创建新 Skill
• Category 3：sentry-code-review skill — 利用 Sentry MCP 自动分析 PR 中的 bug

---

四、技术规范要点

4.1 文件结构与命名

your-skill-name/          # kebab-case，禁止空格/大写/下划线
├── SKILL.md              # 必须，大小写敏感
├── scripts/              # 可选
├── references/           # 可选
└── assets/               # 可选

硬性规则：

• 文件名必须是 SKILL.md，不接受任何变体（SKILL.MD、skill.md 均无效）
• 文件夹名必须 kebab-case：notion-project-setup ✅，NotionProjectSetup ❌
• 不要在 Skill 文件夹内放 README.md

4.2 YAML Frontmatter — 最关键的部分

---
name: your-skill-name                    # 必需，kebab-case
description: |                            # 必需，<1024 字符
  做什么 + 什么时候用 + 触发词
license: MIT                              # 可选
allowed-tools: "Bash(python:*) WebFetch"  # 可选，限制工具访问
metadata:                                 # 可选
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
---

安全限制：

• 禁止使用 XML 尖括号 < >
• 禁止用 claude 或 anthropic 作为 Skill 名称前缀
• YAML 使用安全解析，禁止代码执行

4.3 Description 字段的写法

这是决定 Skill 能否被正确触发的最关键字段，结构应为：

做什么 + 什么时候用 + 核心能力

好的 description 示例：

Analyzes Figma design files and generates developer handoff documentation. 
Use when user uploads .fig files, asks for "design specs", "component documentation", 
or "design-to-code handoff".

坏的 description 示例：

Helps with projects.                    # 太模糊
Creates sophisticated documentation.   # 缺少触发词
Implements the entity model.            # 太技术化

解读：Description 在整个架构中的地位类似于搜索引擎中的 meta description——它直接决定了 Claude 在"第一层"判断中能否正确匹配用户意图。写得不好，Skill 就是死代码。

---

五、五大设计模式

graph TB
    P["5 大 Skill 设计模式"]
    
    P1["模式 1<br/>顺序工作流编排"]
    P2["模式 2<br/>多 MCP 协调"]
    P3["模式 3<br/>迭代精炼"]
    P4["模式 4<br/>上下文感知工具选择"]
    P5["模式 5<br/>领域专业智能"]

    P --> P1
    P --> P2
    P --> P3
    P --> P4
    P --> P5

    P1 --- P1D["固定步骤顺序<br/>步骤间依赖<br/>每步验证<br/>失败回滚"]
    P2 --- P2D["跨服务阶段划分<br/>MCP 间数据传递<br/>阶段前验证<br/>集中错误处理"]
    P3 --- P3D["初稿生成<br/>质量检查脚本<br/>精炼循环<br/>达标终止"]
    P4 --- P4D["决策树判断<br/>根据上下文选工具<br/>回退方案<br/>透明说明选择"]
    P5 --- P5D["嵌入领域规则<br/>合规前置检查<br/>审计追踪<br/>治理透明"]

    style P fill:#f5f5f5,stroke:#333
    style P1 fill:#e8f5e9
    style P2 fill:#fff3e0
    style P3 fill:#e3f2fd
    style P4 fill:#fce4ec
    style P5 fill:#f3e5f5

模式 1：顺序工作流编排 (Sequential Workflow Orchestration)

适用场景：用户需要按固定顺序执行多步骤流程

graph LR
    S1["创建账户"] --> S2["设置支付"]
    S2 --> S3["创建订阅"]
    S3 --> S4["发送欢迎邮件"]
    
    S2 -.->|"等待验证"| S2
    S1 -.->|"customer_id"| S3

关键技术：显式步骤排序、步骤间依赖、逐步验证、失败回滚。

模式 2：多 MCP 协调 (Multi-MCP Coordination)

适用场景：工作流跨越多个服务

graph TB
    subgraph "Phase 1: Figma MCP"
        F1["导出设计资产"]
        F2["生成设计规范"]
    end

    subgraph "Phase 2: Drive MCP"
        D1["创建项目文件夹"]
        D2["上传资产"]
    end

    subgraph "Phase 3: Linear MCP"
        L1["创建开发任务"]
        L2["关联资产链接"]
    end

    subgraph "Phase 4: Slack MCP"
        SL["发送交接摘要"]
    end

    F1 --> F2 --> D1 --> D2 --> L1 --> L2 --> SL

关键技术：清晰的阶段分离、MCP 间数据传递、阶段前验证、集中错误处理。

模式 3：迭代精炼 (Iterative Refinement)

适用场景：输出质量需要通过迭代提升

工作流：初稿 → 验证脚本检查 → 发现问题 → 修正 → 重新验证 → 循环直到达标 → 最终输出。

关键技术：显式质量标准、验证脚本、知道何时停止迭代。

模式 4：上下文感知工具选择 (Context-Aware Tool Selection)

适用场景：同样的目标，根据上下文选择不同工具

graph TB
    Input["输入文件"] --> Check["检查文件类型和大小"]
    Check -->|">10MB"| Cloud["云存储 MCP"]
    Check -->|"协作文档"| Notion["Notion/Docs MCP"]
    Check -->|"代码文件"| GitHub["GitHub MCP"]
    Check -->|"临时文件"| Local["本地存储"]

关键技术：明确的决策标准、回退选项、向用户解释选择原因。

模式 5：领域专业智能 (Domain-Specific Intelligence)

适用场景：Skill 需要注入超越工具访问的专业知识

典型流程：合规检查 → 条件分支（通过/不通过）→ 执行处理或标记审查 → 审计追踪。

关键技术：领域专业知识嵌入逻辑、合规前置于操作、完整文档化、清晰治理。

解读：这 5 种模式并非互斥的，实际的复杂 Skill 往往组合使用。比如一个企业级客户入职 Skill 可能同时包含顺序编排（模式1）、多 MCP 协调（模式2）和领域合规智能（模式5）。理解这些模式的价值在于，它们提供了可复用的思维框架。

---

六、测试策略

三层测试方法

层次	方法	适用场景
手动测试	在 Claude.ai 中直接运行查询	快速迭代，无需配置
脚本测试	在 Claude Code 中自动化测试用例	跨版本可重复验证
编程测试	通过 Skills API 构建评估套件	大规模系统化评估

三个测试维度

1. 触发测试：正确触发 + 不误触发
2. 功能测试：输出正确 + API 调用成功 + 错误处理有效
3. 性能对比：有 Skill vs. 无 Skill 的对比（消息轮数、token 消耗、API 失败率）

成功标准（参考值）

• Skill 在 90% 的相关查询上正确触发
• 工作流在 X 次工具调用内完成
• 每次工作流 0 次 API 调用失败

解读：Anthropic 坦言这些指标是"vibes-based"——还没有精确的度量工具，正在开发中。这说明 Skill 生态还在早期阶段，但他们提供的测试框架已经足够实用。

---

七、分发模型

当前（2026 年 1 月）的分发方式

graph TB
    subgraph "个人用户"
        U1["下载 Skill 文件夹"] --> U2["压缩为 .zip"]
        U2 --> U3["上传到 Claude.ai<br/>Settings > Capabilities > Skills"]
        U2 --> U4["放入 Claude Code Skills 目录"]
    end

    subgraph "组织级别"
        O1["管理员部署<br/>workspace 全局生效"]
        O2["自动更新"]
        O3["集中管理"]
    end

    subgraph "API 使用"
        A1["/v1/skills 端点"]
        A2["Messages API<br/>container.skills 参数"]
        A3["Claude Agent SDK"]
    end

    style U3 fill:#e8f5e9
    style O1 fill:#fff3e0
    style A1 fill:#e3f2fd

推荐做法

1. GitHub 托管：公开仓库 + 清晰 README + 使用截图
2. MCP 文档联动：在 MCP 文档中链接 Skill，解释两者配合使用的价值
3. 安装指南：提供完整的下载→安装→启用→测试步骤

开放标准

Anthropic 将 Agent Skills 发布为开放标准（类似 MCP），目标是跨平台可移植。同一 Skill 理论上可以在 Claude 和其他 AI 平台上运行。

---

八、排障指南精华

问题	症状	解决方案
上传失败	"Could not find SKILL.md"	文件名大小写敏感，必须是 SKILL.md
Frontmatter 无效	"Invalid frontmatter"	检查 --- 分隔符、引号闭合
不触发	Skill 从不自动加载	改善 description，加入具体触发词
过度触发	无关查询也加载	添加否定触发词，收窄范围
指令不遵循	Skill 加载但不按指令做	精简指令、关键内容置顶、用代码替代语言描述
上下文过大	响应变慢/质量下降	SKILL.md 控制在 5000 词以内，详细内容移到 references/
模型"偷懒"	跳过验证步骤	在用户提示词（而非 SKILL.md）中添加鼓励语

一个实用技巧：调试触发问题时，直接问 Claude："When would you use the [skill name] skill?" Claude 会引用 description 内容，据此调整。

---

九、综合观点与价值判断

Skill 机制的本质定位

Skill 不是插件、不是代码、不是 API——它是结构化的 Prompt Engineering。Anthropic 将 Prompt 工程从"每次手写"升级为"封装复用"，这解决了大模型使用中的一个核心痛点：知识的持久化与标准化。

与 Google ADK Skill 模式的对比

结合之前分析的 Google ADK 5 种 Agent Skill 设计模式，可以看到两种体系的异同：

维度	Anthropic Claude Skills	Google ADK Patterns
载体	文件夹 + Markdown	Python 代码 + 装饰器
核心机制	渐进式披露 + 自然语言指令	函数封装 + 类型系统
触发方式	Description 语义匹配	显式函数调用
可编程性	弱（依赖自然语言）	强（完整编程能力）
门槛	低（会写 Markdown 就行）	中（需要 Python）
确定性	较低（语言解释有歧义）	较高（代码执行确定）
生态策略	开放标准 + MCP 联动	深度绑定 Google 生态

关键洞察

1. Skill 是"Prompt as Code"的产品化：文件夹结构、版本管理、组织级部署——这些都在把 Prompt 当作软件工程产物来管理。
2. 三层披露是 token 经济学的必然：上下文窗口再大也不是无限的，渐进加载是唯一可持续的方案。
3. MCP + Skill 的组合拳是 Anthropic 的护城河策略：MCP 解决"能做什么"，Skill 解决"怎么做好"，两者结合构成完整的 AI 能力栈。
4. Skill 生态仍在早期：测量工具缺失、分发机制简陋（还在靠 ZIP 上传）、缺乏包管理——但基础架构设计合理，后续演进空间大。
5. "代码比语言更确定"的洞察值得重视：文档明确建议对关键验证逻辑使用脚本而非自然语言指令，这说明 Anthropic 自己也意识到了纯 Prompt 方案的局限性。

---

十、Skill 开发快速检查清单

开发前

• 确定 2-3 个具体用例
• 确认所需工具（内置 or MCP）
• 规划文件夹结构

开发中

• 文件夹名 kebab-case
• SKILL.md 拼写正确
• YAML frontmatter 有 --- 分隔符
• name 字段 kebab-case
• description 包含做什么 + 何时用
• 无 XML 标签 < >
• 指令清晰可执行
• 包含错误处理
• 包含使用示例
• 引用文件链接清晰

上传前

• 触发测试通过
• 功能测试通过
• 压缩为 .zip

上传后

• 在真实对话中测试
• 监控触发率
• 收集用户反馈
• 迭代 description 和指令

---

参考资源

• Best Practices Guide — 官方最佳实践
• Skills Documentation — 技术文档
• GitHub: anthropics/skills — 公开 Skill 仓库
• Introducing Agent Skills — 产品发布博客
• Engineering Blog: Equipping Agents for the Real World — 工程技术博客