skill-creator

技能创建器

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

关于技能

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

技能提供的内容

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

技能的组成

每项技能都包含一个必需的 SKILL.md 文件，以及可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── 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 应少于 200 行，并包含相关 Markdown 文件和脚本的引用。
• 每个脚本或被引用的 Markdown 文件也应少于 200 行。请记住，可以随时将它们拆分到多个文件中（遵循渐进式披露原则）。
• SKILL.md 文件元数据中的描述应简洁，同时包含足够多的引用文件和脚本的用例，这有助于在 Claude Code 的实现过程中自动激活技能。
• 被引用的 Markdown 文件：
  • 编写这些文件时，可以牺牲语法规范以追求简洁。
  • 也可以引用其他 Markdown 文件或脚本。
• 被引用的脚本：
  • 优先使用 Node.js 或 Python 脚本，而不是 Bash 脚本，因为 Bash 脚本在 Windows 上支持不佳。
  • 如果要编写 Python 脚本，请确保提供 requirements.txt
  • 确保脚本按照以下顺序读取 .env 文件：process.env > .claude/skills/${SKILL}/.env > .claude/skills/.env > .claude/.env
  • 创建 .env.example 文件，以展示所需的环境变量。
  • 始终为这些脚本编写测试。

为什么？ 更好的上下文工程：受 Agent Skills 的渐进式披露技术启发，激活技能时，Claude Code 会考虑只将相关文件加载到上下文中，而不是像以前那样读取整个冗长的 SKILL.md。

SKILL.md（必需）

文件名： SKILL.md（大写） 文件大小： 少于 200 行；如需更多内容，请将其拆分到 references 文件夹中的多个文件。

元数据质量： YAML frontmatter 中的 name 和 description 决定 Claude 何时使用该技能。请具体说明该技能的功能及适用场景。使用第三人称（例如，“This skill should be used when...” 而不是 “Use this skill when...”）。

捆绑资源（可选）

脚本（scripts/）

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

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

参考资料（references/）

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

• 适用情况：Claude 工作时需要参考的文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优势：保持 SKILL.md 精简，仅在 Claude 判断需要时加载
• 最佳实践：如果文件较大（>10k 字），在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，而不是两者都放。除非信息确实是技能的核心内容，否则详细信息优先放在参考资料文件中。这样既能让 SKILL.md 保持精简，又能确保信息易于查找，而不会占用过多上下文窗口。SKILL.md 中只保留必要的流程说明和工作流指导；将详细的参考资料、架构和示例移到参考资料文件中。

资源文件（assets/）

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

• 适用情况：技能需要在最终输出中使用某些文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、字体文件 assets/font.ttf
• 使用场景：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
• 优势：将输出资源与文档分开，使 Claude 无需将文件加载到上下文中即可使用

渐进式披露设计原则

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

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（<5k 个词）
3. 捆绑资源 - Claude 按需加载（无限*）

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

技能创建流程

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

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

从可复用的技能内容开始

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

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

更新 SKILL.md

写作风格： 整个技能应采用祈使式／不定式（以动词开头的指令）来写，而不是使用第二人称。使用客观、指导性的语言（例如，“要完成 X，请执行 Y”，而不是“你应该执行 Y”或“如果你需要执行 Y”）。这样可以保持内容一致清晰，便于 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 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

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

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

步骤 6：迭代

测试技能后，用户可能会要求改进。通常，这些要求会在使用技能后立即提出，此时用户对技能的表现还有清晰的印象。

迭代工作流：

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

参考资料

• Agent Skills
• Agent Skills 规范
• Agent Skills 概览
• 最佳实践