Anthropic：技能构建内部指南
我写 Claude 工具已经有一段时间了。Claude Code、提示命令、Obsidian 集成。但 Skills 是我一直搁置的东西，因为它们感觉解释得不够——就像文档假设你已经知道自己在做什么一样。
然后 Anthropic 发布了一份完整的内部指南。30 页。每一个模式、每一个陷阱、每一份清单。我读了全文。
以下是真正重要的内容。
1、Skill 到底是什么
一个 Skill 就是一个文件夹。就这样。
那个文件夹里有一个 SKILL.md 文件——主要的指令文件——以及可选的一些脚本、参考文档或资产模板。你把文件夹压缩，通过 Settings > Capabilities > Skills 上传到 Claude.ai，从那时起 Claude 就知道如何处理你描述的任何工作流。
思路很简单：不用在每次对话中重新解释你的流程，你只需教 Claude 一次。Sprint 规划、文档生成、入职工作流、API 集成——任何可重复的东西都变成一个 Skill。
文件夹结构如下：
your-skill-name/
├── SKILL.md ← 必需
├── scripts/ ← 可选
├── references/ ← 可选
└── assets/ ← 可选
Skills 在 Claude.ai、Claude Code 和 API 中的工作方式完全相同。构建一次，到处使用。
2、三层加载系统
这是大多数人忽略的部分，它解释了很多关于为什么某些 Skills 有效而其他的无效。
Skills 分三层加载：
第 1 层 — YAML frontmatter。 始终存在于 Claude 的系统提示中，每次对话都有。这是 Claude 决定你的 Skill 是否相关的地方。它只有几行，这就是关键——它保持较低的 token 使用量。
第 2 层 — SKILL.md 正文。 当 Claude 认为 Skill 适用时加载。这是你实际指令所在的地方。
第 3 层 — references/ 中的链接文件。 仅在 Claude 需要它们时加载。深度文档、API 模式、边界情况指南。
这个系统的后果是：你的 frontmatter 描述是你整个 Skill 中最重要的东西。如果它不好，Claude 永远不会加载这个 Skill。如果没人读，指令再好也没用。
3、编写 SKILL.md 文件
该文件有两个部分：YAML 头部（frontmatter）和正文（你的实际指令）。
3.1 Frontmatter
最小有效格式：
---
name: your-skill-name
description: What it does and when to use it.
---
name 字段必须是 kebab-case。不能有空格、大写字母或下划线。my-cool-skill 可以。My Cool Skill 不行。
description 字段是大多数人出错的地方。它必须包含两件事：Skill 做什么，以及何时使用它。两者都要。不能只有一个。
好的描述示例：
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".
Manages Linear project workflows including sprint planning, task creation,
and status tracking. Use when user mentions "sprint", "Linear tasks",
"project planning", or asks to "create tickets".
不起作用的描述示例：
Helps with projects.
Creates sophisticated multi-page documentation systems.
第一个太模糊了。第二个没有触发短语——Claude 不知道什么时候加载它。
你还可以添加可选字段：
---
name: my-skill
description: ...
license: MIT
metadata:
author: Your Name
version: 1.0.0
mcp-server: your-server-name
---
一个硬性规则：frontmatter 中任何地方都不能有 XML 尖括号。这是安全限制，因为 frontmatter 会直接进入 Claude 的系统提示。
3.2 指令正文
在 frontmatter 之后，用纯 Markdown 编写指令。指南推荐这样的结构：
# Skill Name
## Step 1: First thing
Clear explanation. What to do, what success looks like.
## Step 2: Next thing
...
## Examples
User says: "Set up a new project"
Actions:
1. Fetch existing projects via MCP
2. Create new project with provided parameters
Result: Project created with confirmation link
## Troubleshooting
Error: Connection refused
Cause: MCP server isn't running
Solution: Settings > Extensions > [Service] > Reconnect
要具体。"Validate the data before proceeding" 对 Claude 来说毫无意义。"Run python scripts/validate.py --input {filename} and if it fails, check for missing required fields or date formats" 是 Claude 可以真正执行的内容。
保持 SKILL.md 聚焦，将深度文档移到 references/。从指令中链接到它。这就是渐进式披露系统的工作方式。
4、三种 Skill 类别
Anthropic 从早期构建者中识别出三个主要用例：
类别 1：文档和资产创建。 生成一致输出的 Skills——文档、演示文稿、代码、设计。frontend-design Skill 就属于这里。关键模式：嵌入样式指南，使用模板，在完成前运行质量检查。不需要外部工具。
类别 2：工作流自动化。 具有一致方法的多步骤流程。skill-creator Skill 本身就是这里的例子。关键模式：带有验证门的分步进行，迭代优化循环，内置改进建议。
类别 3：MCP 增强。 在现有 MCP 服务器连接之上叠加工作流指导。Sentry 的代码审查 Skill 就是例子——它使用 Sentry 的 MCP 来分析 GitHub PR 中的 bug。关键模式：序列化多个 MCP 调用，嵌入领域专业知识，处理常见错误。
5、Skills + MCP
如果你已经有一个 MCP 服务器连接到 Claude，Skills 就是缺失的那块拼图。
指南使用了厨房的类比。MCP 提供厨房——工具、食材、访问一切。Skills 提供食谱——关于实际要做什么的分步指令。
没有 Skills，用户连接你的 MCP 服务器后不知道该做什么。他们不一致地提示，得到不一致的结果，最终责怪连接器。
有了 Skills，工作流自动激活。Claude 知道序列。领域专业知识被嵌入了。
Anthropic 识别了五种适用于 MCP 增强 Skills 的模式：
模式 1：顺序工作流编排。 当步骤必须按顺序发生时。创建账户 → 设置支付 → 创建订阅 → 发送欢迎邮件。每一步在进入下一步之前进行验证，如果出现问题还有回滚指令。
模式 2：多 MCP 协调。 当工作流跨多个服务时。从 Figma 导出 → 上传到 Drive → 在 Linear 中创建任务 → 在 Slack 通知。清晰的阶段分离，服务之间的数据传递，集中式错误处理。
模式 3：迭代优化。 当质量通过迭代提升时。生成初稿 → 验证 → 识别问题 → 修复 → 重新验证 → 重复直到达到阈值。适用于报告、文档、任何有明确质量标准的东西。
模式 4：上下文感知工具选择。 当相同的结果需要根据处理内容使用不同的工具。文件超过 10MB？使用云存储。协作文档？使用 Notion。代码文件？使用 GitHub。Skill 做出决定并向用户解释原因。
模式 5：领域特定智能。 当 Skill 添加超越仅仅运行工具的专业知识时。支付处理 Skill 在交易前运行合规性检查。法律 Skill 应用司法管辖区规则。专业知识被嵌入到逻辑中，而不是留给用户。
6、测试你的 Skill
指南将测试分为三个方面。
触发测试。 你的 Skill 是否在应该加载时加载？运行 10-20 个应该触发它的查询，跟踪有多少实际触发了。同时测试它在不相关查询上不会触发。目标：相关查询的准确率达到 90%，明确不相关的查询达到 0%。
功能测试。 Skill 是否产生正确的输出？将同一请求运行 3-5 次并比较结果。计算工具调用次数。监控 API 错误。
性能比较。 Skill 实际上比没有它更好吗？比较有和没有 Skill 激活时的 token 使用量、来回消息数量和失败的 API 调用。
指南中还有一个实用的调试技巧：直接问 Claude，"When would you use the [skill name] skill?" Claude 会把描述引用给你。如果答案揭示了差距，你就确切知道该修复什么。
一个对迭代很有效的模式：先让 Claude 在单个困难任务上成功，然后将该方法提取为 Skill。不要从第一天就构建广泛的覆盖范围。先让一件事可靠地工作，然后再扩展。
7、常见故障和修复
Skill 无法上传。 通常是命名问题。文件必须完全是 SKILL.md——区分大小写，没有变体。文件夹必须是 kebab-case。如果你看到 "Invalid frontmatter"，检查你的 YAML 分隔符（--- 行）并确保没有未闭合的引号。
Skill 不触发。 描述太模糊或缺少触发短语。添加用户实际会说的具体语言。问 Claude 什么会触发这个 Skill——它的答案会告诉你缺少什么。
Skill 触发太多。 明确添加负面触发器："Do NOT use for X — use the Y skill instead." 对范围更具体。
MCP 调用失败但 Skill 加载了。 先独立测试 MCP 连接。让 Claude 在没有 Skill 的情况下直接调用 MCP 工具。如果那也失败了，问题出在认证或 MCP 服务器上，而不是你的 Skill。
Claude 加载了 Skill 但忽略了指令。 几个原因：指令太长（将细节移到 references/），关键步骤被埋没了（把它们放在顶部），语言太模糊（明确"validate"的含义）。对于真正关键的检查，考虑使用验证脚本——代码是确定性的，自然语言不是。
上下文感觉慢或降级。 保持 SKILL.md 在 5,000 词以内。如果你同时启用了超过 20-50 个 Skills，考虑精简。将详细文档移到 references/ 并链接到它。
8、分发你的 Skill
目前（截至 2026 年初），分发流程是：
- 将 Skill 托管在 GitHub 上——公共仓库，为人类访问者提供清晰的 README，带有截图的示例使用
- 如果你有 MCP 文档，将 Skill 添加到其中
- 用户下载文件夹，压缩，通过 Settings > Capabilities > Skills 上传
组织管理员还可以在工作区范围部署 Skills，具有自动更新和集中管理——这在 2025 年 12 月就推出了。
对于在 API 上构建的团队，Skills 可通过 /v1/skills 端点访问，并可通过 container.skills 参数附加到 Messages API 请求。它们需要 Code Execution Tool beta。
在撰写关于你的 Skill 的内容时——在 README 或其他任何地方——描述结果，而不是机制。"Enables teams to set up complete project workspaces in seconds instead of spending 30 minutes on manual setup" 比 "a folder containing YAML frontmatter and Markdown instructions" 更有说服力。
9、清单（浓缩版）
开始之前：确定 2-3 个具体用例。知道需要哪些工具。
开发期间：kebab-case 文件夹名。精确的 SKILL.md 拼写。带 --- 分隔符的 YAML。描述包括做什么和何时做。任何地方都没有 XML 标签。清晰、具体的指令，带有错误处理和示例。
上传之前：在明显的和改述的查询上测试触发。验证它在不相关主题上不会触发。测试实际工作流。
上传之后：监控触发不足/过度。收集反馈。迭代描述和指令。
阅读整个指南后最突出的一点是，有多少权重集中在一个字段上——描述。其他一切都可以优化。但如果描述没有告诉 Claude 何时加载 Skill，这一切都不重要。
先把那个做对。其他一切都从那里开始。
原文链接: I Read Anthropic's Internal Guide on Building Claude Skills. Here's Everything You Need to Know.
汇智网翻译整理，转载请标明出处