娱乐盒子
79.37M · 2026-03-10
近几个月 AI 领域 “Skill” 的概念非常火热，社区也已有很多对Skill和MCP等概念的对比解读，以及如何构建高效能 AI 技能的讨论与实践分享，但作为其标准定义者，官方一直处于只有规范没有指南的情况。间隔4个月后，Anthropic 才首次下场发布了一份几十页的详尽 Skill 最佳构建指南，我们不妨花几分钟再从官方权威的“第一性视角”来完整回顾一下Skill的实践说明，看看我们自己的个人理解和标准设计者之间的理解是否相同。
本文从官方指南中提炼总结了关键内容供大家进行快速进行了解，包括Skill 的官方定义、设计原则、关键实现、评估迭代及常见误区等部分。如果想要完整了解Skill的设计和实践指南，推荐阅读官方的完整白皮书。
resources.anthropic.com/hubfs/The-C…
首先，我们需要明确 Anthropic 对 Skill 的官方定义。它不是一个简单的提示（Prompt），也不是一个孤立的工具（Tool）。
一个标准的 Skill 是一个包含以下内容的文件夹：
your-skill-name/
├── SKILL.md # **必需**：核心指令文件，包含 YAML 元数据
├── scripts/ # 可选：可执行脚本 (Python, Bash 等)
├── references/ # 可选：供 Skill.md 按需读取的参考文档
└── assets/ # 可选：用于生成结果的模板、图标等资源
官方强调了 Skill 设计的三大核心原则，理解它们是构建高效 Skill 的前提。
这是 Skill 最精妙的设计，旨在最大化能力、最小化 Token 消耗。它分为三层：
references/ 或 scripts/ 目录中的文件，只有在 Skill 指令引导 Claude去读取时才会被加载。Agent 可以同时加载多个 Skill。这意味着你的 Skill 需要像一个行为良好的微服务，专注于做好一件事，并能与其他 Skill 协同工作，而不是假设自己是系统中唯一的能力。
例如：
原则三：可移植性 (Portability)
一次创建，处处运行。一个标准的 Skill 能够在所有支持的环境中（如 Claude.ai 网页版、Claude Code 开发环境，以及通过 API 调用）无需修改即可一致地工作，前提是目标环境满足其依赖项（如特定的系统软件包或网络访问）。
简单来说，Skill 是连接“用户意图”和“底层工具”的智能胶水层。它教会Agent不仅“能做什么”，更重要的是“应该如何一步步地、高质量地完成”。
为了更清晰地理解 Skill 的定位，我们可以通过一个简单的表格来对比它与 Prompt 和 Tool 的区别：
| 对比维度 | Skill (技能) | Prompt (提示) | Tool / Function (工具/函数) |
|---|---|---|---|
| 核心本质 | 一个工作流 (Workflow) 的知识封装 | 一次性给予模型的指令 (Instruction) | 一个模型可以调用的具体能力 (Capability) |
| 形态 | 结构化的文件夹，包含指令、脚本、文档 | 自然语言文本 | 定义清晰的 API 接口 (如 OpenAPI Schema) |
| 解决的问题 | “应该如何做” (How to do it) | “这次要做什么” (What to do now) | “可以做什么” (What can be done) |
| 典型场景 | 多步骤、可复用的流程，如“根据公司风格生成周报”、“执行代码审查并自动修复 Sentry 告警” | 临时的、一次性的任务，如“帮我总结这段文字” | 原子化的、确定性的操作，如“查询天气”、“发送邮件” |
| 上下文消耗 | 低。通过“渐进式披露”按需加载，仅在触发时消耗少量 Token | 高。每次都需要在上下文中完整提供 | 中等。调用时消耗接口定义的 Token |
官方用一个生动的“厨房类比”阐明了 Skill 与工具调用 (Tool Use / MCP) 的关系：
什么时候需要 Skill？
当你发现自己或团队在可重复的工作流上花费大量时间时，就应该考虑构建 Skill。例如：
如果没有 Skill，用户即使连接了工具，也需要每次在对话中从头解释“该做什么”和“该怎么做”，导致结果不一致、效率低下。Skill 将这些隐性的工作流知识显性化、标准化，从而实现真正的自动化。
官方指南用大量篇幅阐述了从设计到发布的完整生命周期。我们将其提炼为工程师最关心的几个核心实践维度。
一个健壮的 Skill 应该遵循以下软件工程原则：
SKILL.md 的 description 字段就是这个契约最重要的部分。核心要点：把 Skill 当作一个“ 微服务 ”来设计。 它的 SKILL.md 就是 API 文档，scripts/ 目录就是业务逻辑实现，references/ 则是外部依赖文档。
一个 Skill 的核心在于其文件结构和 SKILL.md 的撰写质量。
notion-project-setup。禁止使用空格、下划线或大写字母。SKILL.md (区分大小写)。README.md: 技能文件夹内不应包含 README.md，所有面向 Claude 的文档都应在 SKILL.md 或 references/ 目录中。SKILL.md 文件头部的 YAML Front Matter 是整个 Skill 中最重要的部分，它直接决定了 Claude 是否会以及何时加载你的 Skill。
最小必需格式:
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
如何编写高效的 description
description 字段是渐进式披露的第一环，其核心任务是清晰地告诉Agent 两件事：这个 Skill 是做什么的，以及什么时候应该使用它。除此之外，再辅助对一些关键能力进行补充说明。
官方推荐结构: [它做什么] + [何时使用] + [关键能力]
好的示例:
# Good: 具体且可操作，包含触发短语
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".
# Good: 包含用户可能提及的任务
description: 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".
糟糕的示例:
# Bad: 过于模糊
description: Helps with projects.
# Bad: 缺少触发条件
description: Creates sophisticated multi-page documentation systems.
SKILL.md 主体：清晰的指令是关键在 YAML 元数据之后，便是用 Markdown 编写的实际指令。官方推荐包含指令 (Instructions)、示例 (Examples) 和故障排除 (Troubleshooting) 三个部分。
指令编写最佳实践:
python scripts/validate.py --input {filename} 来检查数据格式”。references/ 目录，应在指令中明确引导 Agent 何时去查阅它们。例如，“在编写查询前，请查阅 references/api-patterns.md 以了解速率限制指南”。SKILL.md 主体指令的简洁性，将冗长的文档、复杂的示例或详细的 API 定义移至 references/ 目录中，并通过链接引用。当 Skill 开始执行真实世界的操作时，安全成为第一要务。
SKIL.md 的 Troubleshooting 部分中定义清楚。description 字段也是一道安全防线。通过精确定义触发条件，可以防止 Skill 被恶意或无意地用于其设计范围之外的任务。与传统软件测试类似，Skill 的评估也需要覆盖不同层面，官方推荐了三种测试方案：
| 测试类型 | 核心目标 | 方法示例 |
|---|---|---|
| 触发测试 (Triggering Tests) | 确保 Skill 在正确的时间被加载，且不会在不相关时被误触发。> 需要准备一个测试用例集，包含应触发和不应触发的各类用户查询。 | - 正向用例: “帮我规划一个冲刺” -> 应该触发 sprint-planning skill。- 反向用例: “今天天气怎么样” -> 不应该触发 sprint-planning skill。 |
| 功能测试 (Functional Tests) | 验证 Skill 的工作流是否能产出正确、API 调用是否成功，边缘情况是否能被妥善处理，且能够保持一致的结果。 | 给定输入（如项目名），断言 Skill 是否成功调用了所有预期的 API，并创建了符合规范的产出物。 |
| 性能对比 (Performance Comparison) | 证明使用 Skill 比手动操作或纯 Prompt 更优。 | 将使用 Skill 前后的情况进行对比，用预设的成功指标（如完成任务所需的消息轮次、令牌消耗、失败率）来量化 Skill 带来的价值。 |
实践技巧：Anthropic 推荐一个非常有效的方法——不要一开始就追求全面的测试覆盖率。更有效的方法是，先聚焦于一个有代表性且稍有挑战性的任务，通过与Agent的反复对话、调试，直到这个任务可以被完美解决。然后，将这个成功的交互过程和最终的解决方案让AI帮我们提炼、固化成一个 Skill。当你有了一个坚实的基础后，再扩展到更多的测试用例来保证其泛化能力。在我们使用OpenClaw或TraeCli等Agent时都可以广泛使用该技巧。
一个完整的 Skill 生命周期除了测试外，还包括与外部工具的集成、持续的测试迭代以及最终的分发共享:
与工具 ( MCP ) 衔接: Skill 通过指令编排对 MCP 工具的调用。指令需要明确每个步骤应调用哪个工具、传递什么参数，并对预期输出进行说明。
错误与异常处理: 健壮的 Skill 必须定义失败路径。例如，如果 API 调用失败，是应该重试、回滚，还是向用户请求更多信息？这些都应在 SKILL.md 的“故障排除”部分明确。
安全考量:
< >)，以防止指令注入攻击。allowed-tools 字段限制该 Skill 能够调用的工具范围，实现最小权限原则。当团队开始大规模构建和使用 Skill 时，规范化的管理变得至关重要。
版本规范: 建议在 SKILL.md 的元数据中加入 version 字段，便于管理和迭代。
文档化: 虽然 Skill 文件夹内不应有 README.md，但在托管 Skill 的代码仓库中，需要一个清晰的 README.md 文件来面向人类开发者，解释该 Skill 的用途、安装方法和使用示例。
可复用 封装 与团队协作:
误区一：把 Skill 当作一堆 Prompt 的集合。
误区二：无契约的自由输入。
description 就是 Skill 的 API 契约。必须清晰地定义它能做什么、不能做什么，以及何时被触发。误区三：没有安全边界。
误区四：缺少评估闭环。
误区五：版本漂移与无人维护。
从触发和执行的维度，也可以将几个误区总结如下:
触发相关误区
描述过于笼统: 如 description: "Helps with projects"，导致 Claude 无法判断何时使用。
缺少具体触发短语: 没有在 description 中包含用户可能实际使用的词汇或任务描述。
触发过于频繁: description 涵盖范围太广，导致 Skill 在不相关的查询中也被加载。解决方案：在描述中加入负向触发器，如 Do NOT use for...，或让范围更具体，如从“处理文档”细化为“为合同审查处理 PDF 法律文件”。
执行相关误区
SKILL.md 中，而不使用 references/ 目录进行拆分，导致性能下降和模型“惰性”。如果你想快速开始，官方建议了这样一个最小化但完整的路径：
识别用例：找到一个你或你的团队高频重复的多步骤任务。例如，“每周从 Jira 同步数据到 Google Sheets 并生成图表”。
定义成功标准：明确什么样的结果算“成功”。例如，“一个包含最新数据和三个核心图表的 Google Sheet 链接被创建”。
对话式原型：先不要写 Skill！直接在一个新的 Claude 对话中，通过多轮对话手动引导 Claude 完成这个任务。把需要的工具（MCP）、数据源、操作步骤都告诉它。
提炼成 Skill：当你成功地让 Claude 完成任务后，将整个对话过程提炼成 SKILL.md。
description 的一部分。references/ 目录。SKILL.md 主体的指令。scripts/ 目录。本地测试：在 Claude.ai 或 Claude Code 中上传你的 Skill 文件夹，测试它是否能在新对话中被正确触发并独立完成任务。
迭代与分享：根据测试中发现的失败案例（如触发失败、步骤错误），迭代优化你的 SKILL.md。当它足够稳定后，通过 Git 仓库分享给你的团队。
Anthropic 提出的 Skill 概念，本质上是将软件工程的最佳实践（如模块化、版本控制、API 契约）引入到与大语言模型的交互中。它提供了一种在“万能”的通用模型和“固化”的专用工具之间，构建可复用、可维护、可演进的智能工作流的有效范式。
通过这份官方指南，我们可以看到构建一个强大的 Skill 不仅仅是“写 Prompt”，更是一项严肃的工程活动。
