skill-creator

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 在预览时能看到完整范围。

技能创建流程

技能创建涉及以下步骤：

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

按顺序遵循这些步骤，只有在有明确理由说明它们不适用时才跳过。

步骤 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/ 中。

添加的脚本必须通过实际运行来测试，以确保没有 bug，并且输出符合预期。如果有许多相似的脚本，只需测试具有代表性的样本，以在确保它们都能正常工作与平衡完成时间之间取得平衡。

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

更新 SKILL.md

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

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

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

不要在 YAML frontmatter 中包含任何其他字段。

正文

编写使用该技能及其捆绑资源的说明。

步骤 5：打包技能

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

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

可选指定输出目录：

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

打包脚本将：

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

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

2. 如果验证通过，则打包技能，创建以技能命名的 .skill 文件（例如 my-skill.skill），该文件包含所有文件并保持适当的目录结构以便分发。.skill 文件是扩展名为 .skill 的 zip 文件。

如果验证失败，脚本将报告错误并在不创建包的情况下退出。修复任何验证错误并再次运行打包命令。

步骤 6：迭代

测试技能后，用户可能会请求改进。这种情况通常发生在使用技能后不久，此时对技能的表现还有新鲜的记忆。

迭代工作流：

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