skill-creator

技能创建助手

此技能提供创建有效技能的指导。

关于技能

技能是模块化、独立的程序包，可通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为针对特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备程序性知识的专业 Agent，而这些知识并非任何模型都能完全掌握。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司专属知识、架构、业务逻辑
4. 捆绑资源——用于复杂和重复性任务的脚本、参考资料和素材

核心原则

简洁为要

上下文窗口是公共资源。技能与 Claude 所需的其他所有内容共享上下文窗口：系统提示词、对话历史、其他技能的元数据，以及用户的实际请求。

默认假设：Claude 已经很聪明。 只添加 Claude 尚不具备的上下文。逐条审视每项信息：“Claude 真的需要这段解释吗？”以及“这一段内容值得占用相应的 token 吗？”

相比冗长的解释，优先使用简洁的示例。

设置适当的自由度

根据任务的脆弱性和可变性，匹配具体程度：

高自由度（基于文本的说明）：适用于有多种有效方法、决策取决于上下文或需要依据启发式方法指导操作的情况。

中等自由度（伪代码或带参数的脚本）：适用于存在首选模式、允许一定变化或配置会影响行为的情况。

低自由度（特定脚本、少量参数）：适用于操作脆弱且容易出错、一致性至关重要或必须遵循特定顺序的情况。

可以将 Claude 想象成在探索一条路径：悬崖边的窄桥需要明确的防护措施（低自由度），而开阔的田野则允许多种路线（高自由度）。

技能的组成

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

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

SKILL.md（必需）

每个 SKILL.md 包含：

• Frontmatter（YAML）：包含必需的 name 和 description 字段，以及 license、metadata 和 compatibility 等可选字段。Claude 只会读取 name 和 description 来判断何时触发技能，因此请清楚、全面地说明该技能是什么，以及何时应该使用它。compatibility 字段用于注明环境要求（目标产品、系统软件包等），但大多数技能不需要此字段。
• 正文（Markdown）：使用技能的说明和指导。只有在技能触发后（如果触发）才会加载。

捆绑资源（可选）

脚本（scripts/）

用于需要确定性和可靠性，或需要反复重写的任务的可执行代码（Python/Bash 等）。

• 何时包含：需要反复重写相同代码，或需要确定性和可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 token、结果确定，且无需加载到上下文中即可执行
• 注意：Claude 可能仍需读取脚本，以进行修补或适配特定环境

参考资料（references/）

按需加载到上下文中的文档和参考资料，用于为 Claude 的处理和思考提供信息。

• 何时包含：当 Claude 在工作期间需要参考某些文档时
• 示例：references/finance.md 用于财务 schema，references/mnda.md 用于公司 NDA 模板，references/policies.md 用于公司政策，references/api_docs.md 用于 API 规范
• 使用场景：数据库 schema、API 文档、领域知识、公司政策、详细工作流指南
• 优势：让 SKILL.md 保持精简，仅在 Claude 判断需要时加载
• 最佳实践：如果文件较大（>10k 词），在 SKILL.md 中包含 grep 搜索模式
• 避免重复：信息应只存在于 SKILL.md 或 references 文件中，而不是两者都有。除非信息确实是该 skill 的核心，否则优先放在 references 文件中以承载详细信息——这样既能保持 SKILL.md 精简，又能在不占用上下文窗口的情况下让信息可被发现。SKILL.md 中只保留必要的流程说明和工作流指导；将详细的参考材料、schema 和示例移到 references 文件中。

资产（assets/）

不打算加载到上下文中，而是在 Claude 生成的输出中使用的文件。

• 何时包含：当 skill 需要用于最终输出的文件时
• 示例：assets/logo.png 用于品牌资产，assets/slides.pptx 用于 PowerPoint 模板，assets/frontend/ 用于 HTML/React 样板代码，assets/font.ttf 用于字体排版
• 使用场景：会被复制或修改的模板、图片、图标、样板代码、字体、示例文档
• 优势：将输出资源与文档分离，使 Claude 无需将文件加载到上下文中即可使用它们

不应包含在 Skill 中的内容

一个 skill 只应包含直接支持其功能的文件。不要创建多余的文档或辅助文件，包括：

• README
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等。

skill 只应包含 AI Agent 完成手头工作所需的信息。它不应包含关于其创建过程、设置和测试步骤、面向用户的文档等辅助上下文。创建额外的文档文件只会增加杂乱和困惑。

渐进式披露设计原则

Skills 使用三级加载系统来高效管理上下文：

1. 元数据（name + description） - 位于上下文中（约 100 词）
2. SKILL.md 正文 - 当 skill 触发时（<5k 词）
3. 捆绑资源 - 按 Claude 需要（不受限制，因为脚本可以在不读入上下文窗口的情况下执行）

渐进式披露模式

将 SKILL.md 正文控制在 500 行以内，只保留必要内容，以尽量减少上下文膨胀。接近这一上限时，将内容拆分到单独的文件中。将内容拆分到其他文件时，务必在 SKILL.md 中引用这些文件，并清楚说明何时应阅读它们，以确保技能的读者知道这些文件的存在以及何时使用它们。

核心原则： 当某项技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指南。将特定于变体的详细信息（模式、示例、配置）移至单独的参考文件。

模式 1：高级指南与参考文件

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于包含多个领域的技能，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，Claude 只会读取 sales.md。

同样，对于支持多个框架或变体的技能，也按变体组织：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，Claude 只会读取 aws.md。

模式 3：条件式详细内容

展示基本内容，并链接到进阶内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

只有当用户需要这些功能时，Claude 才会读取 REDLINING.md 或 OOXML.md。

重要指南：

• 避免多层嵌套引用——引用文件与 SKILL.md 之间保持一层。所有引用文件都应直接链接自 SKILL.md。
• 为较长的参考文件添加结构——对于超过 100 行的文件，在顶部添加目录，以便 Claude 在预览时了解文件的完整范围。

技能创建流程

创建技能包括以下步骤：

0. 根据任务历史了解用户意图，并确认理解
1. 创建计划文件 TODO 列表，并将其作为唯一的执行跟踪工具
2. 通过具体示例了解技能
3. 规划可复用的技能内容（脚本、参考文件、资源）
4. 初始化技能（运行 init_skill.py）
5. 编辑技能（实现资源并编写 SKILL.md）
6. 打包技能（运行 package_skill.py）
7. 根据实际使用情况迭代

请按顺序执行这些步骤，只有在有明确理由表明某步骤不适用时才跳过。

步骤 0（必需）：根据任务历史了解用户意图

此步骤为必需。在完成之前，不要初始化或编辑技能。

当用户要求创建或更新技能时，通常是基于近期的任务历史。你必须先从以下方面还原用户意图：

• 最近的任务消息及结果（成功或失败，以及修改了什么）
• 当前启用的技能，以及它们完成或未能完成的部分
• 用户反复表达的偏好与约束（语气、受众、结构、边界）

继续之前，先用自然语言向用户回顾你对需求的理解，并征求确认。

面向用户的沟通要求（必需）：

• 使用自然、对话式中文，写 3–6 句话。
• 不要使用刻板的输出格式、双语标题或“理解结果 / Understanding Summary”之类的标签。
• 聚焦于用户真正希望复用的内容：
  • 用户希望将什么目标转化为可重复使用的能力
  • 刚完成的任务中，哪些方法或偏好值得保留
  • 建议采用何种技能粒度，以及原因（能力层级，而非一次性主题）
• 在首次确认消息中，避免倾倒技术命名细节。必要时，只提一个简单的方向名称。
• 以一个确认问题结束，并等待用户回复。

内部完整性检查清单（供推理使用，不作为固定的面向用户模板）：

1. 用户目标
2. 背景和受众
3. 任务历史中成功且可复用的方法
4. 用户偏好和硬性约束
5. 建议的技能粒度
6. 建议的技能方向或名称

推荐语气示例：

我理解你是想把这次任务里“如何写好一类通知”的经验沉淀成可复用能力，而不是只复用这一次的具体内容。
从刚才的过程看，可复用的关键是：受众定位、语气控制、信息结构和人文关怀表达。
所以更合适的沉淀粒度是“编写通知”这类能力型技能，后续可覆盖放假通知、制度通知等相近场景。
我这样理解对吗？如果对，我们就按这个方向进入生成步骤。

必须等待用户明确确认后才能继续。

步骤 1（必需）：创建并维护 Plan-With-Files TODO

此步骤为必需步骤，必须在确认步骤 0 后立即执行。

在以下位置创建 TODO 跟踪文件：

./output/skill-creation.todo.md

使用模板：

references/plan-with-files.todo-template.md

执行规则：

• 每项实施操作都必须对应一个 TODO 条目，并注明明确的文件路径。
• 持续更新状态：
  • [ ] 尚未开始
  • [-] 进行中
  • [x] 已完成
  • [!] 已阻塞
• 当前步骤标记为 [x] 之前，不要执行下一个主要步骤。
• TODO 文件是进度的唯一事实来源，必须如实反映实际情况。

步骤 2：通过具体示例理解技能

仅当已经清楚了解该技能的使用模式时，才可跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这种了解可以来自用户直接提供的示例，也可以来自经用户反馈验证的生成示例。

例如，在构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应支持哪些功能？编辑、旋转，还有别的吗？”
• “你能提供一些该技能的使用示例吗？”
• “我能想到用户可能会提出‘去掉这张图片中的红眼’或‘旋转这张图片’之类的要求。你还设想过其他使用方式吗？”
• “用户说什么时，应该触发此技能？”

为避免让用户不知所措，不要在一条消息中提出太多问题。先从最重要的问题开始，再根据需要追问，以提升效果。

当明确了解该技能应支持的功能后，结束此步骤，并在 TODO 文件中记录其已完成。

步骤 3：规划可复用的技能内容

要将具体示例转化为有效的技能，请逐一分析每个示例：

1. 思考如何从头开始完成该示例
2. 确定重复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：构建用于处理“帮我旋转这个 PDF”之类请求的 pdf-editor 技能时，分析结果表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 在技能中保存一个 scripts/rotate_pdf.py 脚本会很有帮助

示例：为处理“给我构建一个待办事项应用”或“给我构建一个追踪步数的仪表板”之类请求而设计 frontend-webapp-builder 技能时，分析结果表明：

1. 编写前端 Web 应用每次都需要相同的 HTML/React 样板代码
2. 在技能中保存一个包含 HTML/React 项目样板文件的 assets/hello-world/ 模板会很有帮助

示例：构建用于处理“今天有多少用户登录？”之类请求的 big-query 技能时，分析结果表明：

1. 每次查询 BigQuery 都需要重新发现表结构及其关系
2. 在技能中保存一个记录表结构的 references/schema.md 文件会很有帮助

要确定技能的内容，请分析每个具体示例，并列出要包含的可复用资源：脚本、参考资料和资源。使用具体到文件级别的任务更新 TODO 文件。

步骤 4：初始化技能

现在可以开始实际创建技能了。

只有在正在开发的技能已经存在，且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头创建新技能时，务必运行 init_skill.py 脚本。该脚本可以便捷地生成新的技能模板目录，并自动包含技能所需的一切内容，让技能创建过程更加高效可靠。

用法：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成包含正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，按需自定义或删除生成的 SKILL.md 和示例文件。

步骤 5：编辑技能

编辑新生成或已有的技能时，请记住，该技能是为另一个 Claude 实例使用而创建的。请纳入对 Claude 有益且不显而易见的信息。考虑哪些流程知识、特定领域的细节或可复用资源能够帮助另一个 Claude 实例更有效地执行这些任务。

学习经过验证的设计模式

根据技能需求，参考以下实用指南：

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式
• 任务执行跟踪：参阅 references/plan-with-files.todo-template.md，了解 plan-with-files TODO 结构

这些文件包含有效技能设计的成熟最佳实践。

从可复用的技能内容着手

开始实现时，先处理上述已确定的可复用资源文件：scripts/、references/ 和 assets/。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，以便存入 assets/，也可能需要提供文档，以便存入 references/。

必须通过实际运行新增的脚本来测试，确保没有错误，且输出符合预期。如果有许多相似脚本，只需测试有代表性的一部分，以在确保可信度的同时兼顾完成时间。

删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件来展示结构，但大多数技能并不需要这些文件。

更新 SKILL.md

**写作指南：**始终使用祈使或不定式形式。

Frontmatter

使用 name 和 description 编写 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，可帮助 Claude 理解何时使用该技能。
  • 同时说明技能的功能，以及应在何种特定触发条件或情境下使用。
  • 所有“何时使用”信息都应放在此处，而不是正文中。正文只有在触发后才会加载，因此在正文中添加“何时使用此技能”章节对 Claude 没有帮助。
  • docx 技能的 description 示例：“全面支持文档创建、编辑和分析，包括修订跟踪、批注、格式保留和文本提取。Claude 需要处理专业文档（.docx 文件）时使用： (1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订跟踪，(4) 添加批注，或执行任何其他文档任务”

请勿在 YAML frontmatter 中包含其他字段。

正文

编写有关如何使用此技能及其捆绑资源的说明。

第 6 步：打包技能

技能开发完成后，必须将其打包为可分发的 .zip 文件并分享给用户。打包流程会先自动验证技能，确保其满足所有要求：

scripts/package_skill.py <path/to/skill-folder> ./output --todo ./output/skill-creation.todo.md

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./output --todo ./output/skill-creation.todo.md

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名约定和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 验证 TODO 门槛（提供 --todo 时），确保打包前已完成前置任务。

3. 如果验证通过，则打包技能，创建一个以技能名称命名的 .zip 文件（例如 my-skill.zip），其中包含所有文件，并保留适合分发的目录结构。建议输出到 ./output，以便用户在任务输出区域快速找到生成的文件。

如果验证失败，脚本会报告错误并退出，不会创建打包文件。修复所有验证错误后，再次运行打包命令。

第 7 步：迭代

测试技能后，用户可能会要求改进。通常这会发生在刚使用完技能之后，此时用户对技能的表现还有清晰的印象。

迭代工作流：

1. 在实际任务中使用技能
2. 注意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或随附资源
4. 实施更改并再次测试