skill-creator

技能创建器

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

关于技能

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

重要：

• 技能不是文档，而是供 Claude Code 使用工具、程序包、插件或 API 来完成任务的实用说明。
• 每项技能都会教 Claude 如何执行特定开发任务，而不是介绍工具的功能。
• Claude Code 可以自动激活多项技能来完成用户的请求。

技能提供的内容

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

技能的构成

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

.claude/skills/
└── skill-name/
    ├── SKILL.md (required)
    │   ├── YAML frontmatter metadata (required)
    │   │   ├── name: (required)
    │   │   ├── description: (required)
    │   │   ├── license: (optional)
    │   │   └── version: (optional)
    │   └── 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.)

要求（重要）

• 技能应按特定主题合并，例如：将 cloudflare、cloudflare-r2、cloudflare-workers、docker、gcloud 合并为 devops
• SKILL.md 应少于 150 行，并包含相关 Markdown 文件和脚本的引用。
• 每个脚本或引用的 Markdown 文件也应少于 150 行；请记住，你可以随时将它们拆分为多个文件（渐进式披露原则）。
• SKILL.md 文件元数据中的描述应简洁（少于 200 个字符），同时涵盖引用文件和脚本的足够多的用例，这有助于 Claude Code 在实现过程中自动激活技能。
• 引用的 Markdown 文件：
  • 编写这些文件时，应牺牲语法完整性以保持简洁。
  • 也可以引用其他 Markdown 文件或脚本。
• 引用的脚本：
  • 优先使用 nodejs 或 python 脚本，而非 bash 脚本，因为 bash 脚本在 Windows 上的支持不佳。
  • 如果要编写 python 脚本，请确保提供 requirements.txt
  • 确保脚本遵循 .env 文件的加载顺序：process.env > $HOME/.claude/skills/${SKILL}/.env（全局）> $HOME/.claude/skills/.env（全局）> $HOME/.claude/.env（全局）> ./.claude/skills/${SKILL}/.env（当前工作目录）> ./.claude/skills/.env（当前工作目录）> ./.claude/.env（当前工作目录）
  • 创建 .env.example 文件，展示所需的环境变量。
  • 始终为这些脚本编写测试。

重要：

• 始终牢记，SKILL.md 和参考文件应尽可能节省 token，以便充分利用渐进式披露。
• SKILL.md 应少于 150 行
• 引用的 Markdown 文件也应少于 150 行；请记住，你可以随时将它们拆分为多个文件（渐进式披露原则）。
• 引用的脚本：长度不限，但请确保其可正常工作，不存在编译、运行时、依赖、环境或平台问题。

为什么？ 更好的上下文工程：利用渐进式披露技术。激活 Agent 技能后，Claude Code 将考虑仅加载与当前任务相关的文件到上下文中，而不是像以前那样读取整个冗长的 SKILL.md。

SKILL.md（必需）

文件名： SKILL.md（大写） 文件大小： 少于 150 行；如果需要更多内容，请将其拆分到 references 文件夹中的多个文件（每个文件少于 150 行）。 SKILL.md 应始终简短精炼、直奔主题，可将其视为快速参考指南。

元数据质量： YAML frontmatter 中的 name 和 description（必须少于 200 个字符）决定 Claude 何时使用此技能。请具体说明此技能的功能及适用场景，切勿写得笼统、含糊或像教学内容。使用第三人称表述（例如，“This skill should be used when...” 而不是 “Use this skill when...”）。

随附资源（可选）

脚本（scripts/）

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

• 适用场景： 同一段代码需要反复重写，或需要确定性可靠性时
• 示例： 用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点： 节省 Token、结果确定，可在不加载到上下文的情况下执行
• 注意： Claude 仍可能需要读取脚本，以便进行修补或针对特定环境调整

重要：

• 为脚本编写测试。
• 运行测试并确认功能正常；如果测试失败，请修复后再次运行，并重复此过程，直到测试通过。
• 使用一些实际场景手动运行脚本，确认功能正常。
• 确保脚本遵循 .env 文件的读取顺序：process.env > $HOME/.claude/skills/${SKILL}/.env（全局）> $HOME/.claude/skills/.env（全局）> $HOME/.claude/.env（全局）> ./.claude/skills/${SKILL}/.env（当前工作目录）> ./.claude/skills/.env（当前工作目录）> ./.claude/.env（当前工作目录）

参考资料（references/）

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

• 适用场景： Claude 工作时需要参考文档的情况
• 示例： 财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 用途： 数据库架构、最佳实践、常见工作流、速查表、工具说明、API 文档、领域知识、公司政策、详细工作流指南
• 优点： 让 SKILL.md 保持精简，仅在 Claude 判断有需要时加载；便于查找信息，同时避免占用过多上下文窗口。
• 最佳实践： 如果文件较长（超过 150 行），请将其拆分到 references 文件夹中的多个文件（每个文件少于 150 行）；并在 SKILL.md 中加入 grep 搜索模式
• 避免重复： 信息应放在 SKILL.md 或 references 文件中，不要两处都写。除非某些内容确实是技能的核心，否则详细信息优先放在 references 文件中；这样能让 SKILL.md 保持精简，同时便于查找信息且避免占用过多上下文窗口。SKILL.md 中只保留必要的流程说明和工作流指导；将详细参考资料、架构和示例移至 references 文件。

重要：

• 被引用的 Markdown 文件也应少于 150 行；请记住，始终可以将其拆分为多个文件（渐进式披露原则）。
• 被引用的 Markdown 文件应包含实用说明，指导 Claude Code 如何使用工具、软件包、插件或 API 完成任务。
• 每项技能都应教会 Claude 如何执行特定的开发任务，而不是介绍工具的功能。

资源文件（assets/）

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

• 包含时机：技能需要在最终输出中使用文件时
• 示例：用于品牌素材的 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、用于排版的 assets/font.ttf
• 使用场景：模板、图片、图标、样板代码、字体、可复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Claude 无需将文件加载到上下文中即可使用

渐进式披露设计原则

技能采用三级加载系统，以高效管理上下文：

1. 元数据（名称 + 描述） - 始终位于上下文中（少于 200 个字符）
2. SKILL.md 正文 - 技能触发时加载（少于 5,000 个单词）
3. 捆绑资源 - Claude 按需使用（无限制*）

*之所以不受限制，是因为脚本可以执行，而无需读入上下文窗口。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，只有在明确不适用时才跳过步骤。

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

仅当技能的使用模式已明确时，才跳过此步骤。即使是在处理现有技能时，此步骤仍然很有价值。

要创建有效的技能，请通过具体示例清楚了解技能的使用方式。这些示例可以来自用户直接提供的示例，也可以由系统生成并经用户反馈验证。

使用 AskUserQuestion 工具收集用户反馈并验证理解。

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

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

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

当明确了解技能应支持的功能后，结束此步骤。

第 2 步：在互联网上研究

有效的技能是现实专业工作流程与案例研究的一个子集，因此研究互联网以了解当前的先进水平和最佳实践非常重要。

如有需要，启用 /docs-seeker 技能来搜索文档。

如果收到大量 URL 或文件，请使用多个 WebFetch 工具和 Explore 子 Agent 并行探索，然后向主 Agent 汇报。

启用 /research 技能，研究以下内容：

• 最佳实践和行业标准
• 现有 CLI 工具（可通过 npx、bunx 或 pipx 执行）及其使用模式
• 工作流与成功案例研究
• 常见模式、使用场景和示例
• 边缘情况、潜在问题及规避策略

记录研究报告，以便在下一步中使用。

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

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

1. 考虑如何从头开始执行示例
2. 优先通过现有 CLI 工具（使用 npx、bunx 或 pipx）执行，而不是编写自定义代码
3. 确定在重复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助
4. 分析当前的技能目录，避免功能重复，并尽可能复用现有技能。

示例： 构建一个用于处理“帮我旋转这个 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 文件存储在技能中会有所帮助

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

• 确保脚本遵循以下 .env 文件的读取顺序：process.env > $HOME/.claude/skills/${SKILL}/.env（全局）> $HOME/.claude/skills/.env（全局）> $HOME/.claude/.env（全局）> ./.claude/skills/${SKILL}/.env（当前工作目录）> ./.claude/skills/.env（当前工作目录）> ./.claude/.env（当前工作目录）
• 确保脚本有测试，运行所有测试并确认通过。切勿跳过此步骤。

第 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 实例更有效地完成这些任务。

从可复用的技能内容着手

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

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

更新 SKILL.md

写作风格： 使用祈使式／不定式形式（以动词开头的指令）撰写整个技能，而非使用第二人称。使用客观、指导性的语言（例如，使用“要实现 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这能确保内容一致，并便于 AI 理解。

完成 SKILL.md 时，请回答以下问题：

1. 用几句话说明该技能的用途。
2. 说明何时应使用该技能。
3. 说明在实际使用中 Claude 应如何使用该技能。请引用上文开发的所有可复用技能内容，让 Claude 知道如何使用它们。

第 5 步：打包技能

技能准备就绪后，应将其打包成可分发的 zip 文件，与用户共享。打包流程会自动先验证技能，确保其符合所有要求：

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

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

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

打包脚本将：

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

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量（必须少于 200 个字符）
   • 文件组织和资源引用

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

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

第 6 步：迭代

测试技能后，用户可能会要求改进。通常，这会在使用技能后立即发生，此时用户对技能的表现印象犹新。

迭代工作流：

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

验证标准

用于评估技能的详细验证标准：

• 快速检查清单：references/validation-checklist.md
• 元数据质量：references/metadata-quality-criteria.md
• Token 效率：references/token-efficiency-criteria.md
• 脚本质量：references/script-quality-criteria.md
• 结构与组织：references/structure-organization-criteria.md

插件市场

如需了解如何通过市场以插件形式分发技能，请参阅：

• 概述：references/plugin-marketplace-overview.md
• 架构：references/plugin-marketplace-schema.md
• 来源：references/plugin-marketplace-sources.md
• 托管：references/plugin-marketplace-hosting.md
• 故障排除：references/plugin-marketplace-troubleshooting.md

参考资料

• Agent Skills
• Agent Skills 规范
• Agent Skills 概述
• 最佳实践
• 插件市场