skill-creator

Skill Creator

Skills 是模块化、独立的包，可通过提供专门的知识、工作流和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备程序性知识的专用 Agent，而这些知识是任何模型都无法完全掌握的。Skill 为复杂且重复的任务提供专门的工作流、工具集成、领域专业知识和捆绑资源（脚本、参考资料、素材）。

下文先介绍操作流程；设计细节位于 references/（参见参考文件）。

Skill 创建流程

创建 Skill 包括以下步骤：

1. 通过具体示例了解 Skill
2. 规划可复用的 Skill 内容（脚本、参考资料、素材）
3. 初始化 Skill 目录
4. 编辑 Skill（实现资源并编写 SKILL.md）
5. 打包 Skill（仅在需要可分发的 .skill 文件时）
6. 根据实际使用情况迭代

请按顺序执行这些步骤；仅当有明确理由表明某步骤不适用时才跳过。

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

只有在已经清楚了解 Skill 的使用模式时，才跳过此步骤。即使在处理现有 Skill 时，这一步仍然很有价值。

要创建有效的 Skill，请清楚了解它的具体使用方式。这些信息既可以来自用户直接提供的示例，也可以来自经过用户反馈验证的生成示例。

例如，构建图像编辑器 Skill 时，相关问题包括：

• “图像编辑器 Skill 应支持哪些功能？编辑、旋转，还是其他功能？”
• “你能给出一些这个 Skill 的使用示例吗？”
• “我能想到用户可能会提出‘去掉这张图片中的红眼’或‘旋转这张图片’之类的要求。你还能想到其他使用方式吗？”
• “用户说什么时应该触发这个 Skill？”

为避免让用户应接不暇，请勿在一条消息中提出太多问题。先提出最重要的问题，再根据需要追问，以提升效果。

当明确了解 Skill 应支持的功能后，即可完成此步骤。

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

要将具体示例转化为有效的 Skill，请针对每个示例进行分析：

1. 考虑如何从头执行该示例
2. 确定在反复执行这些工作流时，哪些脚本、参考资料和素材会有所帮助

例如：

• pdf-editor Skill（“帮我旋转这个 PDF”）：旋转 PDF 意味着每次都要重写相同代码，因此应保存为 scripts/rotate_pdf.py。
• frontend-webapp-builder Skill（“帮我构建一个待办应用”）：每个 Web 应用都需要相同的样板内容，因此应保存为 assets/hello-world/ 模板项目。
• big-query Skill（“今天有多少用户登录过？”）：每次查询都要重新查找表结构，因此应保存为 references/schema.md。

要确定 Skill 的内容，请分析每个具体示例，列出应包含的可复用资源：脚本、参考资料和素材。各类资源的用途以及应排除的内容，请参见：references/skill-anatomy.md。

步骤 3：初始化 Skill

如果 Skill 已存在，且只需迭代或打包，请跳过此步骤。

此版本的 skill-creator 不包含任何脚本（Anthropic 上游的 skill-creator 此后已移除其 init_skill.py）。请手动创建骨架：

mkdir -p <skill-name>/scripts <skill-name>/references <skill-name>/assets

然后编写 <skill-name>/SKILL.md：在 frontmatter 中填写 name（与目录名一致：仅使用小写字母、数字和连字符，最多 64 个字符）和 description，再编写正文。仅保留 Skill 会使用的资源目录，除非宿主仓库要求保留全部三个目录（有些仓库会用 .gitkeep 保留这些目录）。

第 4 步：编辑技能

编辑（新生成或现有的）技能时，请记住，该技能是为另一个 Claude 实例创建的。应加入有益且对 Claude 来说并非显而易见的信息。思考哪些流程知识、领域专属细节或可复用资源能帮助另一个 Claude 实例更有效地完成这些任务。

学习成熟的设计模式

根据技能的需求，参考以下实用指南：

• SKILL.md 正在变长，或包含多个变体、框架或领域：参阅 references/progressive-disclosure.md，了解大小限制和拆分模式
• 多步骤流程：参阅 references/workflows.md，了解顺序工作流、条件逻辑和子 Agent 委派模式
• 特定输出格式或质量标准：参阅 references/output-patterns.md，了解模板和示例模式
• 官方示例：浏览 Anthropic 的技能仓库，查看可用于生产环境的示例

复杂任务的专业技巧：

• 使用子 Agent：对于需要大量计算或并行探索的请求，追加“use subagents”
• 保持上下文整洁：将单项子任务交给子 Agent，避免上下文窗口受到干扰
• 将复杂性可视化：让 Claude 绘制新协议和代码库的 ASCII 图，以便更好地理解

从可复用的技能内容开始

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

添加的脚本必须通过实际运行来测试，确保没有错误，且输出符合预期。如果有许多相似脚本，只需测试有代表性的一部分，以确保对它们正常工作的信心，同时兼顾完成时间。

更新 SKILL.md

**写作指南：**始终使用祈使式或不定式形式。

Frontmatter

编写包含 name 和 description 的 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，能帮助 Claude 理解何时使用该技能。
  • 同时说明技能的功能，以及应在何种特定触发条件或情境下使用。
  • 将所有“何时使用”信息都写在此处，不要写在正文中。正文只有在触发后才会加载，因此，在正文中设置“何时使用此技能”部分对 Claude 没有帮助。
  • docx 技能的描述示例：“全面支持文档创建、编辑和分析，包括修订、批注、格式保留和文本提取。Claude 需要处理专业文档（.docx 文件）以完成以下任务时使用：(1) 创建新文档；(2) 修改或编辑内容；(3) 处理修订；(4) 添加批注；或执行其他文档任务。”

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

正文

编写使用该技能及其捆绑资源的说明。正文应少于 500 行且约少于 5,000 个 token：自动压缩后，Claude Code 只会保留已调用技能的前 5,000 个 token，因此应将流程和硬性规则放在前面，并将详细内容移至参考文档。

步骤 5：打包 Skill

仅当用户需要可分发的 .skill 文件时才进行打包（例如，上传到 claude.ai）。Skills 遵循 Agent Skills 开放标准，以便在不同 AI 平台之间移植。.skill 文件是技能文件夹的 zip 归档，扩展名为 .skill，文件名与 Skill 同名（例如，my-skill.skill）。

打包前进行验证：

• YAML frontmatter 可解析，并包含 name 和 description
• name 与文件夹名称一致；description 非空且不超过 1,024 个字符
• 顶层只包含规范规定的六个字段（name、description、license、compatibility、metadata、allowed-tools）——claude.ai 上传和 Skills API 会拒绝任何其他键，因此请从打包副本中移除多余字段
• SKILL.md 引用的每个文件都存在

规范的参考验证器会检查 frontmatter：skills-ref validate <path/to/skill-folder>（skills-ref）。Anthropic 上游的 skill-creator 提供了 scripts/package_skill.py，可在一个步骤中完成验证和打包；此副本未附带该脚本。

步骤 6：迭代

测试 Skill 后，用户可能会要求改进。此类情况通常发生在使用 Skill 后不久，此时用户对 Skill 的表现仍记忆犹新。

迭代工作流：

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

核心原则

简洁至关重要。 上下文窗口是公共资源。Skills 与 Claude 所需的一切内容共享上下文窗口：系统提示词、对话历史、其他 Skills 的元数据，以及用户的实际请求。默认假设：Claude 已经非常聪明。 只添加 Claude 尚不了解的上下文。审视每条信息：“Claude 真的需要这段解释吗？”以及“这段内容值得占用这些 token 吗？”优先使用简洁示例，而非冗长解释。

设定恰当的自由度。 根据任务的脆弱性和可变性匹配具体程度：

• 高自由度（基于文本的指令）：存在多种有效方法、决策取决于上下文，或需要通过启发式方法指导执行。
• 中自由度（伪代码或带参数的脚本）：存在首选模式、允许一定变化，或配置会影响行为。
• 低自由度（具体脚本、参数较少）：操作脆弱且容易出错、一致性至关重要，或必须遵循特定顺序。

可以把 Claude 想象成在探索一条路径：狭窄且两侧是悬崖的桥需要明确的护栏（低自由度），而开阔地带则允许多种路线（高自由度）。

参考文件

文件	何时阅读
references/skill-anatomy.md	规划内容（步骤 2）：布局、脚本、参考资料和资源各自的用途，以及不应包含的内容
references/progressive-disclosure.md	SKILL.md 接近 500 行或约 5,000 个 token，或技能涵盖多个变体时：加载级别、大小限制和三种拆分模式
references/workflows.md	技能包含多步骤流程时：顺序、条件、并行、子 Agent 和检查清单模式
references/output-patterns.md	技能必须生成特定格式或达到特定质量标准时：模板、示例、分层详略

官方资源： Agent Skills 仓库 · 技能编写最佳实践 · Agent Skills 规范 · Claude Code 技能 · 创建自定义技能 · 构建 Claude 技能完整指南（PDF）

改编自 Anthropic 的 skill-creator（github.com/anthropics/skills，Apache-2.0，参见 LICENSE.txt）。为适配 claude-mods，已将操作流程移至前面，并将设计细节移至 参考资料中，以符合大小限制；由于未捆绑脚本，已重写步骤 3 和步骤 5； 并在较长的参考资料中添加了目录。