Anthropic 发布了一份 33 页的 Skills 构建指南，系统讲透了如何把工作流变成可复用的“技能包”。

苏米带你完整拆解这份资料的精髓与落地方法。

先聊一个关键共识：human-in-the-loop 如今反而成了瓶颈。

OpenAI 在春节期间的工程博客中分享了他们用 Codex agent 做项目的经验——随着模型和 agent 产能飙升，人类审核成为系统里最慢、最贵的一环。

每个 PR 等人过目、每次错误等人修复，都不现实。

他们开始去人类环节，改用“渐进式披露”的文件系统：用一个约 100 行的 AGENTS.md 作为目录，指向结构化设计文档、架构规范与执行计划。

让大模型自我加速，在需要时查阅、独立运行，崩溃后读日志再改再跑，单次任务可以跑很久很久。

参考：Harness Engineering（OpenAI）。

因此，“渐进式披露 + 按需加载”成为今天 Agent 工程的核心武功。Anthropic 这篇教程写得极详尽，以下是全篇精炼改写与深入说明。

引言

Skill 是打包成文件夹的指令集，用来教会 Claude 执行特定任务或工作流。这是定制 Claude 的高效方式：一次写好，反复复用，不再在每次对话里重复偏好、流程和领域背景。

Skill 擅长可重复的流程：按需求稿生成前端、用固定方法论做调研、遵循团队规范写文档、编排多步骤任务等。它与 Claude 内置能力（代码执行、文档创建等）天然配合。如果你在做 MCP 集成，Skill 可以在原始工具调用之上再加一层，把零散接口变成稳定、优化的工作流。

这份指南覆盖了 Skill 的完整生命周期：从结构与设计，到测试、迭代与分发。不管是个人使用、团队协作还是社区发布，都有可直接套用的模式与案例。

你将理解：

• Skill 的技术结构与最佳实践
• 独立 Skill 与“Skills + MCP”的设计范式
• 各类场景中的有效方法
• 如何测试、迭代与分发 Skill

适用人群：

• 希望让 Claude 稳定执行特定工作流的开发者
• 希望把流程固化为“按步骤办事”的高级用户
• 希望在组织范围统一 Claude 使用方式的团队

两条实施路线：

• 只做独立 Skill：重点看“基础概念”“规划与设计”和第 1-2 类案例
• 为 MCP 集成加一层工作流引导：直看“Skills + MCP”与第 3 类案例

预期收获：看完即可在一个下午内做出能用的 Skill。使用 skill-creator，15-30 分钟就能跑起第一个版本。

基础概念

什么是 Skill？

一个 Skill 是一个文件夹，包含：

• SKILL.md（必需）：Markdown 指令文件，带 YAML 头部信息
• scripts（可选）：可执行脚本（Python、Bash 等）
• references（可选）：按需加载的参考文档
• assets（可选）：模板、字体、图标等素材

核心设计原则

渐进式披露

• 第一级（YAML 头部）：总是加载进系统提示，提供“刚好够用”的元信息，让 Claude 判断是否调用该 Skill。
• 第二级（SKILL.md 正文）：仅在任务相关时加载，包含完整指令与指南。
• 第三级（关联文件）：需要时才查阅的参考资料与资源。

这套机制在保证专业能力的同时，把 token 消耗降到最低。

可组合性

Claude 可同时加载多个 Skill。你的 Skill 不应假设自己是唯一能力，应与其他 Skill协作。

可移植性

Skill 在 Claude.ai、Claude Code 与 API 中表现一致。一次创建，全平台可用（前提是依赖满足）。

给 MCP 开发者：Skills + 连接器

只做独立 Skill 的读者可直接跳到“规划与设计”。

如果你已有运行中的 MCP 服务器，最难的连接层已完成。Skill 是知识层——把工作流与最佳实践固化为可复用的指令，让 Claude 稳定如一地执行。

比喻：MCP 是专业厨房（工具、食材、设备的访问权限）；Skill 是菜谱（把这些资源按步骤变成可用成果）。两者结合，用户无需自己摸索，即可完成复杂任务。

配合关系：

• MCP（连接能力）：让 Claude 接入你的服务（如 Notion、Asana、Linear），提供实时数据与工具调用
• Skill（知识能力）：教 Claude 如何高效使用这些服务，把流程与最佳实践嵌入每次交互

为什么你的 MCP 用户需要 Skill？

• 没有 Skill：用户连上你的 MCP，却不知道下一步；客服充斥“如何用你的集成做 X”；每次从零开始、结果不一致；用户把问题归咎于连接器，但真正缺的是工作流引导。
• 有 Skill：需要时自动激活预置工作流；工具调用稳定可靠；最佳实践内嵌在每次交互中；集成的上手门槛显著下降。

规划与设计

从用例出发

动笔前先明确 2-3 个要支撑的具体场景。一个好的用例定义包含：触发条件、步骤与结果。

示例（Sprint 规划）：

• 触发：用户说“帮我规划这个 sprint”“创建 sprint 任务”
• 步骤：
  1. 通过 MCP 获取当前项目状态
  2. 分析团队速率与产能
  3. 给出任务优先级建议
  4. 在 Linear 中创建任务并添加标签与工时
• 结果：一个完整规划好的 sprint，相关任务已创建

自问要点：

• 用户要完成什么？是否涉及多步骤工作流？
• 需要哪些工具（内置或 MCP）？
• 要嵌入哪些领域知识或团队最佳实践？

常见 Skill 用例分类

我们观察到三类典型用法：

1. 文档与素材生成

   用于产出一致、高质量的文档、演示稿、应用、设计稿等。

   案例：frontend-design skill（以及 docx、pptx、xlsx、ppt 等系列）。目标是生成可上线的前端界面与组件/页面/海报等 artifact。

   关键技巧：嵌入风格指南与品牌规范；以模板结构保证一致性；交付前用质量清单把关；尽量依赖 Claude 内置能力。

2. 工作流自动化

   用于需要稳定方法论的多步骤流程（可跨多个 MCP）。

   案例：skill-creator skill。它用交互方式引导你从用例到头部信息、指令编写与验证。

   关键技巧：分步工作流与每步验证；模板化常见结构；内置审查与改进建议；迭代精炼闭环。

3. MCP 增强

   在 MCP 工具访问之上叠加工作流与领域知识。

   案例：sentry-code-review skill（Sentry）。利用 Sentry MCP 的错误数据，自动分析并修复 GitHub PR 中的 bug。

   关键技巧：编排多次 MCP 调用；嵌入专业知识；补全用户原本要手动提供的上下文；处理 MCP 常见错误。

定义成功标准

如何判断 Skill 好用？参考这组指标（非硬阈值）：

量化：

• 在 90% 相关查询中被自动触发（测试 10-20 条应触发的查询，统计自动加载比例）
• 工作流在较少的工具调用内完成（对比开关 Skill 的调用次数与 token 消耗）
• 每次工作流 0 个失败的 API 调用（监控 MCP 日志，跟踪错误码与重试率）

定性：

• 用户无需提示下一步（记录纠正或补充说明频率，收集内测反馈）
• 工作流可一次完成无需用户修正（同请求复跑 3-5 次，对比结构与质量一致性）
• 跨会话结果一致（新用户能否在最少引导下第一次就完成任务）

技术要求

文件结构：

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 文件夹命名用 kebab-case：如 notion-project-setup；不得含空格、下划线或大写
• Skill 文件夹内不要放 README.md（仓库级别 README 仍然需要，用于分发与说明）

YAML 头部信息：触发的关键

头部信息决定 Claude 是否加载你的 Skill，务必写好。

最简格式：

---
name: your-skill-name
description: 做什么用的；当用户说 [具体短语] 时使用。
---

字段说明：

• name（必填）：kebab-case；无空格或大写；建议与文件夹名一致
• description（必填）：同时包含“这个 Skill 做什么”和“何时使用（触发条件）”；不超过 1024 字；不能含 XML 标签（< 或 >）；尽量写出用户会说的具体任务描述；涉及特定文件类型请注明
• license（可选）：开源许可证（MIT、Apache-2.0 等）
• compatibility（可选）：1-500 字，标注环境要求与依赖
• metadata（可选）：自定义键值对，建议含 author、version、mcp-server

示例：

metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制：

• 头部信息中禁止出现 XML 尖括号（< >）
• Skill 名字不能包含“claude”或“anthropic”（保留字）

写出有效的 description

原则：提供“刚好够用”的信息，让 Claude 知道何时加载，而无需把全文放进上下文。这就是渐进式披露的第一级。

结构公式：做什么 + 什么时候用 + 核心能力。

好的示例：

# 具体且可操作
description: 分析 Figma 设计稿并生成开发交接文档。用户上传 .fig、提到“设计规格”“组件文档”“设计转开发”时使用。

# 包含触发短语
description: 管理 Linear 项目工作流（sprint 规划、任务创建、状态跟踪）。当用户提到“sprint”“Linear 任务”“项目规划”或“创建工单”时使用。

# 价值主张清晰
description: PayFlow 端到端客户入职流程（账户创建、支付设置、订阅管理）。当用户说“入职新客户”“设置订阅”“创建 PayFlow 账户”时使用。

差的示例：

# 过于含糊
description: 帮忙处理项目。

# 缺少触发条件
description: 创建复杂的多页文档系统。

# 只讲技术，不含用户语言
description: 实现带层级关系的 Project 实体模型。

编写主体指令

推荐骨架（按你的场景替换方括号内容）：

---
name: your-skill
description: [……]
---
# [Skill 名称]

## 指令

### 第 1 步： [第一个主要步骤]
说明这一步的目标与操作。
示例：python scripts/fetch_data.py --project-id PROJECT_ID
预期输出： [描述成功的标准]

（按需添加更多步骤）

## 示例

### 示例 1： [常见场景]
用户说：“帮我建一个新的营销活动”
操作：
1. 通过 MCP 获取现有活动
2. 用提供的参数创建新活动
结果：活动已创建，并附确认链接

（按需添加更多示例）

## 问题排查
报错： [常见错误信息]
原因： [出现原因]
解决方案： [修复方法]

最佳实践：

• 具体且可操作：给出明确命令与参数、常见错误与修复方法
• 包含错误处理与验证关卡
• 把详细参考放入 references/，在正文中明确引用
• 遵循渐进式披露：SKILL.md 放核心指令，细节移至 references/

测试与迭代

测试层级可按使用范围与质量要求调节：

• Claude.ai 中手动测试：最轻量，无需配置，迭代快
• Claude Code 中脚本化测试：写自动化用例，改动后可重复验证
• 通过 Skills API 的编程测试：搭评估套件对预定义测试集系统化验证

建议先在一个有挑战的单任务上反复打磨，直到稳定，再扩展覆盖面。这会充分利用 Claude 的上下文学习能力，反馈更直接、速度更快。

三类推荐测试

1. 触发测试：确保该加载时能加载。

   应触发示例：

   • “帮我搭一个新的 ProjectHub 工作区”
   • “我要在 ProjectHub 里创建一个项目”
   • “给 Q4 规划初始化一个 ProjectHub 项目”

   不应触发示例：

   • “旧金山今天天气怎么样？”
   • “帮我写段 Python 代码”
   • “建个电子表格”（除非你的 Skill 管理表格）

2. 功能测试：验证产出正确、调用成功、错误处理到位、边界覆盖充分。

   示例：创建包含 5 个任务的项目；验证项目与任务均创建、属性正确、任务关联完成、无 API 错误。

3. 性能对比：证明“用 Skill”明显优于“裸跑”。

   典型对比：不开 Skill 需多轮对话、调用失败与更高 token；开 Skill 自动执行、澄清更少、零失败、token 更省。

使用 skill-creator

skill-creator 可在 Claude.ai 插件目录找到，也可在 Claude Code 中使用。若你已明确 MCP 与常用工作流，一个下午就能做出可用 Skill（常见耗时 15-30 分钟）。

能力：

• 从自然语言生成 Skill（输出合规的 SKILL.md 与头部信息）
• 给出触发短语与结构建议
• 审查常见问题（描述模糊、触发缺失、结构问题），提醒过度或不足触发风险
• 基于用途建议测试用例

迭代用法：把边界情况与失败案例回饋给 skill-creator，要求改进指定场景的处理。

注意：skill-creator 不会自动跑测试套件或给出量化评估。

依据反馈迭代

• 触发不足：在 description 中加入更多细节与关键词（尤其技术术语）
• 触发过度：加入排除性触发条件，收紧范围，描述更具体
• 执行不稳：改进指令，增强错误处理与验证步骤

分发与共享

Skill 为 MCP 集成补齐“工作流引导”这一关键拼图。带 Skill 的集成，价值显化更快、对比只提供连接能力的竞品更具优势。

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

• 个人用户：下载 Skill 文件夹（可 zip）；在 Claude.ai 上传（设置 > 功能 > Skills）；或放到 Claude Code 的 skills 目录
• 组织范围：管理员可在工作区内统一部署、自动更新与集中管理（2025 年 12 月 18 日上线）

作为开放标准

我们将 Agent Skills 作为开放标准发布。和 MCP 一样，Skill 应在不同平台通用——同一个 Skill，Claude 或其他 AI 平台都能跑。当然，某些 Skill 对特定平台做了深度优化，可在 compatibility 字段标注。

通过 API 使用 Skill

在应用、Agent 或自动化场景，用 API 直接管理与执行 Skill：

• /v1/skills 端点：列出与管理 Skill
• Messages API 的 container.skills 参数：在请求中加载 Skill
• Claude Console：版本控制与管理
• 配合 Claude Agent SDK 构建自定义 Agent

平台选择建议：

• 终端用户直接用 Skill、手动测试与迭代、个人临时工作流：Claude.ai / Claude Code
• 应用内编程调用、大规模生产部署、自动化流水线与 Agent 系统：API

注意：通过 API 使用 Skill 需要开启 Code Execution Tool beta，以提供安全运行环境。详见“Skills API 快速上手”“Agent SDK 中的 Skill”。

当前推荐做法

• 将 Skill 托管到公开 GitHub 仓库，写清 README（面向人类读者），附用法与截图
• 在 MCP 文档中新增板块，链接 Skill，阐明两者配合价值并提供快速上手

安装指南示例：

## 安装 [你的服务] Skill
1. 下载 Skill：
   - 克隆仓库：git clone https://github.com/yourcompany/skills
   - 或从 Releases 页面下载 ZIP
2. 安装到 Claude：
   - 打开 Claude.ai > 设置 > Skills
   - 点击“上传 Skill”，选择 Skill 文件夹（或 zip）
3. 启用 Skill：
   - 打开 [你的服务] Skill 的开关
   - 确认 MCP 服务器已连接
4. 测试：
   - 询问 Claude：“在 [你的服务] 中新建一个项目”

给 Skill 做好定位

怎么描述你的 Skill，决定用户能否理解其价值并愿意试用。

• 讲结果，不讲文件细节：
  • 好：“ProjectHub Skill 让团队几秒搭好完整项目工作区（页面、数据库、模板），无需 30 分钟手动设置。”
  • 差：“ProjectHub Skill 是包含 YAML 与 Markdown 的文件夹，并会调用我们的 MCP 工具。”
• 讲清 MCP + Skill 的故事：MCP 打通服务访问；Skill 教会最佳工作流；组合实现 AI 驱动的项目管理。

常见模式与问题排查

选择切入方式：从问题出发 vs 从工具出发

就像进五金店：有时你带着要解决的问题（“修柜子”），店员给出合适工具；有时你先拿到电钻，再问如何用它解决手头任务。

• 从问题出发：用户描述目标（如“搭建项目工作区”），Skill 负责按正确顺序编排 MCP 调用
• 从工具出发：用户已接好 Notion MCP，Skill 教 Claude 最优工作流与最佳实践

模式 1：顺序工作流编排

## 工作流：新客户入职
### 第 1 步：创建账户
调用 MCP：create_customer（参数：name, email, company）
### 第 2 步：设置支付
调用 MCP：setup_payment_method（等待验证通过）
### 第 3 步：创建订阅
调用 MCP：create_subscription（参数：plan_id, customer_id）
### 第 4 步：发送欢迎邮件
调用 MCP：send_email（模板：welcome_email_template）

要点：明确顺序与依赖；每步做验证；失败时考虑回滚指令。

模式 2：多 MCP 协同

## 设计到开发交接
### 阶段 1：设计导出（Figma MCP）
1. 导出设计素材
2. 生成设计规格文档
3. 创建素材清单
### 阶段 2：素材存储（Drive MCP）
1. 创建项目文件夹
2. 上传素材
3. 生成分享链接
### 阶段 3：任务创建（Linear MCP）
1. 创建开发任务
2. 附素材链接
3. 分配至工程团队
### 阶段 4：通知（Slack MCP）
1. 在 #engineering 发布交接摘要
2. 附素材链接与任务引用

要点：清晰阶段划分；跨 MCP 数据传递；阶段间验证；集中式错误处理。

模式 3：迭代精炼

## 报告生成（迭代式）
### 初稿
1. 通过 MCP 获取数据
2. 生成初版报告
3. 保存临时文件
### 质量检查
1. 运行 scripts/check_report.py
2. 识别问题（缺章节、格式不一致、校验错误）
### 精炼循环
1. 逐项修正
2. 重新生成受影响章节
3. 再次验证
4. 达标为止
### 最终交付
1. 应用最终格式
2. 生成摘要
3. 保存终版

要点：明确质量标准；迭代式改进；用验证脚本判断何时停止。

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

## 智能文件存储
### 决策树
1. 检查类型与大小
2. 决定存储位置：
   - >10MB：云存储 MCP
   - 协作文档：Notion/Docs MCP
   - 代码：GitHub MCP
   - 临时：本地存储
### 执行
- 调用对应 MCP 工具
- 应用服务特有元数据
- 生成访问链接
### 解释
向用户说明为何选择该方案

要点：明确决策标准、备选方案与决策过程透明。

模式 5：领域专业智能

## 金融合规的支付处理
### 处理前（合规检查）
1. 获取交易详情
2. 应用合规规则（制裁名单、辖区许可、风险评估）
3. 记录判定
### 处理中
- 合规通过：调用支付处理、反欺诈检查、执行交易
- 未通过：标记待审查、创建合规案例
### 审计
- 记录所有检查与决策
- 生成审计报告

要点：嵌入领域知识；先合规后执行；完整文档记录与清晰治理。

问题排查

Skill 上传失败

• 报错：Could not find SKILL.md in uploaded folder
  • 原因：文件名不精确为 SKILL.md
  • 修复：重命名为 SKILL.md（大小写敏感）；用 ls -la 检查
• 报错：Invalid frontmatter
  • 原因：YAML 格式错误（缺分隔符、引号未闭合等）
  • 正确示例：

    ---
    name: my-skill
    description: Does things
    ---

• 报错：Invalid skill name
  • 原因：名字含空格或大写
  • 正确示例：my-cool-skill

Skill 不触发

• 症状：永不自动加载
• 修复：收紧与补充 description；加入用户会说的触发短语；涉及文件类型请注明
• 调试：直接问 Claude——“你什么时候会用 [skill 名] 这个 Skill？”根据复述内容调整

Skill 触发过度

• 症状：无关话题也加载
• 修复：加排除性触发条件，描述更具体、明确范围
• 示例：从“处理文档”收紧到“处理 PDF 格式的法律文件，用于合同审查；不要用于简单数据浏览（用 data-viz skill）”

MCP 连接问题

• 症状：Skill 加载，但 MCP 调用失败
• 排查：
  • 确认 MCP 在 Claude.ai（设置 > 扩展）显示“已连接”
  • 检查认证：API key 有效、权限范围正确、OAuth 刷新
  • 单独测试 MCP：让 Claude 直接调用服务（不通过 Skill）
  • 核对工具名称大小写与文档

指令未被遵守

• 原因：指令冗长、关键信息被淹没、措辞含糊
• 修复：
  • 保持简洁，使用项目符号与编号
  • 关键指令前置并必要时重复
  • 对关键校验考虑用脚本做确定性检查（代码胜于自然语言）

模型“偷懒”

• 建议在用户提示中加入执行提示（如“质量优先、请勿跳过验证”），用户提示比 SKILL.md 中效果更佳。

上下文过大

• 症状：响应变慢、质量下降
• 原因：Skill 内容过大/同时启用过多 Skill/未做分层加载
• 修复：精简 SKILL.md（建议控制在 5,000 词以内）；细节移至 references/ 并链接引用；减少同时启用的 Skill 数量；按需启用或打包为“Skill 套装”。

参考资源

从最佳实践入手，必要时再查 API。

• Anthropic 官方文档与博客：最佳实践指南、Skills 文档、API 参考、MCP 文档、Agent 能力工程实践
• 示例 Skill 仓库：GitHub（anthropics/skills）——可克隆、定制与当模板用
• skill-creator：Claude.ai 内置，Claude Code 可用；支持生成与审查 Skill
• 社区与支持：Claude Developers Discord、社区论坛、GitHub Issues（anthropics/skills/issues）

提交问题请附：Skill 名称、错误信息与复现步骤。

附录 A：快速检查清单

开发前：

• 明确 2-3 个具体用例
• 列出所需工具（内置/MCP）
• 阅读本指南与示例 Skill
• 规划文件夹结构

开发中：

• 文件夹用 kebab-case 命名
• SKILL.md 文件存在且拼写正确
• YAML 头部含 --- 分隔符
• name 字段符合规范（kebab-case、无空格/大写）
• description 同时写“做什么”和“何时用”
• 无 XML 尖括号
• 指令清晰可操作，包含错误处理与示例
• references/ 中的资料有清晰链接

上传前：

• 测试明确任务与换种说法的触发
• 验证不会被无关话题触发
• 功能测试通过、工具集成正常
• 打包为 zip（如需）

上传后：

• 在真实对话中试用
• 监控触发不足/过度
• 收集用户反馈
• 迭代 description 与指令，更新 metadata 版本号

附录 B：YAML 头部信息参考

必填字段：

---
name: skill-name-in-kebab-case
description: 做什么用、什么时候用；包含具体触发短语。
---

全部可选字段示例：

name: skill-name
description: [必填描述]
license: MIT
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
  author: CompanyName
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com

安全须知：

• 允许：标准 YAML 类型与自定义 metadata 字段、最长 1024 字的描述
• 禁止：XML 尖括号；在 YAML 中执行代码；Skill 名以 “claude” 或 “anthropic” 开头

附录 C：完整 Skill 示例

查看可投产的示例（文档类、工作流模式、合作伙伴目录等）：涵盖 PDF/DOCX/PPTX/XLSX 创建、各类工作流编排，以及来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等的伙伴 Skill。仓库持续更新，可直接克隆、修改或作为模板使用。

结语

这就是今天的完整解读。

如果你对构建 AI 智能体与工作流工程感兴趣，欢迎点赞与关注。