技能包结构设计打包

概述

技能创建器

本技能提供创建高效技能的指导。

关于技能

技能是模块化、自包含的包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。把它们想象成针对特定领域或任务的"入职指南"——它们把 Claude 从一个通用型智能体变成一个装备了程序性知识的专用智能体，而这些知识是任何模型都无法完全具备的。

技能能提供什么

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)
│   └── 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 字段。这是 Claude 判断何时该使用该技能时唯一会读取的字段，因此把技能是什么、什么时候该用说清楚、说全面，非常重要。
• 正文（Markdown）：使用该技能的说明和指引。只在技能被触发之后才会加载（如果被触发的话）。

捆绑资源（可选）

脚本（scripts/）

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

• 何时包含：当同一段代码被反复重写，或需要确定性可靠性时
• 示例：scripts/rotate_pdf.py 用于 PDF 旋转任务
• 好处：省 token、确定性强，且可以执行而不必加载进上下文
• 注意：脚本仍然可能需要 Claude 读取，以便打补丁或做环境特定调整

参考文档（references/）

供 Claude 在需要时按需加载进上下文的文档与参考资料，用于支撑其流程与思考。

• 何时包含：对于 Claude 在工作中应当参考的文档
• 示例：references/finance.md 放财务数据结构，references/mnda.md 放公司 NDA 模板，references/policies.md 放公司政策，references/api_docs.md 放 API 规范
• 用途：数据库结构、API 文档、领域知识、公司政策、详细工作流指南
• 好处：让 SKILL.md 保持精简，只在 Claude 判断需要时才加载
• 最佳实践：如果文件很大（超过 1 万词），在 SKILL.md 中附上 grep 搜索模式
• 避免重复：信息应当只存在于 SKILL.md 或 references 文件之一，不要两处都有。除非确实是技能的核心，否则详细优先放 references 文件——这既让 SKILL.md 保持精简，又让信息可被找到而不占用上下文窗口。SKILL.md 里只保留必要的流程性指令和工作流指引；详细的参考材料、数据结构和示例移到 references 文件。

素材（assets/）

不打算加载进上下文、而是用于 Claude 产出结果的文件。

• 何时包含：当技能需要用在最终产出中的文件时
• 示例：assets/logo.png 放品牌素材，assets/slides.pptx 放 PowerPoint 模板，assets/frontend-template/ 放 HTML/React 样板代码，assets/font.ttf 放排版字体
• 用途：模板、图片、图标、样板代码、字体、会被复制或修改的示例文档
• 好处：把产出资源与文档分离，让 Claude 能使用文件而不必把它们加载进上下文

技能中不要包含什么

技能只应包含直接支撑其功能的必要文件。不要创建多余的文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等等

技能只应包含 AI 智能体完成手头任务所需的信息。它不应包含关于"它是怎么被创造出来的"这一过程的辅助上下文、安装与测试流程、面向用户的文档等。创建额外的文档文件只会增加杂乱和困惑。

渐进式披露设计原则

技能使用三级加载系统来高效管理上下文：

1. 元数据（name + description） —— 始终在上下文中（约 100 词）
2. SKILL.md 正文 —— 技能触发时加载（少于 5000 词）
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 技能的 description 示例："Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"

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

正文

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

第 5 步：打包技能

技能开发完成后，必须打包成一个可分发的 .skill 文件交给用户。打包流程会先自动校验该技能，确保它满足所有要求：

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

可选指定输出目录：

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

打包脚本会：

1. 校验 技能，自动检查：
   • YAML frontmatter 格式和必需字段
   • 技能命名规范和目录结构
   • Description 的完整性和质量
   • 文件组织和资源引用
2. 打包 技能（如果校验通过），创建一个以技能命名的 .skill 文件（例如 my-skill.skill），其中包含所有文件并保持正确的分发目录结构。.skill 文件是一个扩展名为 .skill 的 zip 文件。

如果校验失败，脚本会报告错误并退出，不创建包。修复校验错误后重新运行打包命令。

第 6 步：迭代

测试技能之后，用户可能会要求改进。这通常发生在刚用过技能之后，因为他们对技能表现如何有最新的直观感受。

迭代流程：

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