skill-creation-walkthrough

设计、编写和维护你自己的 Claude Skills 的指南。介绍何时适合用 Skill 解决问题、如何撰写真正能触发 Skill 的描述、如何组织 SKILL.md 和参考文件，以及如何测试和迭代。

适用场景

• 你发现自己反复编写相同的提示词或说明。
• 你想打包一个工作流或框架以便重复使用。
• 你现有的 Skill 在应该触发时却没有触发。
• 你正在发布 Skill 供他人使用。
• 你想教 Claude 按特定领域的方式工作。
• 你正在审查他人编写的 Skill，需要一套质量标准。

不适用场景

• 一次性提示词（直接编写提示词即可）。
• 应该放在系统上下文中，而不是渐进式披露的信息。
• 更改 Claude 在所有对话中的整体行为（使用 Claude.ai 设置或系统提示词，而不是 Skill）。
• 替代工具调用（Skill 是说明，不是工具）。

必需输入

• 你想编码的任务或工作流。
• 目标受众：谁会触发这个 Skill，以及会在什么类型的对话中触发。
• 现有材料：你用过的提示词、写过的文档、优质输出示例。

框架：Skill 的工作方式

Skill 是一个包含 SKILL.md 文件的文件夹。SKILL.md 包含 YAML 前置信息（名称和描述）以及说明正文。它还可以包含参考文件、脚本或模板，并在需要时加载。

其关键特性是：渐进式披露。Claude 不会在每轮对话中读取所有 Skill。Skill 描述会放在系统提示词中。只有在触发 Skill 时，才会加载 SKILL.md 正文和参考文件。这样，用户就可以拥有数百个 Skill，而不会让上下文变得臃肿。

这对你意味着：

• 描述决定一切，负责触发 Skill。写好描述，否则 Skill 永远不会加载。
• SKILL.md 正文用于说明工作流本身。
• 参考文件用于存放无需在每次调用时都加载的内容：长清单、模板、示例和深入参考资料。

工作流

阶段 1：判断 Skill 是否适合

并非所有内容都应该做成 Skill。请进行以下检查：

适合做成 Skill 的迹象	不适合做成 Skill 的迹象
你重复同一工作流 5 次以上。	你只用过一次。
输出需要保持一致的结构。	每次输出都是定制的。
任务有明确的触发条件（问题类型、文件类型或领域）。	任务本来就是每次对话的一部分。
说明超过 200 个词。	一条系统说明就够了。
模板或参考资料会有所帮助。	纯文本就足够了。
其他人也可能受益于同一工作流。	只与你的单个项目相关。

如果你的大多数答案都在左栏，就构建一个 Skill。否则，使用已保存的提示词或系统说明。

阶段 2：定义触发条件

开始编写之前，先问自己：什么时候应该加载这个 Skill？

要具体。写下应该触发它的确切短语或情境。例如：

• “当用户要求编写创意简报、启动会议文档或项目简报时。”
• “当用户上传 CSV 并要求进行表格数据分析时。”
• “当用户询问‘如何让 X 获得更高排名’、‘是否应该添加 schema’，或提出任何与 SEO 相关的问题时。”
• “当用户提到想要挑选供应商或比较工具时。”

触发条件是描述的职责。如果你无法清晰地阐明触发条件，这个 Skill 就无法可靠地加载。

阶段 3：编写描述

这是你的技能中最重要的一句话（或两句话）。描述会显示在 Claude 的系统提示词中，供其判断是否加载该技能。

优秀的描述包含 4 个部分：

1. 它的作用（一句以行动为导向的话）。
2. 何时使用（触发短语或情境）。
3. 边缘情况，用“也会在……时触发”来捕捉不那么明显的情形。
4. 适用于……（受众或使用场景，有助于消除歧义）。

糟糕的描述：

“帮助处理 SEO。”

为什么不行：过于笼统，没有触发短语，而且用户真正需要它时也不会触发。

优秀的描述：

“审核单个 URL 或少量页面的页面 SEO。用户要求进行页面审核、想优化标题和元描述、询问‘为什么这个页面没有排名’，或分享 URL 并询问哪里出了问题时使用。用户提到 Core Web Vitals、内链或 schema 标记时也会触发。适用于单个页面审查和小批量审核。”

为什么有效：明确具体的操作、多种触发短语、边缘情况和清晰的受众范围。

阶段 4：组织 SKILL.md 正文

结构一致能让技能更易读、维护，也更适合 AI。以下模式适用于大多数技能：

---
name: [your-skill-name]
description: [your description]
---

[One-sentence purpose statement]

## When to use
[Bulleted list of trigger situations]

## When NOT to use
[Bulleted list, ideally redirecting to sibling skills]

## Required inputs
[What Claude needs from the user to run this skill]

## The framework
[The durable IP: the model, the steps, the dimensions, the layers]

## Workflow
[Numbered steps Claude follows]

## Failure patterns
[Common mistakes to avoid or push back on]

## Output format
[What the deliverable looks like]

## Reference files
[List of files in the references/ folder with descriptions]

并非每个技能都需要所有章节。有些技能纯粹是操作指南，可以省略“框架”章节。有些技能侧重示例，可以添加“示例”章节。先将此结构作为起点，再根据需要调整。

阶段 5：为不适合放在 SKILL.md 中的内容添加参考资料

参考资料是渐进式披露的第二层。Claude 读取时才会加载，而不是默认加载。

以下内容适合放在参考资料中：

• 长清单（例如包含 100 项的审核清单）。
• 带有完整示例的模板。
• 针对特定场景的详细操作手册。
• 规范链接、术语表、决策表等参考资料。
• 超过 100 行且并非每次调用都需要的任何内容。

每份参考资料都应独立完整。结合技能提供的上下文，读者（或 Claude）应能在不先阅读 SKILL.md 的情况下使用它。

可用的命名模式：

• 模板使用 references/[noun]-template.md。
• 清单使用 references/[noun]-checklist.md。
• 端到端运行手册使用 references/[noun]-playbook.md。
• 完整示例使用 references/example-[scenario].md。

在 SKILL.md 的“参考文件”章节中引用参考文件，并用一行文字说明每个文件的内容。

阶段 6：测试并迭代

技能第一次通常无法正常工作。请做好迭代的准备。

测试清单：

• 触发测试：在新对话中输入触发短语。技能是否加载？如果没有，说明描述范围太窄或有误。
• 边缘情况测试：输入一段应通过“也会在……时触发”条款触发的内容。技能是否触发？
• 误报测试：输入一段接近但实际无关的内容。技能是否避免加载？如果它总是加载，说明描述范围太广。
• 输出测试：让技能处理一项真实任务。输出是否符合预期？
• 长度测试：SKILL.md 是否少于 250 行？参考资料是否少于 400 行？如果不是，请拆分或精简。

测试后，常见的修复方法：

• 技能未触发 → 扩大描述范围，添加明确短语，并加入“也会在……时触发”。
• 技能触发过于频繁 → 缩小描述范围，添加“以下情况不要触发”，并更具体地说明受众。
• 输出过于笼统 → 添加更清晰的框架或更具体的工作流。
• 参考资料令人应接不暇 → 拆分为多份参考资料，并让每份内容各有侧重。

深入探讨：描述的组成

描述很难写好。以下详细介绍其公式。

句子 1：它的作用

以动词开头。描述要具体。

• 好：“审核页面 SEO。”
• 不好：“帮助处理 SEO 相关事宜。”

句子 2：何时使用

说明主要触发条件。使用用户实际会说的短语。

• 好："当用户要求审核页面、想要优化标题和元描述，或询问‘为什么这个页面没有排名’时使用。"
• 不好："用于 SEO 改进。"

句子 3：「也会在……时触发」

涵盖次要触发条件和边缘情况。

• 好："当用户提到 Core Web Vitals、内部链接或 schema 标记时也会触发。"
• 不好：（省略）

句子 4：适用于……

说明受众或适用范围，以帮助区分。

• 好："适用于单个页面审查和小批量审核。"
• 不好：（省略）

如果你的技能描述只有一句话，那它可能不够具体。

深入探讨：实践示例

假设你经常编写技术复盘文档，并希望将其转化为技能。

步骤 1：判断它是否适合做成技能。 你每年撰写 5 篇以上复盘，输出内容能从一致性中受益，团队中的其他人也会使用它。没错，创建一个技能。

步骤 2：触发条件。 "当用户想撰写事后复盘、回顾总结或行动后报告时。当事件发生后，我们要审查哪里出了问题时。"

步骤 3：描述。

"在事件、服务中断或重大项目失败后撰写结构化复盘。用户提到 post-mortem、retrospective、after-action report、RCA，或在事件发生后询问‘为什么会出错’时使用。当用户想记录发布、项目未达预期或事件复盘会议中的经验教训时也会触发。适用于技术事件、项目回顾和团队学习评审。"

步骤 4：SKILL.md 正文。 使用标准结构。必需输入（时间线、影响、参与者）。框架（五个为什么、促成因素、行动项）。工作流（收集事实、起草、审查、分发）。常见失败模式（归咎于人、行动项含糊、没有后续跟进）。

步骤 5：参考资料。 创建一个 post-mortem-template.md，包含文档结构；再创建一个 facilitator-checklist.md，用于主持复盘会议。

步骤 6：测试。 对“昨天发生了服务中断，你能帮我写复盘吗？”应触发。对“什么是事后复盘？”也应该触发。对“我们来回顾一下这个季度吧。”不应触发（这是另一种类型的回顾）。

不断迭代，直到触发条件正常工作，然后发布。

失败模式

• 描述过于狭窄。 描述要求用户使用特定短语，而用户实际上不会这么说，因此技能从不触发。
• 描述过于宽泛。 技能频繁触发，包括处理无关任务时。
• 没有触发短语。 描述说明了技能的功能，却没有说明何时加载。触发效果不可靠。
• SKILL.md 过长。 1,000 行的 SKILL.md 违背了渐进式披露的初衷。应拆分到参考资料中。
• 参考资料与 SKILL.md 内容重复。 如果参考资料重复正文中的内容，应删掉其中一处。
• 没有“何时不使用”。 与同类技能重叠的技能会导致加载时难以区分。应明确交叉引用同类技能。
• 没有示例。 没有实践示例的框架很难应用。至少在参考资料中加入一个示例。
• 只针对一个示例优化。 围绕单一用例编写的技能无法适用于相邻场景。应进行概括。
• 没有迭代。 技能发布后就再也不更新。技能会逐渐过时。每年审核一次。
• 在公开技能中加入品牌或特定产品假设。 通用技能不应将你的技术栈写死。公开技能应教授方法论（框架、决策标准、分类体系、反模式）；实现细节（特定页面架构、类型定义、组件代码、特定框架的模式）应放在内部操作手册中。完整规范以及这为何关系到用户成果的原因，请参阅 references/methodology-vs-implementation.md。

输出格式

使用此技能创建另一个技能时，请交付：

1. 触发条件分析：简要列出应触发该技能的短语和情境。
2. 描述草稿：用于 YAML frontmatter 的 2-4 句描述。
3. SKILL.md 正文：遵循标准结构的完整技能正文。
4. 参考文件计划：列出要创建的参考文件，并用一句话描述各文件。
5. 第一个参考文件：至少完整编写一个参考文件，作为起点。
6. 测试计划：提供 3-5 个应触发该技能的测试提示词，以及 2-3 个不应触发的测试提示词。

参考文件

• references/skill-template.md：空白的 SKILL.md 模板，附有各部分的注释说明，可直接复制并填写。
• references/description-cookbook.md：包含常见技能类型（审计、模板、框架、操作指南）描述模式及完整示例的库。
• references/methodology-vs-implementation.md：说明公开技能中应包含哪些内容、哪些内容应保留在内部，以及这项规范对用户成果的重要性。包含审计模式和用于确保技能纯粹聚焦于方法论的编写检查清单。