Skill Creator

本 Skill 提供创建高效 Skill 的指导。

关于 Skill

Skill 是模块化、自包含的软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可将其视作特定领域或任务的“上手指南”——它们将 Claude 从通用型智能体转变为具备程序性知识的专用智能体；而这类程序性知识是任何大语言模型都无法完全内化的。

Skill 提供的内容

1. 专业化工作流：面向特定领域的多步骤操作流程
2. 工具集成：与特定文件格式或 API 协同工作的说明
3. 领域专长：公司专属知识、数据结构（schema）、业务逻辑
4. 捆绑资源：用于复杂或重复性任务的脚本、参考资料及配套资产

核心设计原则

简洁性至关重要

上下文窗口是一种公共资源。Skill 必须与其他所有 Claude 所需内容共享该窗口：系统提示（system prompt）、对话历史、其他 Skill 的元数据，以及用户的实际请求。

默认假设：Claude 已经非常聪明。 仅添加 Claude 当前不具备的上下文信息。对每一处新增内容都应提出质疑：“Claude 真的需要这段解释吗？”以及“该段落是否值得其占用的 token 成本？”

优先采用简洁示例，而非冗长说明。

设定恰当的自由度

根据任务的脆弱性与可变性，匹配相应级别的具体程度：

高自由度（纯文本指令）：适用于多种解法均有效、决策高度依赖上下文，或需启发式方法引导的情形。

中自由度（带参数的伪代码或脚本）：适用于存在首选模式、允许一定变化，或行为受配置影响的情形。

低自由度（具体脚本，参数极少）：适用于操作易出错、一致性要求极高，或必须严格遵循固定顺序的情形。

可将 Claude 视为在路径上探索：若路径是一条两侧悬崖的狭窄桥梁，则需设置明确护栏（低自由度）；若是一片开阔原野，则允许多种通行路线（高自由度）。

Skill 的组成结构

每个 Skill 均包含一个必需的 SKILL.md 文件，以及若干可选的捆绑资源：

skill-name/
├── SKILL.md （必需）
│   ├── YAML 前置元数据（必需）
│   │   ├── name: （必需）
│   │   ├── description: （必需）
│   │   └── compatibility: （可选，极少使用）
│   └── Markdown 格式说明（必需）
└── 捆绑资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 文档资料，按需加载至上下文中
    └── assets/           - 用于输出内容的文件（模板、图标、字体等）

SKILL.md（必需）

每个 SKILL.md 文件均由以下两部分构成：

• 前置元数据（YAML 格式）：包含必需字段 name 和 description，以及可选字段如 license、metadata 和 compatibility。Claude 仅读取 name 和 description 字段以判断 Skill 是否触发，因此请清晰、全面地描述该 Skill 的功能及其适用场景。字段 compatibility 用于注明环境依赖（目标产品、系统包等），但绝大多数 Skill 并不需要此字段。
• 正文（Markdown 格式）：使用该 Skill 的说明与指引。仅在 Skill 触发后（如有必要）才被加载。

捆绑资源（可选）

脚本（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 规范）
• 典型用途：数据库结构（schema）、API 文档、领域知识、公司政策、详细工作流指南
• 优势：保持 SKILL.md 轻量；仅当 Claude 判定必要时才加载
• 最佳实践：若文件过大（>10k 词），应在 SKILL.md 中加入 grep 检索模式
• 避免重复：信息应仅存在于 SKILL.md 或参考资料文件之一，不可同时出现在两者中。除非信息确属 Skill 的核心逻辑，否则应优先存于参考资料文件中——这既可维持 SKILL.md 的简洁性，又能确保信息可发现且不挤占上下文窗口。仅将关键的程序性操作步骤与工作流指引保留在 SKILL.md 中；将详细的参考资料、结构定义（schema）和示例移至参考资料文件中。

资产（assets/）

不用于加载至上下文，而是嵌入 Claude 输出结果中的文件。

• 何时引入：当 Skill 需要某些文件参与最终输出时
• 示例：assets/logo.png（品牌资产）、assets/slides.pptx（PowerPoint 模板）、assets/frontend-template/（HTML/React 脚手架）、assets/font.ttf（字体文件）
• 典型用途：模板、图片、图标、脚手架代码、字体、待复制或修改的样例文档
• 优势：将输出资源与文档分离；使 Claude 能调用文件而无需将其载入上下文

Skill 中不应包含的内容

Skill 应仅包含直接支撑其功能所必需的文件。切勿添加无关文档或辅助性文件，包括：

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

Skill 应仅包含 AI 智能体完成当前任务所需的信息，不得包含有关 Skill 创建过程本身的附加背景（如开发流程、安装测试步骤、面向用户的说明文档等）。额外文档只会增加混乱与干扰。

渐进式披露设计原则

Skill 采用三级加载机制，以高效管理上下文：

1. 元数据（name + description）：始终驻留于上下文中（约 100 词）
2. SKILL.md 正文：仅在 Skill 触发时加载（<5k 词）
3. 捆绑资源：Claude 按需加载（无上限，因脚本可不经上下文直接执行）

渐进式披露模式

为最小化上下文膨胀，请将 SKILL.md 正文控制在核心内容范围内，且不超过 500 行。接近该限制时，应将内容拆分至独立文件。拆分时，务必在 SKILL.md 中显式引用这些文件，并清晰说明其适用场景，确保 Skill 的使用者了解其存在及调用时机。

核心原则：当 Skill 支持多种变体、框架或选项时，仅将核心工作流与选择指引保留在 SKILL.md 中；将各变体特有细节（模式、示例、配置）移至独立的参考资料文件中。

模式 1：高层级指南 + 参考链接

# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
[code example]

## 高级功能

- **表单填写**：详见 [FORMS.md](FORMS.md) 完整指南  
- **API 参考**：详见 [REFERENCE.md](REFERENCE.md) 全部方法  
- **示例**：详见 [EXAMPLES.md](EXAMPLES.md) 常见模式

Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于覆盖多个领域的 Skill，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md （概览与导航）
└── reference/
    ├── finance.md （营收、计费指标）
    ├── sales.md （销售机会、销售漏斗）
    ├── product.md （API 使用量、功能）
    └── marketing.md （营销活动、归因分析）

当用户询问销售指标时，Claude 仅读取 sales.md。

同理，对于支持多种框架或变体的 Skill，亦可按变体组织：

cloud-deploy/
├── SKILL.md （工作流 + 云服务商选择）
└── references/
    ├── aws.md （AWS 部署模式）
    ├── gcp.md （GCP 部署模式）
    └── azure.md （Azure 部署模式）

当用户选择 AWS 时，Claude 仅读取 aws.md。

模式 3：条件化细节展开

先展示基础内容，再链接至高级内容：

# DOCX 处理

## 创建文档

使用 docx-js 创建新文档。详见 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档

简单编辑可直接修改 XML。

**处理修订痕迹（tracked changes）**：详见 [REDLINING.md](REDLINING.md)  
**了解 OOXML 细节**：详见 [OOXML.md](OOXML.md)

Claude 仅在用户需要对应功能时才读取 REDLINING.md 或 OOXML.md。

重要规范：

• 避免深度嵌套引用：所有参考资料文件应仅一层嵌套，即全部直接从 SKILL.md 引用。
• 结构化长篇参考资料：对超过 100 行的参考资料文件，应在顶部添加目录（Table of Contents），便于 Claude 在预览时快速掌握全文范围。

Skill 创建流程

Skill 创建包含以下步骤：

1. 通过具体示例理解 Skill
2. 规划可复用的 Skill 内容（脚本、参考资料、资产）
3. 初始化 Skill（运行 init_skill.py）
4. 编辑 Skill（实现资源并撰写 SKILL.md）
5. 打包 Skill（运行 package_skill.py）
6. 基于真实使用反馈持续迭代

请严格按序执行上述步骤；仅当有明确理由表明某步不适用时，方可跳过。

步骤 1：通过具体示例理解 Skill

仅当 Skill 的使用模式已十分明确时，方可跳过本步骤；即使针对已有 Skill 进行优化，本步骤依然具有价值。

为构建高效 Skill，必须清晰理解其具体使用方式。这种理解可源于用户提供的真实用例，或经用户反馈验证的生成用例。

例如，在构建图像编辑 Skill 时，可提出如下问题：

• “图像编辑 Skill 应支持哪些功能？编辑、旋转，还有其他吗？”
• “您能否提供一些该 Skill 的具体使用示例？”
• “我设想用户可能会提出类似‘去除这张图片的红眼’或‘旋转这张图片’的需求。您还想到其他使用场景吗？”
• “用户会说什么话来触发该 Skill？”

为避免给用户造成负担，请勿在单条消息中提出过多问题。应优先聚焦最关键的问题，再视需要跟进补充提问以提升效果。

当已明确 Skill 应支持的功能范围时，本步骤即告完成。

步骤 2：规划可复用的 Skill 内容

为将具体示例转化为高效 Skill，需逐条分析每个示例：

1. 思考如何从零开始执行该示例
2. 识别在重复执行此类工作流时，哪些脚本、参考资料和资产将带来帮助

示例：构建 pdf-editor Skill 以响应“帮我旋转这份 PDF”类请求时，分析表明：

1. PDF 旋转每次均需重写相同代码
2. 在 Skill 中内置 scripts/rotate_pdf.py 脚本将十分有用

示例：设计 frontend-webapp-builder Skill 以响应“为我构建一个待办事项应用”或“为我构建一个追踪步数的仪表盘”类请求时，分析表明：

1. 每次编写前端 Web 应用均需重复相同的 HTML/React 脚手架代码
2. 在 Skill 中内置含脚手架 HTML/React 项目文件的 assets/hello-world/ 模板将十分有用

示例：构建 big-query Skill 以响应“今日有多少用户已登录？”类查询时，分析表明：

1. 每次查询 BigQuery 均需重新探查表结构（schema）与关联关系
2. 在 Skill 中内置记录表结构的 references/schema.md 文件将十分有用

为确立 Skill 的内容构成，请逐一分析每个具体示例，整理出需纳入的可复用资源清单：脚本、参考资料、资产。

步骤 3：初始化 Skill

此时正式进入 Skill 创建阶段。

仅当所开发 Skill 已存在，且当前仅需迭代或打包时，方可跳过本步骤；此时请直接进入下一步。

从零新建 Skill 时，务必运行 init_skill.py 脚本。该脚本将便捷地生成一个完整模板 Skill 目录，自动包含 Skill 所需全部要素，大幅提升创建效率与可靠性。

用法：

scripts/init_skill.py  --path 

该脚本将：

• 在指定路径下创建 Skill 目录
• 生成含标准前置元数据及 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在各目录中添加可定制或删除的示例文件

初始化完成后，请按需定制或删除生成的 SKILL.md 及示例文件。

步骤 4：编辑 Skill

编辑（新生成或既有）Skill 时，请牢记：该 Skill 是为另一个 Claude 实例而设计。请提供对 Claude 有益且非显而易见的信息。思考哪些程序性知识、领域特有细节或可复用资产，能帮助另一实例更高效地执行任务。

学习成熟的设计模式

请根据 Skill 的实际需求，参考以下实用指南：

• 多步骤流程：参阅 references/workflows.md 获取顺序工作流与条件逻辑示例
• 特定输出格式或质量标准：参阅 references/output-patterns.md 获取模板与示例模式

这些文件汇总了经过验证的 Skill 设计最佳实践。

从可复用的 Skill 内容入手

实施初期，请优先处理前述识别出的可复用资源：scripts/、references/ 和 assets/ 文件。注意，此步骤可能需用户提供输入。例如，在实现 brand-guidelines Skill 时，用户可能需提供品牌资产或模板存入 assets/，或提供文档存入 references/。

新增脚本必须通过实际运行进行测试，以确保无缺陷且输出符合预期。若存在大量相似脚本，可仅测试代表性样本，以在保证信心的同时平衡交付时效。

任何对 Skill 无用的示例文件与目录均应删除。初始化脚本在 scripts/、references/ 和 assets/ 中创建示例文件仅为展示结构，大多数 Skill 并不需要全部示例。

更新 SKILL.md

撰写规范：始终使用祈使式 / 不定式表达。

前置元数据

编写含 name 和 description 字段的 YAML 前置元数据：

• name：Skill 名称
• description：这是 Skill 的主要触发机制，帮助 Claude 判断何时启用该 Skill。
  • 需同时说明 Skill 的功能，以及其具体触发条件与适用上下文。
  • 所有“何时使用”信息均应在此处体现——而非正文中。“何时使用本 Skill”类章节置于正文中对 Claude 无意义，因正文仅在触发后加载。
  • docx Skill 的描述示例：“全面支持 .docx 文档的创建、编辑与分析，涵盖修订痕迹（tracked changes）、批注、格式保留及文本提取等功能。当 Claude 需处理专业文档（.docx 文件）时启用，包括：（1）创建新文档，（2）修改或编辑内容，（3）处理修订痕迹，（4）添加批注，或其他任何文档相关任务。”

YAML 前置元数据中请勿添加其他字段。

正文

撰写使用该 Skill 及其捆绑资源的操作指引。

步骤 5：打包 Skill

Skill 开发完成后，需打包为可分发的 .skill 文件供用户使用。打包过程将首先自动校验 Skill，确保其满足全部要求：

scripts/package_skill.py 

指定可选输出目录：

scripts/package_skill.py  ./dist

打包脚本将执行以下操作：

1. 校验：自动校验 Skill，检查项包括：

   • YAML 前置元数据格式及必需字段
   • Skill 命名规范与目录结构
   • 描述完整性与质量
   • 文件组织结构与资源引用

2. 打包：校验通过后，生成以 Skill 名命名的 .skill 文件（如 my-skill.skill），其中包含全部文件并维持正确目录结构以便分发。.skill 文件本质为扩展名为 .skill 的 ZIP 包。

若校验失败，脚本将报告错误并退出，不生成包。请修复所有校验错误后，再次运行打包命令。

步骤 6：迭代优化

Skill 测试完成后，用户可能提出改进建议。此类反馈往往紧随 Skill 使用之后，且带有对实际表现的最新认知。

迭代工作流：

1. 在真实任务中使用 Skill
2. 识别执行中的困难或低效环节
3. 明确 SKILL.md 或捆绑资源应如何更新
4. 实施变更并再次测试