Anthropic 官方发布：Claude Skills 构建指南（全文译版）

正文

Anthropic 刚刚官方发布了 33 页的 Claude Skills 构建指南，以下为全文中文译版。

技能（Skill）其实就是一套指令——打包成一个简单的文件夹——用来教 Claude 怎么处理特定任务或工作流程。这是你自定义 Claude 最有力的方式之一。

你有没有遇到过这种情况：每次跟 Claude 对话，都要重新解释你的偏好、流程和专业背景？有了技能，你只需要教一次，以后每次都能直接用上。

什么时候用技能最合适？ 就是当你有可以重复执行的工作流程时，比如：

• 根据设计稿生成前端界面
• 用固定的方法论做研究调查
• 按照团队风格指南写文档
• 协调多个步骤的复杂流程

技能跟 Claude 的内置功能（比如执行代码、创建文档）搭配起来效果很好。如果你在做 MCP 集成，技能还能帮你把原始的工具访问能力，变成可靠、顺畅的工作流程。

读完这份指南，你会学到：

• 技能的技术要求和最佳实践
• 独立技能和 MCP 增强型工作流的设计模式
• 我们观察到的那些真正有效的做法
• 怎么测试、迭代、发布你的技能

这份指南适合谁读？

• 想让 Claude 按固定流程工作的开发者
• 想让 Claude 遵循自己习惯的高级用户
• 想在团队/组织内统一 Claude 使用方式的管理者

两条阅读路径： 只做独立技能？重点看"基础知识"和"规划与设计"部分。 想在 MCP 上叠加技能？"技能 + MCP"和第五章的设计模式更适合你。

预计投入： 读完这份指南后，配合 skill-creator 工具，通常 15-30 分钟就能做出你第一个能用的技能。

第一章：基础知识

技能到底是什么？

技能就是一个文件夹，里面放着：

| 文件/文件夹 | 是否必须 | 作用 | |---|---|---| | SKILL.md | ✅ 必须 | 带 YAML 前置信息的 Markdown 格式指令 | | scripts/ | 可选 | 可执行代码（Python、Bash 等） | | references/ | 可选 | 按需加载的参考文档 | | assets/ | 可选 | 输出用的模板、字体、图标等 |

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

技能用三层结构来组织内容：

• 第一层（YAML 前置信息）：每次都会加载到 Claude 的系统提示里。内容要精简——让 Claude 知道"这个技能是做什么的、什么时候该用它"就够了，不需要把所有东西都塞进来。
• 第二层（SKILL.md 正文）：当 Claude 觉得当前任务跟这个技能有关，才会加载完整指令。
• 第三层（链接文件）：放在技能文件夹里的其他文件，Claude 可以按需查阅。

这种分层设计的好处：既省 token，又能保留足够的专业深度。

2. 可组合性（Composability）

Claude 可以同时加载多个技能。你的技能要能跟其他技能和平共处，别假设自己是唯一被启用的那个。

3. 可移植性（Portability）

在 Claude.ai、Claude Code 和 API 里，技能的工作方式完全一样。写一次，到处能用——前提是运行环境支持技能所需的依赖。

面向 MCP 开发者：用技能增强 MCP

技能其实就是 MCP 的"知识层"——把你已经知道的工作流程和最佳实践固化下来，让 Claude 能够一致地应用它们。

| MCP（连接层） | 技能（知识层） | |---|---| | 把 Claude 连接到你的服务（Notion、Asana、Linear 等） | 教 Claude 怎么有效地使用这些服务 | | 提供实时数据访问和工具调用能力 | 固化工作流程和最佳实践 | | Claude 能做什么 | Claude 应该怎么做 |

没有技能时，用户可能遇到的问题：

• 连上了 MCP，但不知道下一步该咋办
• 不断发来"怎么用你的集成做 X"的支持提问
• 每次对话从头开始，结果每次都不一样
• 用户会把问题归咎于 MCP 连接器，但根本原因其实是缺少工作流程指引

有了技能之后：

• 预置的工作流程在需要时自动激活
• 工具调用稳定可靠
• 最佳实践内嵌在每次交互里
• 新用户的学习成本大幅降低

第二章：规划与设计

第一步：从用例出发

在写任何代码之前，先想清楚你的技能要解决的 2-3 个具体场景。

问自己这几个问题：

• 用户想达成什么目标？
• 这需要哪些多步骤的工作流程？
• 需要哪些工具（Claude 内置的，还是 MCP 的）？
• 需要嵌入哪些领域知识或最佳实践？

三类常见用例

第 1 类：文档和素材创建

适合场景：创建一致的高质量输出，比如文档、演示文稿、应用、设计、代码等。

关键做法：

• 嵌入风格指南和品牌规范
• 用模板结构保证输出一致
• 最终确认前做质量清单检查
• 不需要外部工具——用 Claude 的内置能力就够

第 2 类：工作流程自动化

适合场景：多步骤流程，需要一致的执行方式，可能跨多个 MCP 服务器协调。

关键做法：

• 带验证节点的分步工作流
• 常见结构的模板
• 内置审查和改进建议
• 迭代优化循环

第 3 类：MCP 增强

适合场景：为 MCP 服务器的工具访问能力加上工作流程引导。

关键做法：

• 按顺序协调多个 MCP 调用
• 嵌入领域专业知识
• 提供用户本来需要手动指定的上下文
• 处理常见 MCP 问题

第二步：定义成功标准

量化指标：

• 技能在 90% 的相关查询中触发
• 工作流程在 X 次工具调用内完成
• 每个工作流程 0 次 API 调用失败

定性指标：

• 用户不需要提示 Claude 下一步该做什么
• 工作流程无需用户纠正就能跑完
• 跨会话结果保持一致

技术要求

文件夹结构

your-skill-name/
├── SKILL.md              # 必须——主技能文件
├── scripts/              # 可选——可执行代码
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选——参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选——模板等资源
    └── report-template.md

几条必须遵守的规则

• SKILL.md 必须精确命名（区分大小写）
• 技能文件夹用 kebab-case：notion-project-setup（不能有空格、大写或下划线）
• 技能文件夹内不要放 README.md

YAML 前置信息：最关键的部分

最简格式：

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

description 字段怎么写——好的写法：

# 好——具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。
  当用户上传 .fig 文件，或者问"设计规格"、"组件文档"、
  "设计转代码交接"时使用。

# 好——包含触发词
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。
  当用户提到"冲刺"、"Linear 任务"、"项目规划"，
  或者要求"创建工单"时使用。

❌ 不好的写法：

# 太模糊
description: 帮助处理项目。

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

# 太技术化，用户不会这么说
description: 实现具有层次关系的 Project 实体模型。

写主体指令的最佳实践

✅ 要具体，要说清楚怎么操作：

运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
如果验证失败，常见原因有：
- 缺少必填字段（把它加到 CSV 里）
- 日期格式不对（要用 YYYY-MM-DD）

❌ 别含糊其词：

继续之前请先验证数据。

✅ 要包含错误处理：

## 常见问题

### MCP 连接失败
看到 "Connection refused" 时：
1. 确认 MCP 服务器在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重连：设置 > 扩展 > [你的服务] > 重新连接

SKILL.md 要保持聚焦：核心指令放在 SKILL.md，详细文档移到 references/ 里，通过链接引用。

第三章：测试与迭代

推荐测试方法

1. 触发测试

应该触发：
- "帮我设置一个新的 ProjectHub 工作区"
- "我需要在 ProjectHub 里创建个项目"

不应该触发：
- "旧金山今天天气怎么样？"
- "帮我写个 Python 脚本"

2. 功能测试

验证技能输出是否正确，步骤是否完整，API 调用是否成功。

3. 对比测试

对比有技能 vs. 无技能的关键指标：用户消息数、API 调用失败次数、token 消耗。

专业技巧：先把一个难题跑通，再推广 最高效的做法是：先针对一个最具挑战的任务反复迭代，直到 Claude 成功搞定，再把这个成功方案提炼成技能。这样能充分利用 Claude 的上下文学习能力，比广撒网测试更快得到有效反馈。

根据反馈持续迭代

触发不足的信号：

• 技能该自动加载时没加载
• 用户手动开启它

→ 解决办法：在 description 里加更多细节和关键词

触发过度的信号：

• 技能在不相关的查询里也触发了
• 用户禁用了它

→ 解决办法：添加负触发词，让描述更具体

执行问题的信号：

• 结果不一致
• API 调用失败

→ 解决办法：改进指令，加上错误处理

第四章：发布与分享

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

1. 下载技能文件夹
2. 压缩成 zip
3. 通过 Claude.ai 的 设置 > 功能 > 技能 上传
4. 或放到 Claude Code 的技能目录里

怎么介绍你的技能：

聚焦结果，而非功能：

✅ 好的写法：

"ProjectHub 技能让团队能在几秒钟内建立完整的项目工作区——
包括页面、数据库和模板——而不是花 30 分钟手动配置。"

❌ 不好的写法：

"ProjectHub 技能是一个包含 YAML 前置信息和 Markdown 指令
并调用我们 MCP 工具的文件夹。"

第五章：模式与故障排查

选你的出发点：问题优先 vs. 工具优先

• 问题优先："我需要设置项目工作区" → 技能按正确顺序协调 MCP 调用。用户说目标，技能搞定工具。
• 工具优先："我已经连上了 Notion MCP" → 技能教 Claude 最佳工作流程和实践。用户有访问权限，技能提供专业知识。

模式一：顺序工作流编排

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

关键技术：步骤顺序要明确、步骤间依赖关系要写清楚、每个阶段要有验证、失败时要有回滚指令。

模式二：多 MCP 协调

适合场景： 工作流需要跨多个服务（设计导出→资产存储→创建任务→发送通知）。

关键技术：阶段分隔要清晰、MCP 间的数据传递要明确、进下一阶段前要验证、错误处理要集中。

模式三：迭代式优化

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

关键技术：质量标准要明确、迭代改进要有节奏、验证脚本要好用、要知道什么时候停。

进阶技巧：对于关键验证步骤，可以考虑打包一个脚本来做程序化检查，而不是靠自然语言描述。代码的执行是确定的，语言的理解不是。

模式四：情境感知工具选择

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

关键技术：决策标准要清晰、要有备用选项、选择理由要透明。

模式五：特定领域智能

适合场景： 技能在工具访问之外还需要提供专业知识。

关键技术：领域专业知识要嵌入逻辑、行动前要合规检查、记录要完整、治理边界要清晰。

故障排查

技能不触发：

自查清单：

• 描述是不是太笼统？
• 有没有用户可能实际说的触发词？
• 如果涉及文件类型，有没有提到？

调试技巧：问 Claude："你什么时候会用 [技能名] 这个技能？" Claude 会引用 description 里的内容。

技能触发太频繁：

解决方法：

1. 加负触发词：

description: 用于 CSV 文件的高级数据分析，适合统计建模、回归、聚类分析。
  不要用于简单数据探索（请改用 data-viz 技能）。

1. 描述更具体，把不该触发的情况明确排除。

指令没有被遵守：

常见原因：

1. 指令太冗长 → 保持简洁，详细参考文档移到单独文件
2. 关键指令被埋没 → 重要内容放最前面，用 ## 重要 标题
3. 语言模糊 → 改为精确的验证条件

上下文太大导致响应变慢或质量下降：

解决方法：

1. 精简 SKILL.md（控制在 5,000 个词以内）
2. 减少同时启用的技能数量（超过 20-50 个要考虑精简）
3. 用渐进式披露，详细文档移到 references/

第六章：资源与参考

官方资源：

• Best Practices Guide（最佳实践指南）
• Skills Documentation（技能文档）
• API Reference（API 参考）
• MCP Documentation（MCP 文档）

示例技能仓库：

• GitHub：anthropics/skills
• 包含 Anthropic 创建的技能，可以直接自定义用

skill-creator 工具：

• 内置于 Claude.ai，也可用于 Claude Code
• 可以从描述生成技能
• 提供审查和改进建议
• 使用方法："用 skill-creator 帮我构建一个技能"

附录A：快速检查清单

上传技能前后，用这个清单验证一遍。

开始之前

• 确定了 2-3 个具体用例
• 确定了所需工具（内置还是 MCP）
• 看过这份指南和示例技能
• 规划好了文件夹结构

开发过程中

• 文件夹用了 kebab-case 命名
• SKILL.md 文件存在（精确拼写，区分大小写）
• YAML 前置信息有 --- 分隔符
• name 字段：kebab-case、无空格、无大写
• description 同时写了"做什么"和"什么时候用"
• 没有 XML 标签（< >）
• 指令清晰、可操作
• 包含了错误处理
• 参考资料有清晰的链接

上传后

• 在真实对话里测试过
• 观察了过度/不足触发的情况
• 收集了用户反馈
• 根据反馈迭代了 description 和指令

附录B：YAML 前置信息参考

---
name: skill-name-in-kebab-case
description: 它做什么以及什么时候用。包含具体的触发短语。
---

# 完整字段
name: skill-name
description: [必填描述]
license: MIT                      # 可选：开源协议
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
compatibility: Requires network access  # 可选：运行环境需求
metadata:
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]

禁止的：

• XML 尖括号（< >）——安全限制
• 以 "claude" 或 "anthropic" 开头的技能名（保留词）