skill-creator

⚠️ 性能提示: 此 Skill 包含完整的评估体系（Grader/Comparator/Analyzer），适合在创建重要 Skill 时使用。对于简单 Skill，可跳过评估环节。

Skill Creator

此 Skill 提供创建高质量 Skills 的完整工作流指导。

关于 Skills

Skills 是模块化、自包含的包，通过提供专业领域的知识、工作流程和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的"入职指南"——它们将 Claude 从通用代理转变为配备程序性知识的专业代理。

Skills 提供的价值

1. 专业工作流 - 多步骤的特定领域流程
2. 工具集成 - 处理特定文件格式或 API 的说明
3. 领域专业知识 - 公司特定的知识、模式、业务逻辑
4. 打包资源 - 复杂和重复性任务的脚本、参考文档和资源

核心原则

简洁为王

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

默认假设：Claude 已经非常聪明。 只添加 Claude 不具备的上下文。质疑每一段信息："Claude 真的需要这个解释吗？" 和 "这段话的 token 成本合理吗？"

用简洁的示例代替冗长的解释。

设置适当的自由度

根据任务的脆弱性和可变性设置具体的指导程度：

自由度	类型	使用场景
高自由度	基于文本的指令	多个方案有效、决策依赖上下文
中自由度	伪代码或带参数的脚本	存在首选模式、可接受一些变化
低自由度	特定脚本、少参数	操作脆弱易错、一致性关键、需遵循特定顺序

把 Claude 想象成探索路径：狭窄的悬崖桥需要具体的护栏（低自由度），而开阔的田野允许多条路线（高自由度）。

Skill 结构

每个 Skill 由一个必需的 SKILL.md 文件和可选的打包资源组成：

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 正文 (必需)
└── 打包资源 (可选)
    ├── scripts/          - 可执行代码 (Python/Bash 等)
    ├── references/       - 按需加载到上下文的文档
    └── assets/          - 输出中使用的文件

SKILL.md 格式

每个 SKILL.md 由以下部分组成：

• Frontmatter (YAML): 包含 name 和 description 字段。这是 Claude 确定何时使用 Skill 的唯一依据，因此清晰描述 Skill 的功能和触发场景非常重要。
• Body (Markdown): 使用 Skill 的说明和指导。只在 Skill 被激活后加载。

打包资源

Scripts (scripts/)

用于需要确定性可靠性或反复重写的任务的可执行代码。

• 何时包含: 当相同的代码被反复重写或需要确定性可靠性时
• 示例: PDF 旋转任务的 scripts/rotate_pdf.py
• 优势: Token 高效、确定性、可执行而不加载到上下文

References (references/)

用于按需加载到上下文中以指导 Claude 过程和思维的文档和参考资料。

• 何时包含: 当 Claude 应该参考的文档时
• 示例: 财务模式的 references/finance.md、API 文档的 references/api_docs.md
• 最佳实践: 如果文件很大（>10k 字），在 SKILL.md 中包含 grep 搜索模式

Assets (assets/)

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

• 何时包含: 当 Skill 需要用于最终输出的文件时
• 示例: 品牌资源的 assets/logo.png、模板的 assets/frontend-template/

What to Not Include in a Skill

A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• etc.

The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited because scripts can be executed without reading into context window)

渐进式披露模式

将 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 在预览时了解文件的完整范围。

技能创建流程

创建技能包括以下步骤：

1. 通过具体示例理解技能
2. 规划可复用的技能内容（脚本、参考资料、资源）
3. 初始化技能（运行 init_skill.py）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 package_skill.py）
6. 迭代改进 - 根据真实使用反馈优化 Skill

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

步骤 5：评估与质量保证

创建 Skill 后，必须进行严格的质量评估。使用三 Agent 评估体系：

5.1 Grader（评分者）

职责：严格评估 Skill 输出质量

评估维度：

• 准确性（1-5）：输出是否准确回答问题？
• 完整性（1-5）：是否覆盖所有必要步骤？
• 可执行性（1-5）：指令是否清晰可执行？
• 边界处理（1-5）：错误和异常是否处理得当？

判定标准：

• 平均分 ≥ 4.0/5 → 通过
• 任何维度 < 3 → 不通过
• 其他情况 → 迭代后重评

5.2 Comparator（盲比较者）

职责：在不知道来源的情况下对比 Skill 与非 Skill 输出

比较维度：

• 任务完成度（40%）：哪个更好地解决问题？
• 代码质量（25%）：哪个更规范、更易维护？
• 清晰度（20%）：哪个解释得更清晰？
• 边界处理（15%）：哪个考虑了更多边界情况？

判定标准：

• Skill 输出明显更好，占比 ≥ 60% → 评估通过
• 其他情况 → 诊断问题后调整

5.3 Analyzer（分析者）

职责：汇总评估数据，分析原因并提出改进建议

分析内容：

• 总体统计（通过率、平均得分）
• 维度分析（最高分/最低分/平均分）
• 成功模式（可复制的特征）
• 失败原因（根本问题）
• 改进建议（按 P0/P1/P2 优先级排序）

判定标准：

• P0 建议 < 1 → 可发布
• P0 建议 ≥ 1 → 必须修复
• P1 建议 < 3 → 可发布
• P1 建议 ≥ 3 → 迭代后发布

评估流程图

新 Skill → 收集测试用例 → Grader 评估
    ↓
  {通过?} 
  ├─ 是 → Comparator 盲测
  └─ 否 → 返回改进 → 重新收集用例
    ↓
  {A 更好?}
  ├─ 是 → Analyzer 分析
  └─ 否 → 问题诊断 → 调整 Skill
    ↓
  {改进建议 < 3?}
  ├─ 是 → 发布
  └─ 否 → 迭代改进

快速评估指南

简单 Skill（< 3KB）：

1. 准备 5 个测试用例
2. Grader 评估（1 轮）
3. Comparator 盲测（1 轮）
4. 如通过，发布

复杂 Skill（> 10KB 或多功能）：

1. 准备 20 个测试用例（10 个 happy path + 10 个 edge cases）
2. Grader 评估（3 轮，每轮优化）
3. Comparator 盲测（2 轮）
4. Analyzer 完整分析
5. 根据建议迭代
6. 进行最终发布评审

详细评估文档：参考 AGENTS.md，获取完整的 Agent 定义、评估模板和最佳实践。

步骤 6：迭代改进

根据评估反馈持续优化：

1. 收集真实反馈

   • 用户使用数据（使用次数、成功率）
   • 评估结果（Grader/Comparator/Analyzer）
   • 错误报告和边界情况

2. 确定优先级

   • P0：影响核心功能的 bug
   • P1：重要的体验问题
   • P2：优化建议

3. 小步迭代

   • 每次迭代聚焦 1-2 个问题
   • 避免一次性大改
   • 每次修改后重新评估

4. 发布节奏

   • 简单修复：随时发布
   • 功能调整：每周发布
   • 大改：每月发布

步骤 1：通过具体示例了解技能

只有在已清楚了解技能的使用模式时，才跳过此步骤。即使使用现有技能，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解该技能将如何应用于具体示例。这些示例可以来自用户直接提供的内容，也可以是生成后经用户反馈验证的内容。

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

• “图像编辑器技能应支持哪些功能？编辑、旋转，还有其他功能吗？”
• “你能举几个使用此技能的例子吗？”
• “我能想到用户可能会提出这样的请求：‘去掉这张图片中的红眼’或‘旋转这张图片’。你觉得此技能还可能有哪些用途？”
• “用户说什么时应该触发此技能？”

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

当明确了解技能应支持哪些功能后，即可结束此步骤。

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

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

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

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

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 文件保存在技能中会有所帮助

要确定技能包含的内容，请分析每个具体示例，并列出需要纳入的可复用资源：脚本、参考资料和资源文件。

步骤 3：初始化技能

此时就可以创建技能了。

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

从头创建新技能时，务必运行 init_skill.py 脚本。该脚本会自动生成新的技能模板目录，其中包含技能所需的全部内容，从而大幅提高技能创建过程的效率和可靠性。

用法：

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

该脚本：

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

初始化后，根据需要自定义或移除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

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

学习成熟的设计模式

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

• 多步骤流程：参阅 references/workflows.md，了解顺序工作流和条件逻辑
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式

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

从可复用的技能内容着手

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

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

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

更新 SKILL.md

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

前置元数据

使用 name 和 description 编写 YAML 前置元数据：

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

不要在 YAML 前置元数据中添加其他字段。

正文

编写使用技能及其附带资源的说明。

第 5 步：打包技能

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

scripts/package_skill.py <path/to/skill-folder>

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

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

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

   • YAML 前置元数据格式和必需字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能名称命名的 .skill 文件（例如 my-skill.skill），其中包含所有文件，并保持适用于分发的正确目录结构。.skill 文件是带有 .skill 扩展名的 zip 文件。

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

第 6 步：迭代

测试技能后，用户可能会提出改进建议。这通常发生在刚使用完技能之后，此时对技能的表现还记忆犹新。

迭代工作流：

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