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.)

SKILL.md（必需）

元数据质量： YAML frontmatter 中的 name 和 description 决定 Claude 何时使用该技能。请具体说明技能的功能和适用场景。使用第三人称表述（例如“在……时应使用此技能”，而不是“在……时使用此技能”）。

捆绑资源（可选）

脚本（scripts/）

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

• 适用场景：当相同代码被反复重写，或需要确定性可靠性时
• 示例：用于旋转 PDF 的 scripts/rotate_pdf.js
• 优势：节省 Token、结果确定，可在不加载到上下文中的情况下执行
• 注意：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：编辑 Skill

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

从可复用的 Skill 内容入手

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

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

更新 SKILL.md

写作风格： 整个 Skill 使用祈使式／不定式形式（以动词开头的指令），而非第二人称。使用客观、指导性的语言（例如，“要完成 X，请执行 Y”，而非“你应该执行 X”或“如果你需要执行 X”）。这样能确保 AI 易于理解的一致性和清晰度。

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

1. 这个 Skill 的用途是什么？用几句话说明。
2. 何时应使用这个 Skill？
3. 实际使用时，Claude 应如何使用这个 Skill？应引用上文开发的所有可复用 Skill 内容，让 Claude 知道如何使用这些内容。

步骤 5：验证 Skill

Skill 准备就绪后，使用 quick_validate.py 脚本进行验证，确保在使用前符合所有要求：

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

该脚本会检查：

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

修复所有报告的问题，并重新运行脚本，直到验证通过。

注意： 不要使用 package_skill.py——它会创建必须手动解压的 zip 文件，并留下临时文件。Skill 目录已经位于正确位置，无需打包。

步骤 6：迭代

测试 Skill 后，用户可能会要求改进。通常，这种情况会在使用 Skill 后立即发生，此时用户对 Skill 的表现还有新鲜的体验。

迭代工作流：

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