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 frontmatter 元数据（必需）
│   │   ├── name: （必需）
│   │   └── description: （必需）
│   └── Markdown 格式说明（必需）
└── 捆绑资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 文档资料，按需加载至上下文中
    └── assets/           - 用于输出内容的文件（模板、图标、字体等）

SKILL.md（必需）

每个 SKILL.md 文件均包含以下两部分：

• Frontmatter（YAML 格式）：包含 name 和 description 字段。这是 Claude 判断是否启用该 Skill 的唯一依据，因此必须清晰、全面地描述 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 或 references/ 文件中，不可两者兼有。除非信息确为核心逻辑，否则应优先存于 references/ 文件中——此举既保持 SKILL.md 轻量，又确保信息可发现性，同时不挤占上下文窗口。仅在 SKILL.md 中保留必要的程序性操作说明与工作流指引；将详细的参考材料、schema 和示例移至 references/ 文件中。

资源（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 中保留核心工作流与选择指引；将变体特有细节（模式、示例、配置）移至独立的 reference 文件中。

模式 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。

**带修订标记的编辑**：详见 [REDLINING.md](REDLINING.md)  
**OOXML 细节说明**：详见 [OOXML.md](OOXML.md)

Claude 仅在用户需要对应功能时，才加载 REDLINING.md 或 OOXML.md。

重要规范：

• 避免深度嵌套引用 —— 引用层级应限制为从 SKILL.md 出发的一层。所有 reference 文件必须直接由 SKILL.md 引用。
• 长 reference 文件结构化 —— 对超过 100 行的 reference 文件，在顶部添加目录（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，须清晰掌握其具体使用场景。此类理解可来源于真实用户示例，或经用户反馈验证过的生成示例。

例如，构建 image-editor Skill 时，可提出如下问题：

• “该 image-editor Skill 应支持哪些功能？编辑、旋转，还有其他吗？”
• “能否举几个该 Skill 的典型使用示例？”
• “我设想用户可能会说‘去除这张图片的红眼’或‘旋转这张图片’。您还想到其他使用方式吗？”
• “用户会说什么话触发该 Skill？”

为避免给用户造成困扰，切勿在单条消息中提出过多问题。应优先聚焦最关键的问题，再视需要逐步跟进以提升有效性。

当对 Skill 应支持的功能形成清晰认知时，本步骤即告完成。

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

为将具体示例转化为高效 Skill，应对每个示例进行如下分析：

1. 从零开始执行该示例所需的操作路径
2. 识别在重复执行此类工作流时，哪些脚本、参考资料和资源会带来帮助

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

1. PDF 旋转每次都需要重写相同代码
2. 将 scripts/rotate_pdf.py 脚本纳入 Skill 将十分有用

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

1. 前端 Web 应用每次都需要相同的 HTML/React 脚手架
2. 将含标准 HTML/React 项目文件的 assets/hello-world/ 模板纳入 Skill 将十分有用

示例：构建 big-query Skill 以响应“今天有多少用户登录了？”类请求时，分析表明：

1. 查询 BigQuery 每次都需要重新梳理表结构与关联关系
2. 将记录表结构的 references/schema.md 文件纳入 Skill 将十分有用

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

步骤 3：初始化 Skill

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

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

若从零开始创建新 Skill，务必运行 init_skill.py 脚本。该脚本可便捷生成符合全部要求的新 Skill 目录模板，显著提升 Skill 创建的效率与可靠性。

用法：

scripts/init_skill.py  --path 

该脚本将：

• 在指定路径下创建 Skill 目录
• 生成含正确 frontmatter 与 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/。

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

所有与 Skill 无关的示例文件与目录均应删除。初始化脚本会在 scripts/、references/ 和 assets/ 中生成示例文件以演示结构，但大多数 Skill 并不需要全部示例。

更新 SKILL.md

撰写规范：始终使用祈使式/不定式语法。

Frontmatter

编写含 name 和 description 字段的 YAML frontmatter：

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

YAML frontmatter 中不得包含其他字段。

正文

撰写关于如何使用该 Skill 及其捆绑资源的说明。

步骤 5：打包 Skill

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

scripts/package_skill.py 

可选指定输出目录：

scripts/package_skill.py  ./dist

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

1. 校验：自动检查以下项目：

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

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

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

步骤 6：迭代优化

完成 Skill 测试后，用户可能提出改进建议。此类反馈通常发生在 Skill 刚被使用之后，用户对实际表现记忆犹新。

迭代工作流：

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