Claude Code Skill入门实战

如果要说 Claude 生态中最重要、最强大的扩展能力，非 Skill 莫属。

MCP 让 Claude 能连接外部工具，但 Skill 做的事情更根本------它让 Claude 学会"怎么干活"。你的代码规范、文档格式、审查流程、部署步骤，这些反复出现的工作模式，写成 Skill 之后 Claude 就一劳永逸地掌握了。不用每次对话都从头解释，不用担心换个人来提问结果就变了样。

这篇文章带你从概念到实操，完整理解 Skill 的设计思路和构建方法。

Skill 是什么

一句话：Skill 是一组打包成文件夹的指令集，教会 Claude 处理特定任务或工作流。

如果你用过 MCP（Model Context Protocol），可以这样理解它们的关系：

MCP 是"厨房"------提供工具、食材和设备的连接能力
Skill 是"菜谱"------告诉 Claude 怎么用这些工具做出一道好菜

MCP 解决的是"Claude 能做什么"，Skill 解决的是"Claude 该怎么做"。两者可以独立使用，也可以组合发挥更大威力。

graph LR A[用户请求] --> B{Claude} B --> C[Skill
工作流指令] B --> D[MCP
工具连接] C --> E[知道怎么做] D --> F[知道用什么] E --> G[高质量输出] F --> G classDef default fill:#0d1b2a,stroke:#1A9090,color:#e0e0e0 classDef highlight fill:#1A9090,stroke:#0d1b2a,color:#ffffff class B highlight class G highlight

没有 Skill 的时候，用户连上 MCP 却不知道下一步该干什么，每次对话都从零开始，结果因人而异。有了 Skill，预设的工作流会自动激活，最佳实践嵌入每次交互，学习成本大幅降低。

三个核心设计原则

在动手写之前，先理解 Skill 的设计哲学。这三个原则决定了 Skill 为什么长这个样子。

渐进式披露（Progressive Disclosure）

Skill 采用三层加载机制：

层级	内容	加载时机
第一层	YAML 前置元数据	始终加载到系统提示词中
第二层	SKILL.md 正文	Claude 判断 Skill 与当前任务相关时加载
第三层	关联文件（references/）	Claude 按需读取

这个设计的好处很直接：不浪费 token。Claude 不需要一次性把所有指令塞进上下文，而是按需逐层展开。

可组合性（Composability）

Claude 可以同时加载多个 Skill。你的 Skill 应该能和其他 Skill 和平共处，而不是假设自己独占整个舞台。

可移植性（Portability）

同一个 Skill 在 Claude.ai、Claude Code 和 API 上都能用，写一次到处跑。前提是运行环境支持 Skill 所需的依赖。

文件结构详解

一个 Skill 的目录结构长这样：

bash 复制代码

your-skill-name/
├── SKILL.md          # 必需 - 主指令文件
├── scripts/          # 可选 - 可执行脚本
│   ├── process_data.py
│   └── validate.sh
├── references/       # 可选 - 参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/           # 可选 - 模板、图标等资源
    └── report-template.md

唯一必需的文件是 SKILL.md。注意几个硬性规则：

文件名必须是 SKILL.md，大小写敏感，skill.md 或 SKILL.MD 都不行
文件夹名用 kebab-case：notion-project-setup 对，Notion Project Setup 错
不要在 Skill 文件夹里放 README.md，所有文档都写在 SKILL.md 或 references/ 里

编写 SKILL.md

SKILL.md 由两部分组成：YAML 前置元数据和 Markdown 正文。

YAML 前置元数据：决定 Skill 生死的关键

前置元数据是 Claude 决定是否加载你的 Skill 的唯一依据。写不好，Skill 就永远不会被触发。

最小格式只需要两个字段：

yaml 复制代码

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

name 的规则很简单：kebab-case，和文件夹名一致。

description 才是重头戏，它必须同时包含两个信息：

这个 Skill 做什么
什么时候该用它（触发条件）

为什么这个字段如此关键？回顾前面提到的渐进式披露机制------description 属于第一层，它始终存在于 Claude 的系统提示词中。Claude 就是靠这段文字来判断"当前用户的请求是否需要加载这个 Skill"。如果 description 写得模糊，Claude 根本不知道什么时候该调用它；如果写得太宽泛，又会在不相关的场景下误触发。可以说，description 的质量直接决定了 Skill 的可用性。

来看好的和差的对比：

yaml 复制代码

# 好 - 具体且包含触发短语
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.

# 差 - 没有触发条件
description: Creates sophisticated multi-page documentation systems.

好的 description 像一个精准的"if-then"语句：如果用户说了这些话，那就激活这个 Skill。

还有几个可选字段：

license：开源协议，如 MIT、Apache-2.0
compatibility：环境要求说明，1-500 字符
metadata：自定义键值对，建议包含 author 和 version

安全限制：前置元数据中不能包含 XML 尖括号（< >），name 中不能包含 "claude" 或 "anthropic"。

Markdown 正文：写好指令的技巧

前置元数据之后就是正文，用标准 Markdown 编写。推荐的结构模板：

markdown 复制代码

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [第一步]
清晰说明要做什么。

示例：
python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功的样子]

### Step 2: [第二步]
...

## Examples

### 示例 1: [常见场景]
用户说："帮我建一个营销活动"

操作步骤：
1. 通过 MCP 获取现有活动列表
2. 用提供的参数创建新活动

结果：活动创建成功，返回确认链接

## Troubleshooting

### 错误：[常见错误信息]
原因：[为什么会发生]
解决：[怎么修]

写指令时有几个关键原则：

要具体，不要抽象。 "运行 python scripts/validate.py --input {filename} 检查数据格式"比"在继续之前验证数据"好一百倍。

包含错误处理。 告诉 Claude 遇到常见错误时该怎么办，比如 MCP 连接失败时的排查步骤。

善用渐进式披露。 核心指令放在 SKILL.md 里，详细的 API 文档、参考资料放到 references/ 目录，在正文中引用即可。

三大常见用例

Anthropic 观察到 Skill 的使用主要集中在三个类别，每个类别有不同的侧重点。

graph TB subgraph cat1["类别 1：文档与资产创建"] A1[嵌入风格指南] --> A2[模板化输出结构] A2 --> A3[质量检查清单] end subgraph cat2["类别 2：工作流自动化"] B1[分步工作流] --> B2[验证门控] B2 --> B3[迭代优化循环] end subgraph cat3["类别 3：MCP 增强"] C1[编排多个 MCP 调用] --> C2[嵌入领域知识] C2 --> C3[错误处理] end classDef catStyle fill:#0d1b2a,stroke:#1A9090,color:#e0e0e0 classDef subStyle fill:#112233,stroke:#1A9090,color:#1A9090,font-weight:bold class A1,A2,A3,B1,B2,B3,C1,C2,C3 catStyle class cat1,cat2,cat3 subStyle

类别 1：文档与资产创建

用于生成一致的、高质量的输出物------文档、演示文稿、前端界面、代码等。

典型代表是 Anthropic 官方的 frontend-design Skill，它能"创建独特的、生产级的前端界面"。这类 Skill 的核心技巧是嵌入风格指南和品牌标准，用模板保证输出一致性，不需要外部工具，完全依赖 Claude 的内置能力。

类别 2：工作流自动化

用于需要一致方法论的多步骤流程。

典型代表是 skill-creator Skill 本身------它引导用户完成用例定义、前置元数据生成、指令编写和验证的完整流程。核心技巧是分步工作流加验证门控，每一步都有明确的检查点。

类别 3：MCP 增强

用于在 MCP 工具连接之上叠加工作流指导。

典型代表是 Sentry 的 sentry-code-review Skill，它利用 Sentry 的 MCP 服务器自动分析和修复 GitHub PR 中的 bug。核心技巧是编排多个 MCP 调用的顺序，嵌入用户原本需要手动提供的领域知识。

五种实战模式

掌握了基础之后，来看五种经过验证的 Skill 设计模式。

模式 1：顺序工作流编排

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

markdown 复制代码

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

关键点：明确步骤顺序、声明步骤间的依赖关系、每步都有验证、包含失败回滚指令。

模式 2：多 MCP 协调

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

比如设计到开发的交接流程：Phase 1 用 Figma MCP 导出设计稿，Phase 2 用 Drive MCP 存储资产，Phase 3 用 Linear MCP 创建开发任务，Phase 4 用 Slack MCP 发送通知。每个阶段之间有数据传递和验证。

模式 3：迭代优化

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

典型的报告生成流程：先拉数据生成初稿，然后运行验证脚本检查质量，针对问题逐项修正，重新验证，循环直到达标，最后定稿。关键是要定义明确的质量标准和退出条件。

模式 4：上下文感知的工具选择

适用场景：同一个目标，根据上下文选择不同工具。

比如文件存储：大文件走云存储 MCP，协作文档走 Notion MCP，代码文件走 GitHub MCP，临时文件用本地存储。Skill 中定义清晰的决策树，并向用户解释选择原因。

模式 5：领域知识嵌入

适用场景：Skill 需要提供超越工具连接的专业知识。

比如支付合规处理：在执行交易前先跑合规检查（制裁名单、管辖区限制、风险评估），通过才处理，不通过则标记审查，全程记录审计日志。领域专业知识直接编码在 Skill 的逻辑中。

分发与共享

Skill 写好了，怎么让别人用上？

个人用户安装

下载 Skill 文件夹
打包为 zip（如需要）
在 Claude.ai 中通过 Settings > Capabilities > Skills 上传
或者放到 Claude Code 的 skills 目录下

组织级部署

管理员可以在工作区范围内部署 Skill，支持自动更新和集中管理。

通过 API 使用

对于编程场景，API 提供了完整的 Skill 管理能力：

/v1/skills 端点用于列出和管理 Skill
通过 Messages API 的 container.skills 参数将 Skill 加入请求
配合 Claude Agent SDK 构建自定义 Agent

常见问题排查

最后整理几个高频踩坑点：

Skill 上传失败，提示 "Could not find SKILL.md" 检查文件名是否严格为 SKILL.md，大小写敏感。

Skill 不触发 问题几乎都出在 description 字段。检查是否太笼统、是否包含了用户实际会说的触发短语。调试技巧：直接问 Claude "你什么时候会用 [skill name] 这个 Skill？"，它会把 description 复述出来，你就知道哪里需要调整了。

Skill 触发太频繁 在 description 中加入否定触发条件，比如 "Do NOT use for simple data exploration"，或者缩小描述范围，从 "Processes documents" 改为 "Processes PDF legal documents for contract review"。

Skill 加载了但 Claude 不按指令执行 三个常见原因：指令太冗长（精简，用列表）、关键指令埋得太深（放到顶部，用醒目标题）、语言太模糊（把"确保正确验证"改成"在调用 create_project 前，验证项目名非空"）。

总结

Skill 的本质是把你的专业知识和工作流程编码成 Claude 可以反复执行的指令。它的设计足够简单------一个文件夹、一个 Markdown 文件就能起步，但通过渐进式披露、MCP 集成和多种设计模式的组合，又能支撑相当复杂的场景。

如果你想现在就动手，最快的路径是：用 skill-creator Skill 辅助生成，从一个具体的工作流开始，先让它跑通，再逐步扩展。Anthropic 的经验是，15-30 分钟就能构建并测试你的第一个可用 Skill。