7.7 Skill Creator - 创建自定义 Skill
概述
Skill Creator 是一个元技能（meta-skill），专门用于指导如何创建有效的自定义 Skill。它帮助用户将特定领域的知识、工作流程和工具封装成可复用的 Skill 包，让 Claude 能够在特定任务中表现得更加专业。
什么是 Skill？
Skill 是模块化、自包含的扩展包，通过提供专业知识、工作流程和工具来扩展 Claude 的能力。可以把 Skill 想象成特定领域的"入职指南"——它们将 Claude 从通用型助手转变为配备专业知识的专门化代理。
Skill 提供的能力
- 专业工作流程：特定领域的多步骤流程
- 工具集成：处理特定文件格式或 API 的指令
- 领域专业知识：公司特定的知识、模式、业务逻辑
- 打包资源：脚本、参考资料和资产文件
核心原则
原则一：简洁是关键
上下文窗口是公共资源。Skill 与系统提示、对话历史、其他 Skill 元数据以及用户请求共享上下文窗口。
默认假设：Claude 已经非常智能。 只添加 Claude 不具备的上下文。对每条信息提出质疑：
- "Claude 真的需要这个解释吗？"
- "这段内容值得消耗这些 token 吗？"
优先选择简洁的示例，而非冗长的解释。
原则二：设置适当的自由度
根据任务的脆弱性和可变性匹配具体程度：
自由度光谱
+------------------+------------------+------------------+
| 高自由度 | 中自由度 | 低自由度 |
+------------------+------------------+------------------+
| 文本指令 | 伪代码/带参数脚本 | 具体脚本/少参数 |
| 多种方法都有效 | 存在首选模式 | 操作脆弱易错 |
| 决策依赖上下文 | 允许一些变化 | 一致性至关重要 |
| 启发式引导 | 配置影响行为 | 必须遵循特定顺序 |
+------------------+------------------+------------------+
开阔田野 窄桥悬崖类比：把 Claude 想象成在探索路径：
- 有悬崖的窄桥需要具体的护栏（低自由度）
- 开阔的田野允许多条路线（高自由度）
原则三：渐进式披露
Skill 使用三级加载系统来高效管理上下文：
+---------------------------+------------------+------------+
| 加载级别 | 触发条件 | 大小限制 |
+---------------------------+------------------+------------+
| 1. 元数据 (name+desc) | 始终在上下文中 | ~100 词 |
| 2. SKILL.md 正文 | 当 Skill 触发时 | <5000 词 |
| 3. 打包资源 | Claude 按需加载 | 无限制 |
+---------------------------+------------------+------------+Skill 的结构剖析
每个 Skill 由一个必需的 SKILL.md 文件和可选的打包资源组成：
skill-name/
|-- SKILL.md (必需)
| |-- YAML frontmatter 元数据 (必需)
| | |-- name: (必需)
| | |-- description: (必需)
| |-- Markdown 指令 (必需)
|-- scripts/ (可选) 可执行代码
|-- references/ (可选) 参考文档
|-- assets/ (可选) 输出资产文件SKILL.md 文件
SKILL.md 由两部分组成：
Frontmatter (YAML)：包含 name 和 description 字段。这是 Claude 判断何时使用该 Skill 的唯一依据，因此必须清晰全面地描述 Skill 的功能和使用时机。
Body (Markdown)：使用 Skill 的指令和指导。仅在 Skill 触发后加载。
---
name: docx
description: 全面的文档创建、编辑和分析能力，支持修订跟踪、批注、
格式保留和文本提取。当 Claude 需要处理专业文档 (.docx 文件) 时使用，
包括：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订跟踪，
(4) 添加批注，或任何其他文档任务
---打包资源
scripts/ - 脚本目录
存放可执行代码（Python/Bash 等），用于需要确定性可靠性或经常重复编写的任务。
何时包含：
- 相同代码被反复重写
- 需要确定性可靠性
示例：scripts/rotate_pdf.py 用于 PDF 旋转任务
优势：
- Token 高效
- 确定性执行
- 可以不加载到上下文就执行
references/ - 参考文档目录
存放文档和参考材料，用于在需要时加载到上下文中指导 Claude 的思考过程。
何时包含：
- Claude 在工作时应参考的文档
- 数据库模式、API 文档、领域知识、公司政策
示例：
references/finance.md- 财务模式references/api_docs.md- API 规范
最佳实践：
- 如果文件很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式
- 避免重复：信息应只存在于 SKILL.md 或 references 中，不要两处都有
assets/ - 资产目录
存放不打算加载到上下文、而是用于 Claude 输出的文件。
何时包含：
- Skill 需要在最终输出中使用的文件
- 模板、图片、图标、样板代码、字体
示例：
assets/logo.png- 品牌资产assets/slides.pptx- PowerPoint 模板assets/frontend-template/- HTML/React 样板
不应包含在 Skill 中的内容
Skill 应只包含直接支持其功能的必要文件。不要创建多余的文档或辅助文件：
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
Skill 只应包含 AI 代理完成工作所需的信息，不应包含关于创建过程、设置和测试程序、面向用户的文档等辅助上下文。
Skill 创建流程
创建 Skill 涉及六个步骤：
+--------+ +--------+ +--------+ +--------+ +--------+ +--------+
| Step 1 | --> | Step 2 | --> | Step 3 | --> | Step 4 | --> | Step 5 | --> | Step 6 |
+--------+ +--------+ +--------+ +--------+ +--------+ +--------+
| 理解 | | 规划 | | 初始化 | | 编辑 | | 打包 | | 迭代 |
| Skill | | 内容 | | Skill | | Skill | | Skill | | 优化 |
+--------+ +--------+ +--------+ +--------+ +--------+ +--------+Step 1: 通过具体示例理解 Skill
为了创建有效的 Skill，需要清楚地理解 Skill 将如何被使用的具体示例。
关键问题：
- "这个 Skill 应该支持什么功能？"
- "能给一些如何使用这个 Skill 的例子吗？"
- "用户会说什么来触发这个 Skill？"
示例：构建 image-editor Skill 时：
- "编辑图片"
- "旋转这张图片"
- "去除这张照片的红眼"
Step 2: 规划可复用的 Skill 内容
分析每个示例：
- 考虑如何从头执行示例
- 识别在重复执行这些工作流时有帮助的脚本、参考和资产
示例分析：
| 场景 | 分析 | 建议资源 |
|---|---|---|
| PDF 旋转 | 每次需要重写相同代码 | scripts/rotate_pdf.py |
| 前端构建 | 每次需要相同样板代码 | assets/hello-world/ 模板 |
| BigQuery 查询 | 每次需要重新发现表模式 | references/schema.md |
Step 3: 初始化 Skill
使用 init_skill.py 脚本创建新 Skill：
scripts/init_skill.py <skill-name> --path <output-directory>示例：
scripts/init_skill.py my-new-skill --path skills/public
scripts/init_skill.py my-api-helper --path skills/private脚本会：
- 在指定路径创建 Skill 目录
- 生成带有正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
- 创建示例资源目录：
scripts/、references/和assets/ - 在每个目录添加可自定义或删除的示例文件
Step 4: 编辑 Skill
学习已验证的设计模式
工作流模式 - 用于多步骤流程：
填充 PDF 表单涉及以下步骤：
1. 分析表单 (运行 analyze_form.py)
2. 创建字段映射 (编辑 fields.json)
3. 验证映射 (运行 validate_fields.py)
4. 填充表单 (运行 fill_form.py)
5. 验证输出 (运行 verify_output.py)条件工作流模式 - 用于分支逻辑：
1. 确定修改类型：
**创建新内容？** --> 遵循下面的"创建工作流"
**编辑现有内容？** --> 遵循下面的"编辑工作流"
2. 创建工作流：[步骤]
3. 编辑工作流：[步骤]模板模式 - 用于一致的输出格式：
## 报告结构
始终使用这个精确的模板结构：
# [分析标题]
## 执行摘要
[关键发现的一段概述]
## 关键发现
- 发现 1 及支持数据
- 发现 2 及支持数据
## 建议
1. 具体可操作的建议
2. 具体可操作的建议示例模式 - 用于输出质量依赖示例的情况：
## 提交消息格式
按照这些示例生成提交消息：
**示例 1:**
输入：添加了使用 JWT 令牌的用户认证
输出：
feat(auth): 实现基于 JWT 的认证
添加登录端点和令牌验证中间件
**示例 2:**
输入：修复了报告中日期显示错误的 bug
输出：
fix(reports): 修正时区转换中的日期格式
在报告生成中一致使用 UTC 时间戳编写 Frontmatter
---
name: skill-name
description: 完整且信息丰富的解释，说明 Skill 做什么以及何时使用。
包含触发此 Skill 的具体场景、文件类型或任务。
---重要提示：
description是 Skill 的主要触发机制- 包含所有"何时使用"信息在这里，而不是在正文中
- 正文只在触发后加载，所以正文中的"何时使用此 Skill"部分对 Claude 没有帮助
Step 5: 打包 Skill
开发完成后，必须将 Skill 打包成可分发的 .skill 文件：
scripts/package_skill.py <path/to/skill-folder>
# 可选：指定输出目录
scripts/package_skill.py <path/to/skill-folder> ./dist打包脚本会：
验证 Skill：
- YAML frontmatter 格式和必需字段
- Skill 命名约定和目录结构
- 描述完整性和质量
- 文件组织和资源引用
打包 Skill（如果验证通过）：
- 创建以 Skill 命名的 .skill 文件
- 包含所有文件并保持正确的目录结构
Step 6: 迭代优化
测试 Skill 后，用户可能会要求改进：
迭代工作流：
- 在真实任务上使用 Skill
- 注意困难或低效之处
- 确定应如何更新 SKILL.md 或打包资源
- 实施更改并再次测试
渐进式披露设计模式
模式 1：高层指南 + 参考
# PDF 处理
## 快速开始
使用 pdfplumber 提取文本：
[代码示例]
## 高级功能
- **表单填充**：参见 [FORMS.md](FORMS.md) 完整指南
- **API 参考**：参见 [REFERENCE.md](REFERENCE.md) 所有方法
- **示例**：参见 [EXAMPLES.md](EXAMPLES.md) 常见模式Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
模式 2：按领域组织
对于具有多个领域的 Skill，按领域组织内容以避免加载无关上下文：
bigquery-skill/
|-- SKILL.md (概述和导航)
|-- reference/
|-- finance.md (收入、账单指标)
|-- sales.md (机会、管道)
|-- product.md (API 使用、功能)
|-- marketing.md (活动、归因)当用户询问销售指标时，Claude 只读取 sales.md。
模式 3：条件详情
显示基本内容，链接到高级内容：
# DOCX 处理
## 创建文档
使用 docx-js 创建新文档。参见 [DOCX-JS.md](DOCX-JS.md)。
## 编辑文档
对于简单编辑，直接修改 XML。
**对于修订跟踪**：参见 [REDLINING.md](REDLINING.md)
**对于 OOXML 详情**：参见 [OOXML.md](OOXML.md)Skill 结构选择指南
根据 Skill 的目的选择最合适的结构：
1. 基于工作流（适合顺序流程）
当有清晰的步骤式程序时效果最好。
## 概述 --> ## 工作流决策树 --> ## 步骤 1 --> ## 步骤 2...示例：DOCX Skill 的"工作流决策树" --> "读取" --> "创建" --> "编辑"
2. 基于任务（适合工具集合）
当 Skill 提供不同操作/能力时效果最好。
## 概述 --> ## 快速开始 --> ## 任务类别 1 --> ## 任务类别 2...示例：PDF Skill 的"快速开始" --> "合并 PDF" --> "拆分 PDF" --> "提取文本"
3. 参考/指南（适合标准或规范）
用于品牌指南、编码标准或需求。
## 概述 --> ## 指南 --> ## 规范 --> ## 使用...示例：品牌样式的"品牌指南" --> "颜色" --> "字体" --> "功能"
4. 基于能力（适合集成系统）
当 Skill 提供多个相互关联的功能时效果最好。
## 概述 --> ## 核心能力 --> ### 1. 功能 --> ### 2. 功能...示例：产品管理的"核心能力" --> 编号的能力列表
重要指南
避免深层嵌套引用
保持引用从 SKILL.md 只有一层深度。所有参考文件应直接从 SKILL.md 链接。
结构化较长的参考文件
对于超过 100 行的文件，在顶部包含目录，以便 Claude 预览时能看到完整范围。
写作风格
始终使用祈使句/不定式形式：
- 好："提取文本"、"创建文档"
- 避免："这将提取文本"、"用户应该创建文档"
实际应用示例
示例 1：创建 PDF 编辑 Skill
Step 1 - 理解：
- "旋转这个 PDF"
- "提取第 5 页到第 10 页"
- "合并这些 PDF 文件"
Step 2 - 规划：
scripts/rotate_pdf.py- PDF 旋转脚本scripts/merge_pdf.py- PDF 合并脚本references/api_docs.md- API 文档
Step 3 - 初始化：
scripts/init_skill.py pdf-editor --path skills/Step 4 - 编辑：
---
name: pdf-editor
description: PDF 文档的编辑和处理能力。当用户需要旋转、合并、
拆分、提取或修改 PDF 文件时使用此 Skill。
---示例 2：创建 BigQuery 查询 Skill
Step 1 - 理解：
- "今天有多少用户登录？"
- "上周的收入是多少？"
- "显示销售管道状态"
Step 2 - 规划：
references/schema.md- 数据库模式references/finance.md- 财务相关表references/sales.md- 销售相关表
Step 4 - 编辑： 使用按领域组织的模式，让 Claude 根据查询类型只加载相关文档。
总结
Skill Creator 提供了创建有效 Skill 的完整方法论：
核心原则：
- 简洁是关键 - 只添加 Claude 不知道的信息
- 适当的自由度 - 根据任务脆弱性调整具体程度
- 渐进式披露 - 三级加载系统高效管理上下文
创建流程：
- 理解 -> 2. 规划 -> 3. 初始化 -> 4. 编辑 -> 5. 打包 -> 6. 迭代
关键工具：
init_skill.py- 初始化新 Skillpackage_skill.py- 打包和验证 Skill
设计模式：
- 工作流模式、条件工作流模式
- 模板模式、示例模式
- 按领域组织、渐进式披露
记住：Skill 是为另一个 Claude 实例创建的"入职指南"。包含那些有益且非显而易见的信息，帮助 Claude 更有效地执行特定领域的任务。