从0到1打造Skill：完整实战指南

引言

最近 Skill 可谓热度颇高，无论是微信公众号还是博客园，都能看到大量围绕 Skill 的开发实践、落地方式以及发展趋势的文章。既然如此，我也打算凑个热闹，从实战的角度写一篇关于 Skill 的实践分享。
在展开之前，先简要说明一下什么是 Skill。Skills 的概念由 Anthropic 提出，本质上是一种更高层次的模块化能力封装，用于扩展智能体的功能边界。每一个 Skill 都封装了指令、元数据以及可选的资源（如脚本、模板等），智能体在执行任务时，会根据上下文相关性自动选择并调用合适的 Skill。
Skills能提供什么？

• 专业工作流 - 特定领域的多步骤操作流程
  
• 工具集成 - 使用特定文件格式或 API 的指导说明
  
• 领域专长 - 企业特有知识、数据架构、业务规则
  
• 资源包 - 处理复杂和重复任务所需的脚本、参考文档和相关资源
  

对Skill不了解的同学可以看下我之前的一篇文章 Claude Skills是什么？为什么要引入Skills？
开发个什么Skill呢？

通过 Skill，我们可以将某些能力进行模块化封装，从而实现特定的工作流编排、专家领域知识沉淀以及各类工具的集成。
这里我打算来一次“套娃式”的实践：创建一个用于自动生成 Skill 的 Skill，一是用来展示如何创建Skill，二是通过这种方式再深入理解下Skill的设计理念。在实际使用时，用户只需要输入该 Skill 的功能描述、使用场景以及示例用法，系统便可以自动生成对应的 Skill 说明文档、描述信息等配套内容。把这个自动生成Skill的Skill命名成：skill-creator。
下面，我们按照步骤向skill-creator的SKILL.md文件中写入以下内容：
一、定义skill-creator的描述信息

1. ---
2. name: skill-creator
3. description: 生成有效技能的指南。当用户想要创建新技能（或更新现有技能）时，应该使用此技能，该技能可以通过专业知识、工作流或工具集成来扩展Claude的能力。
4. ---

复制代码

二、解释下Skill和关于Skill

技能是模块化的、自包含的软件包，通过提供专业知识、工作流程和工具来扩展 Claude 的能力。可以把它们想象成特定领域或任务的"入职指南"——它们将 Claude 从通用型智能体转变为专业型智能体，使其具备任何模型都无法完全拥有的程序性知识。
Skills能提供什么？

• 专业工作流 - 特定领域的多步骤操作流程
  
• 工具集成 - 使用特定文件格式或 API 的指导说明
  
• 领域专长 - 企业特有知识、数据架构、业务规则
  
• 资源包 - 处理复杂和重复任务所需的脚本、参考文档和相关资源
  

核心理念

简洁至上

上下文窗口是一种公共资源。技能与 Claude 所需的其他所有内容共享上下文窗口：系统提示词、对话历史、其他技能的元数据以及实际的用户请求。
基本前提：Claude 本身已经很聪明。 只需添加 Claude 还不知道的内容。对每条信息都要提出质疑："Claude 真的需要这个说明吗？" 和 "这段内容的 token 成本值得吗？"
优先使用简洁的示例而非冗长的解释。
给予恰当的自由度

根据任务的脆弱性和可变性来匹配具体程度：
高自由度（基于文本的指令）：当存在多种有效方法、决策取决于上下文，或通过启发式方法指导时使用。
中等自由度（带参数的伪代码或脚本）：当存在首选模式、可接受一定程度的变化，或配置会影响行为时使用。
低自由度（特定脚本、少量参数）：当操作容易出错且脆弱、一致性至关重要，或必须遵循特定顺序时使用。
可以把 Claude 想象成在探索一条路径：悬崖边的狭窄桥梁需要具体的护栏（低自由度），而开阔的田野则允许多条路线（高自由度）。
三、生成的Skill有哪些组成部分

每个技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

1. skill-name/
2. ├── SKILL.md (required)
3. │   ├── YAML frontmatter metadata (required)
4. │   │   ├── name: (required)
5. │   │   └── description: (required)
6. │   └── Markdown instructions (required)
7. └── Bundled Resources (optional)
8.     ├── scripts/          - Executable code (Python/Bash/etc.)
9.     ├── references/       - Documentation intended to be loaded into context as needed
10.     └── assets/           - Files used in output (templates, icons, fonts, etc.)

复制代码

什么是SKILL.md

每个SKILL.md包含：

• 头部元数据（YAML 格式）：包含 name（名称）和 description（描述）字段。这些是 Claude 判断何时使用技能的唯一依据，因此清晰、全面地描述技能的功能和使用场景非常重要。
  
• 主体内容（Markdown 格式）：关于如何使用该技能的说明和指引。只有在技能被触发后才会加载（如果被触发的话）。
  

可选的捆绑资源

脚本 (scripts/)

可执行代码（Python/Bash 等），适用于需要确保可靠性或经常重复编写的任务。

• 何时使用：当同一段代码需要反复编写，或需要确定性的可靠执行时
  
• 举例：scripts/rotate_pdf.py 用于 PDF 旋转操作
  
• 优点：节省 token、结果确定、可能直接执行而无需加载到上下文
  
• 说明：Claude 仍可能需要读取脚本以进行修改或适配特定环境
  

参考资料 (references/)

文档和参考材料，按需加载到上下文中，用于指导 Claude 的工作流程和思考方式。

• 何时使用：当 Claude 工作时需要查阅的文档资料
  
• 举例：财务架构文档 references/finance.md、公司保密协议模板 references/mnda.md、公司制度 references/policies.md、API 规范 references/api_docs.md
  
• 适用场景：数据库模式、API 文档、专业领域知识、企业政策、详细操作指南
  
• 优点：让 SKILL.md 保持简洁，只在 Claude 需要时才加载
  
• 最佳实践：如果文件很大（超过 1 万字），在 SKILL.md 中添加 grep 搜索模式
  
• 避免重复：信息应该只放在 SKILL.md 或参考文件的其中一处，不要两边都有。详细信息优先放在参考文件中，除非真的是技能核心——这样既能保持 SKILL.md 简洁，又能让信息易于查找而不会占满上下文窗口。SKILL.md 只保留关键的操作说明和流程指引；详细的参考资料、架构图和示例都移到参考文件里。
  

资源文件 (assets/)

无需加载到上下文的文件，主要用于 Claude 产生的最终输出内容中。

• 何时使用：技能需要在最终成果中用到的文件
  
• 举例：品牌素材 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 脚手架 assets/frontend-template/、字体文件 assets/font.ttf
  
• 适用场景：模板文件、图像、图标、样板代码、字体、需要复制或修改的样例文档
  
• 优点：把输出用的资源和说明文档分开，让 Claude 可以使用这些文件而不占用上下文空间
  

技能中不应包含的内容

技能应仅包含直接支持其功能的核心文件。不要创建无关的文档或辅助文件，例如：

• README.md
  
• INSTALLATION_GUIDE.md（安装指南）
  
• QUICK_REFERENCE.md（快速参考）
  
• CHANGELOG.md（变更日志）
  
• 等等
  

技能只应包含 AI 智能体执行任务所需的信息。不应包含创建过程的附加说明、安装测试步骤、用户使用文档等辅助内容。添加额外的文档文件只会造成混乱和干扰。
四、渐进式展开设计原则

技能使用三级加载系统来高效管理上下文：
<ol>元数据（名称 + 描述） - 始终在上下文中（约100字）
SKILL.md 正文 - 当技能触发时（