Claude Agent Skills开发指南：从理解到实践的最佳工作流

继 MCP（Model Context Protocol）之后，Anthropic 近期又推出了 Skill（技能）。因为工作需要，我最近快速上手并实践开发了一个 Skill，过程中积累了一些经验。本文将分享这些心得，帮助你：

• 快速理解 Skill 到底是什么？
• 掌握关键要点，提升 Skill 的开发质量与效率。

在第三部分，我将通过一个具体案例，完整展示如何将一个想法快速落地为可运行的 Skill。即使你对 Skill 还一知半解，只要能清晰描述需求、准备好相关资料，也能轻松开发出高质量的 Skill。

文章包含较多个人实践观点，仅供参考。

一、快速认识 Skill

Skill 即技能，通常存放在 skills 文件夹内，一个技能对应一个文件夹。一个完整的技能通常包括核心的 SKILL.md 文件，以及相关的文档和可运行的脚本等资源。

一个 SKILL.md 文件通常由两部分构成：开头的 YAML Frontmatter（元数据）和后续的 Markdown 格式技能描述。

在技能描述中，可以提及并引用该技能文件夹内的其他资源和脚本。Agent（智能体）会根据需要，动态加载这些文件。

加载机制分为三层：

1. 级别 1：SKILL.md 中的 YAML 元信息总是被加载到上下文中（约100个Token）。
2. 级别 2：SKILL.md 的正文部分（Markdown）仅在技能被触发时加载，建议小于5K Token。
3. 级别 3：捆绑的其他文件（文本、脚本、数据等）由 Claude 按需加载，没有明确限制。

Agent 的系统提示词和所有技能的元信息会始终驻留在上下文窗口中。这使得 Agent 能够根据实时对话内容，动态决策该使用哪个技能，并依据技能描述进一步加载所需的详细资源。

关于 Agent Skills 的更多官方说明，可以参考 Anthropic 工程博客 和 Claude Code 文档。

目前，Skills 主要在 Claude 桌面版、Claude Code 和 API 中使用。许多其他 AI 编程工具也已开始支持，例如：

• Antigravity：参见 Antigravity Skills 文档。
• Qwen Code：参见 Qwen Code Skills 文档。

如果你的开发工具暂时没有原生支持 Skills，可以借助 OpenSkills 这个开源项目来实现跨平台使用。

OpenSkills 能够非常方便地将技能安装到全局或项目级的 skills 目录中，并自动创建项目规则 Markdown 文件，从而“教会”其他 AI Agent 如何使用这些 Skills。

常用命令示例：

• 安装工具：npm i -g openskills
• 安装官方技能库：openskills install anthropics/skills
• 安装到全局：openskills install anthropics/skills --global
• 同步技能到规则文件：openskills sync
• 列出已安装技能：openskills list

详情参见 OpenSkills GitHub 仓库。

二、Skill vs MCP

最初听到 Skill 这个概念时，可能会有些困惑：不是已经有 MCP 了吗？为什么还要推出 Skill？

图片来源：skillsmp.com/docs

简单来说，两者的核心区别在于：

• Skill（技能） 解决的是“怎么做”的问题，主要是对经验、最佳实践和工作流程的封装。
• MCP 解决的是“有什么工具”的问题，主要是定义连接与交互的协议，用于 API 调用、数据读写和工具集成。

Skills 主要由 Markdown 文件和一些脚本组成，优势在于 渐进式加载，无需服务器资源，适用性广，Token 消耗更经济。而 MCP 采用客户端-服务器架构，启动时需加载所有工具定义，虽然集成外部功能强大，但 Token 消耗更高，设置也更复杂。

两者是 互补关系：Agent 可以通过 Skills 获取领域知识和操作指南，同时通过 MCP 来扩展和调用外部功能。当然，目前 Rule、MCP、Skill 之间的边界也正在变得越来越模糊。

三、快速开发 Skill 的最佳实践

在初步了解 Skill 及其与 MCP 的区别后，我们面临一个核心问题：如何快速、高质量地开发一个 Skill？

这里分享我总结出的一套高效实践。它的核心理念是：不要完全手动编写，而是充分利用强大 AI 模型的能力。

传送门：https://github.com/anthropics/skills

我知道 Anthropic 官方开源了一个 skills 仓库，里面有很多示例。你可能想下载下来学习参考，然后自己动手写一个。

但请先等等！我们为什么要自己从头写？

说实话，完全手动编写既耗时又低效。我们需要构思文件结构、布局提示词，花费大量时间，最终效果还不一定理想。

上下文工程实践

我的最佳实践是：准备好优质的上下文，让 AI 来写。

首先，将 Claude 的官方 Skills 仓库源码克隆到本地。

这个仓库不仅包含了丰富的 Skill 示例，还有非常详细的规范文档（尽管是英文的）。学习 AI 相关的开源项目时，我习惯使用一些工具为代码仓库生成知识图谱或 Wiki，以便快速熟悉其结构、原理和核心知识。

更进一步，我们可以将所有关于 Skill 的高质量资料（官方文档、博客、规范等）导入到 NotebookLM 这类工具中，通过提问快速生成信息图（如上图）、视频概览或 PPT，实现高效学习。这正是人工智能时代高效学习与知识管理的体现。

这要求我们转变思维：默认让 AI 来处理它擅长的事情。因此，编写 Claude 的 Skills 这件事，默认就应该由 AI 来完成。

既然让 AI 做事，我们就需要：

1. 把任务拆解到模型能力边界之内。
2. 把任务需求描述清楚。
3. 提供充足且准确的上下文。

我们已经拥有了什么？我们拥有了官方的优质案例、Skill 的详细规范，以及整理好的知识库。

我们需要做的，仅仅是把我们的任务逻辑表达清楚，然后把写技能所需的所有资料提供给 AI 就可以了！

说了这么多，具体怎么做？下面用一个完整案例来演示。

我一直想做一个“提示词优化专家”工具。我发现市面上的很多提示词调优工具存在两个问题：一是没有澄清需求就直接优化；二是往往套用一个比较通用的框架。

理想的工具应该能先判断用户原始提示是否存在错误或歧义，对焦清楚后再进行优化。此外，通用的提示词框架效果往往不如最贴切、最专业的框架。即使是从事 AI 业务的同学，也不可能记住所有专业框架——为什么不让 AI 来自动匹配呢？

借着学习 Skill 的机会，我尝试将这个概念实现为一个 Skill。

我只需要做两件事：把逻辑理清楚，把 AI 需要的资料准备好。

逻辑梳理：

1. 当用户给出原始提示词或创作想法时，激活技能。
2. 技能需要匹配最专业的提示词框架，并判断原始输入是否存在歧义和遗漏。若存在，则提示用户补充。
3. 若信息完整，则按照最佳匹配的框架，撰写成专业的提示词。

素材准备：

需要准备各种专业的提示词框架。这些框架文档本身，也可以通过 AI Coding 工具中的 MCP（例如 Qoder MCP 广场的 fetch 工具或自行配置 Firecrawl）从网络爬取并整理。

虽然 Claude 支持“渐进式加载”，但我们不应该让智能体一开始就加载所有几十个框架文件再做判断，这样既浪费 Tokens 又慢。

解决方案是：为所有框架准备一份摘要 Markdown 文件。这个摘要同样可以使用 Qoder 或 Cursor 这类工具，基于 57 个框架文档自动汇总生成。AI 先阅读摘要，从中匹配出最合适的框架，然后再去针对性读取对应框架的详情文件。这种在技术文档创作中常见的“索引-详情”结构，能极大提升效率。

接下来，我们只需清晰描述想法，并提供整理好的资源，AI 就能帮我们写出专业、清晰的 Skill，其质量很可能远高于手动编写。

当然，这个方法有个前提：使用当前全球顶尖的 AI 模型。

注：为了演示清晰，下文展示的“提示词框架”文件夹是重新拷贝的示例，实际开发中会直接让 AI 在指定目录生成最终技能包。

我实现的 prompt-optimizer Skill 已开源，地址在 GitHub。

当然，我们也可以通过 Qoder 或 Cursor 将 Claude 的 Skills 仓库规范压缩成一个“Skill 模板”，后续作为 AI Coding 工具的项目 Rule。这样，只需给 AI Coding 工具这条规则、我们的需求以及上下文，它就能帮助我们生成 Skill。

你可能会问：这样生成的 Skill 看着不错，但真的好用吗？我们在 Claude Code 里实际测试一下。

我们创建一个名为 skill-test 的测试项目，然后将我们的 prompt-optimizer.skill 文件夹放入项目的 .claude/skills/ 目录中。接着，我们让 Claude 帮忙优化一个关于“字幕校对”的提示词。

可以看到，Claude 成功匹配到了我们的 prompt-optimizer 技能。它按照技能中的指引，首先读取了摘要文件，智能匹配到最合适的 RACE 框架后，再去读取该框架的详情文档。

最终，它给出了选择 RACE 框架的原因，并输出了一个非常专业、全面的优化后提示词，甚至还贴心地提供了一个精简版本。

这个实践的好处在于，它不依赖 Claude 官方的 Skill 创建工具，也能生成高质量的 Skill。

官方 skill-creator

你可能会突发奇想：能不能做一个专门用于创建 Skill 的 Skill 呢？这就是“套娃”式开发。

事实上，Claude 官方早就想到了这一点，并提供了 skill-creator 技能！

那么，使用方法就非常简单了：创建一个空目录，像前面一样把你的需求描述和所有资料放进去，然后将官方的 skill-creator 技能也放入技能目录，让 Claude 调用它来帮你生成目标技能。

生成出来的 Skill 结构清晰、非常专业。

所以，我们真正应该关心的不是“Skill怎么写”，而是“如何向AI清晰表达需求”以及“如何为AI准备充足的上下文”。

四、Claude Skill 自身的最佳实践

基于官方指南和个人实践，以下是一些开发 Claude Skill 的核心最佳实践，这些内容也深度体现在 Anthropic 官方开源仓库的规范中。

1. 核心设计哲学：为 AI 而写，力求精简

• 上下文是公共资源：你的 Skill 会与系统提示词、对话历史、其他 Skills 的元数据以及用户请求共享有限的上下文窗口。
• 默认假设 Claude 很聪明：不要解释通用概念（如“什么是 PDF”），只提供它完成特定任务所必需的、未知的上下文。
• 质问每一个 Token：不断自问“Claude 真的需要这句话吗？”、“删除这段会影响执行效果吗？”，追求极致的简洁。
• SKILL.md 的黄金法则：
  • 保持精简：一旦加载，每个 Token 都在消耗成本和注意力。
  • 500 行限制：主文件正文建议保持在 500 行以内，超过则应考虑拆分到引用文件中。

2. 自由度控制

根据任务的容错率和风险，为技能设定不同的指令严格程度：

• 低自由度：适用于数据库迁移等高危操作。比喻为“悬崖边的独木桥”。应提供精确的脚本和严格的步骤，不留发挥空间。
• 中自由度：适用于有首选模式但允许微调的任务。可以提供伪代码或带参数的脚本。
• 高自由度：适用于代码审查、创意写作等。比喻为“开阔的平原”。只需提供原则和方向，信任 Claude 的判断力。

3. 结构与文件组织：渐进式披露

不要一次性把所有内容塞进上下文，而应像剥洋葱一样层层展开。

• 文件系统思维：Claude 像操作 Linux 文件系统一样通过 read 工具读取技能文件。设计时应利用此特性。
• 常见组织模式：
  • 概览 + 引用：SKILL.md 作为总览和目录，细节在 REFERENCE.md 等文件中。
  • 领域隔离：不同领域知识放在不同子目录（如 sales/, finance/），互不干扰。
  • 按需加载：高级功能（如“红线修订”）的说明仅在用户提及时才被加载。
• 避免深层嵌套：引用层级最好不要超过1层（如 SKILL.md -> ref.md），避免 sub_ref.md，以防 Claude 偷懒只读部分内容。
• 路径规范：始终使用正斜杠 /（Unix 风格），禁止使用 Windows 反斜杠 \。

4. 命名与元数据规范

• 名称：
  • 推荐使用动名词形式，如 processing-pdfs, analyzing-spreadsheets。
  • 仅限小写字母、数字、连字符。
  • 避免使用 helper, utils 等含义模糊的名称。
• 描述：
  • 至关重要：这是 Claude 在众多技能中决定是否调用你的唯一主要依据。
  • 使用第三人称，直接说明功能，如 “Processes Excel files...”。
  • 必须包含清晰的触发词，说明技能做什么以及在何时使用。

5. 迭代开发流：用 Claude 训练 Claude

不要完全手写，利用 AI 生成和优化 Skill。

• 角色分工：
  • Claude A (架构师)：负责编写/优化 Skill 文档。
  • Claude B (测试员)：加载 Skill 进行实战测试。
• 开发循环：
  1. 裸跑任务：先不用 Skill，让 Claude 执行任务，识别出必需的上下文和模式。
  2. 总结为 Skill：让 Claude A 将识别出的模式总结成 Skill。
  3. 使用测试：让 Claude B 使用新 Skill 执行相同或类似任务。
  4. 观察反馈：观察失败点（如忘记过滤测试数据），反馈给 Claude A 修正 Skill。
• 多模型测试：技能应在 Haiku（测试引导是否足够）、Sonnet（测试效率）、Opus（测试是否冗余）等多个模型上都能顺利运行。

6. 进阶：代码与执行

对于复杂任务，提供可执行脚本远优于纯文本指令。

• Plan-Validate-Execute 模式：对于批量或高风险操作（如修改50个数据库字段），不应直接执行。
  • 流程：分析 -> 生成计划文件 (changes.json) -> 运行脚本验证计划 -> 执行 -> 确认。
• 明确的错误处理：脚本应抛出具体、易懂的错误信息（如 “Field ‘date’ not found”），而不是让 Claude 去解析晦涩的报错。
• 避免魔术数字：所有配置项都应有明确的文档说明，不要让 Claude 猜测参数含义。
• MCP 工具调用：如果技能涉及调用 MCP 工具，必须使用全限定名 ServerName:tool_name（例如 GitHub:create_issue），以防止工具名冲突。

7. 避坑速查表

• ❌ 拒绝：在技能中包含时间敏感信息（如“当前是2024年”），除非是在标注“过时模式”的章节中。
• ❌ 拒绝：术语不一致（前面用“URL”，后面用“Endpoint”）。
• ❌ 拒绝：在路径中使用反斜杠 \。
• ✅ 必须：为超过100行的参考文件添加目录。
• ✅ 必须：在发布前，创建至少3个评估测试用例来验证技能效果。

更多详细的最佳实践，请参考 Claude 平台官方文档。

五、写在最后

本文分享了我对 Claude Agent Skills 的理解，并通过一个“提示词优化专家”的完整案例，展示了如何快速开发一个高质量的 Skill。

当 AI 模型足够强大时，我们的工作方式会发生显著变化。核心转变在于：我们从“执行者”更多地向“规划者”和“赋能者”角色迁移。

我们的重点工作变为：第一，将自己的想法和逻辑清晰地表达出来；第二，为 AI 准备完成任务所需的充足、准确的信息和上下文。

因此，在未来开发 Skill（或其他AI可完成的任务）时，我们应更专注于厘清任务逻辑与需求，并准备好高质量的资料。至于具体的编写和实现，可以放心地交给最强大的 AI 模型来完成。这种高效的人机协作模式，正是许多云栈社区技术爱好者所追求和实践的。

参考资料

1. OpenSkills 项目: https://github.com/numman-ali/openskills
2. Anthropic 官方 Skills 仓库: https://github.com/anthropics/skills
3. Anthropic 工程博客（Agent Skills）: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
4. Claude Code Skills 文档: https://code.claude.com/docs/en/skills