skill-creation-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate.

本指南将带你逐步完成Claude Skills的设计、编写与维护工作，涵盖判断Skill是否适配你的问题、如何编写能有效触发的描述、SKILL.md与参考资料的结构设计，以及测试和迭代方法。

When to use

适用场景

You catch yourself writing the same prompt or instructions repeatedly.
You want to package a workflow or framework for reuse.
An existing skill of yours is not triggering when it should.
You are publishing skills for others to use.
You want to teach Claude a domain-specific way of working.
You are reviewing a skill someone wrote and need a quality bar.

你发现自己反复编写相同的提示词或指令
你希望将工作流或框架打包以便复用
你现有的Skill未按预期触发
你要发布供他人使用的Skill
你想让Claude掌握特定领域的工作方式
你需要审核他人编写的Skill并设定质量标准

When NOT to use

不适用场景

For one-off prompts (just write the prompt).
For information that should live in system context, not progressive disclosure.
For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills).
For replacing tool calls (skills are instructions, not tools).

一次性提示词场景（直接编写提示词即可）
信息应存于系统上下文而非progressive disclosure的场景
想要改变Claude在所有对话中的通用行为（请使用Claude.ai设置或系统提示词，而非Skill）
替代工具调用（Skill是指令，而非工具）

Required inputs

必要输入

The task or workflow you want to encode.
The audience: who will trigger this skill, in what kind of conversation.
Existing artifacts: prompts you have used, docs you have written, examples of good output.

你要编码的任务或工作流
受众：谁会触发该Skill，在何种对话场景下触发
现有素材：你用过的提示词、编写的文档、优质输出示例

The framework: how skills work

框架原理：Skill的工作机制

A Skill is a folder with a

SKILL.md

file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed.

The key property: progressive disclosure. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context.

What this means for you:

The description is everything for triggering. Get it right or the skill never loads.
The SKILL.md body is for the workflow itself.
The references are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material.

Skill是一个包含

SKILL.md

文件的文件夹。SKILL.md包含YAML前置元数据（名称和描述）以及带有指令的正文，还可包含需要时加载的参考文件、脚本或模板。

核心特性：progressive disclosure。Claude不会在每次交互时读取所有Skill。Skill描述存于系统提示词中，只有当Skill被触发时，才会加载SKILL.md正文和参考资料。这一机制让用户可拥有数百个Skill而不会造成上下文冗余。

这对你的意义：

描述是触发Skill的关键。描述不准确，Skill就永远不会加载
SKILL.md正文用于定义工作流本身
参考资料用于存放无需每次调用都加载的内容：长检查表、模板、示例、深度参考资料

Workflow

工作流程

Phase 1: Decide if a skill is the right shape

阶段1：判断Skill是否适配

Not everything should be a skill. Run this test:

Sign it should be a skill	Sign it should not be
You repeat the same workflow 5+ times.	You used it once.
The output benefits from a consistent structure.	Each output is bespoke.
The task has a clear trigger (a question shape, a file type, a domain).	The task is part of every conversation already.
The instructions exceed 200 words.	A one-line system instruction would do.
Templates or reference material would help.	Pure prose is enough.
Other people might benefit from the same workflow.	Only relevant to your single project.

If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction.

并非所有场景都适合用Skill。请进行以下测试：

适合制作Skill的特征	不适合制作Skill的特征
你重复执行同一工作流5次以上	仅使用过一次
输出受益于统一结构	每次输出都是定制化的
任务有明确触发条件（特定问题类型、文件类型、领域）	任务属于每次对话的常规内容
说明文字超过200词	一行系统指令即可满足需求
模板或参考资料能提供帮助	纯文本描述足够
其他人可能从同一工作流中受益	仅与你的单个项目相关

如果大部分答案属于左列，就构建Skill；否则，使用保存的提示词或系统指令。

Phase 2: Define the trigger

阶段2：定义触发条件

Before writing anything, ask: when should this skill load?

Be concrete. Write down the exact phrases or situations that should trigger it. Examples:

"When the user asks for a creative brief, kickoff doc, or project brief."
"When the user uploads a CSV and wants tabular analysis."
"When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related."
"When the user mentions they want to pick a vendor or compare tools."

The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably.

在开始编写前，先明确：何时应加载该Skill？

请具体化，写下能触发Skill的具体短语或场景示例：

"当用户要求创作创意简报、启动文档或项目简报时"
"当用户上传CSV文件并要求进行表格分析时"
"当用户询问‘如何针对X进行排名’‘我应该添加schema吗’或任何与SEO相关的问题时"
"当用户提到想要选择供应商或对比工具时"

触发条件由描述来实现。如果你无法清晰阐述触发条件，Skill将无法可靠加载。

Phase 3: Write the description

阶段3：编写描述

This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill.

Good descriptions have 4 parts:

What it does (one sentence, action-oriented).
When to use it (the trigger phrases or situations).
Edge cases with "Also triggers when..." (catches less obvious situations).
Useful for... (audience or use cases, helps disambiguation).

Bad description:

"Helps with SEO."

Why it fails: vague, no trigger phrases, will not fire when the user actually needs it.

Good description:

"Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits."

Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity.

这是Skill中最重要的一句话（或两句话）。Claude会通过系统提示词中的描述来决定是否加载Skill。

优质描述包含4部分：

功能（一句话，以行动为导向）
触发场景（触发短语或具体情境）
边缘情况，以“Also triggers when...”开头（覆盖不太明显的场景）
适用人群（受众或使用场景，帮助消除歧义）

糟糕的描述示例：

"帮助处理SEO相关事务"

失败原因：模糊不清，无触发短语，用户真正需要时无法触发

优质描述示例：

"审核单个URL或少量页面的站内SEO。当用户要求进行页面审核、优化标题和元描述、询问‘为什么这个页面没有排名’或分享URL并询问问题所在时使用。当用户提到Core Web Vitals、内部链接或schema标记时也会触发。适用于单个页面评审和小批量审核场景。"

成功原因：有具体动作、多个触发短语、覆盖边缘情况、受众清晰

Phase 4: Structure the SKILL.md body

阶段4：构建SKILL.md正文结构

A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills:

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

[One-sentence purpose statement]

统一的结构让Skill更易读、易维护且更适配AI。以下模式适用于大多数Skill：

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

[一句话目的说明]

When to use

[Bulleted list of trigger situations]

[触发场景的项目符号列表]

When NOT to use

[Bulleted list, ideally redirecting to sibling skills]

[项目符号列表，最好关联到同类Skill]

Required inputs

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

[Claude运行该Skill需要用户提供的内容]

The framework

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

[核心内容：模型、步骤、维度、层级]

Workflow

[Numbered steps Claude follows]

[Claude需遵循的编号步骤]

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]


Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed.

[references/文件夹中的文件列表及描述]


并非所有Skill都需要每个部分。有些纯操作指南类Skill可跳过“framework”部分，有些侧重示例的Skill可添加“Examples”部分。以此结构为起点，按需调整即可。

Phase 5: Add references for what does not belong in SKILL.md

阶段5：添加无需放入SKILL.md的参考资料

References are the second tier of progressive disclosure. They load when Claude reads them, not by default.

Use references for:

Long checklists (a 100-item audit checklist).
Templates with worked examples.
Detailed playbooks for specific scenarios.
Reference material like spec links, glossaries, decision tables.
Anything over 100 lines that not every invocation needs.

Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides.

Naming patterns that work:

```
references/[noun]-template.md
```
for templates.
```
references/[noun]-checklist.md
```
for checklists.
```
references/[noun]-playbook.md
```
for end-to-end runbooks.
```
references/example-[scenario].md
```
for worked examples.

Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each.

参考资料是progressive disclosure的第二层级，只有当Claude读取时才会加载，而非默认加载。

参考资料适用于：

长检查表（包含100项的审核清单）
带示例的模板
特定场景的详细操作手册
参考资料如规范链接、术语表、决策表
任何超过100行且无需每次调用都加载的内容

每个参考资料应独立可用。读者（或Claude）在Skill提供的上下文支持下，无需先阅读SKILL.md即可使用参考资料。

实用的命名模式：

```
references/[noun]-template.md
```
用于模板
```
references/[noun]-checklist.md
```
用于检查表
```
references/[noun]-playbook.md
```
用于端到端操作手册
```
references/example-[scenario].md
```
用于示例

在SKILL.md的“Reference files”部分引用参考资料，并为每个文件添加一句话描述。

Phase 6: Test and iterate

阶段6：测试与迭代

Deep dive: description anatomy

深入解析：描述的构成

The description is hard to get right. Here is the formula in detail.

写好描述并不容易，以下是详细的公式：

Sentence 1: What it does

第1句：功能

Lead with the verb. Be specific.

Good: "Audit on-page SEO."
Bad: "Help with SEO things."

以动词开头，具体明确

优质："Audit on-page SEO"
糟糕："Help with SEO things"

Sentence 2: When to use it

第2句：触发场景

State the primary triggers. Use phrases users would actually say.

Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'."
Bad: "Use for SEO improvements."

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

优质："Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'"
糟糕："Use for SEO improvements"

Sentence 3: "Also triggers when..."

第3句："Also triggers when..."

Catch the secondary triggers and edge cases.

Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup."
Bad: (omitted)

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

优质："Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup"
糟糕：（省略）

Sentence 4: Useful for...

第4句：适用人群

Explain audience or scope to help with disambiguation.

Good: "Useful for both individual page reviews and small-batch audits."
Bad: (omitted)

If your skill description is one sentence, it is probably not specific enough.

说明受众或范围，帮助消除歧义

优质："Useful for both individual page reviews and small-batch audits"
糟糕：（省略）

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

Deep dive: worked example

深入解析：实战示例

Imagine you keep writing technical post-mortem documents and want to skill-ify it.

Step 1: Decide it's a skill. You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill.

Step 2: Trigger. "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong."

Step 3: Description.

"Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews."

Step 4: SKILL.md body. Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up).

Step 5: References. A

post-mortem-template.md

with the document structure and a

facilitator-checklist.md

for running the post-mortem meeting.

Step 6: Test. Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro).

You iterate until the triggers fire correctly, then ship.

假设你经常编写技术事后复盘文档，想要将其转化为Skill。

步骤1：确定制作Skill。你每年编写5份以上复盘文档，输出受益于统一结构，团队其他成员也会使用。因此，适合制作Skill。

步骤2：触发条件。"当用户想要编写事后复盘、回顾或行动后报告时；当发生事件并需要回顾问题原因时"

步骤3：描述

"事件、故障或重大项目失败后，编写结构化的事后复盘文档。当用户提到事后复盘、回顾、行动后报告、RCA，或在事件发生后询问‘为什么会出问题’时使用。当用户想要记录发布、项目失误或事件复盘的经验教训时也会触发。适用于技术事件、项目回顾和团队学习复盘场景。"

步骤4：SKILL.md正文。使用标准结构，包含必要输入（时间线、影响、参与人员）、框架（五问法、影响因素、行动项）、工作流（收集事实、起草、评审、分发）、失败模式（指责、模糊的行动项、无跟进）。

步骤5：参考资料。包含

post-mortem-template.md

（文档结构）和

facilitator-checklist.md

（复盘会议主持清单）。

步骤6：测试。输入“我们昨天发生了故障，你能帮我写事后复盘吗？”应触发Skill；输入“什么是事后复盘？”也应触发；输入“我们来回顾一下本季度情况”不应触发（这是另一种类型的回顾）。

迭代调整至触发条件正常工作后，即可发布。

Failure patterns

常见失败模式

Description too narrow. The skill never fires because your description requires exact phrases the user does not say.
Description too broad. The skill fires constantly, including for unrelated tasks.
No trigger phrases. The description describes what the skill does but not when to load it. Triggering is unreliable.
SKILL.md too long. A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references.
References that duplicate SKILL.md. If a reference repeats what the body says, prune one.
No "When NOT to use". Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly.
No examples. A framework without a worked example is hard to apply. Include at least one in the reference material.
Optimizing for one example. A skill written around your single use case fails at adjacent ones. Generalize.
No iteration. Shipping a skill once and never revisiting it. Skills decay. Audit yearly.
Branding or product-specific assumptions in a public skill. Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See
```
references/methodology-vs-implementation.md
```
for the full discipline and the user-outcome reasons it matters.

描述范围过窄：Skill从未触发，因为描述要求用户使用特定短语，但用户实际不会这么说
描述范围过宽：Skill频繁触发，包括无关任务
无触发短语：描述只说明了Skill的功能，未说明何时加载，导致触发不可靠
SKILL.md过长：1000行的SKILL.md违背了progressive disclosure的初衷，应拆分为参考资料
参考资料与SKILL.md重复：如果参考资料重复了正文内容，需删减其中一方
无“不适用场景”：与同类Skill重叠的Skill会被模糊加载，需明确关联同类Skill
无示例：没有示例的框架难以应用，应在参考资料中至少包含一个示例
过度优化单个示例：围绕单个用例编写的Skill无法适配相邻场景，需泛化处理
无迭代：发布Skill后不再更新，Skill会逐渐失效，应每年审核一次
公开Skill中包含品牌或产品特定假设：通用Skill不应硬编码你的技术栈。公开Skill应传授方法论（框架、决策标准、分类体系、反模式）；实现细节（特定页面架构、类型定义、组件代码、框架特定模式）应存于内部操作手册。详见
```
references/methodology-vs-implementation.md
```
了解完整规范及其对用户体验的重要性。

Output format

输出格式

When using this skill to create another skill, deliver:

Trigger analysis: a short list of phrases and situations that should fire the skill.
Description draft: the 2-4 sentence description for the YAML frontmatter.
SKILL.md body: the full body of the skill, following the standard structure.
Reference plan: a list of reference files to create with one-line descriptions.
First reference file: at least one reference written end to end as a starting point.
Test plan: 3-5 test prompts that should trigger the skill, plus 2-3 that should not.

使用本Skill创建其他Skill时，需交付以下内容：

触发条件分析：应触发Skill的短语和场景的简短列表
描述草稿：用于YAML前置元数据的2-4句话描述
SKILL.md正文：遵循标准结构的完整Skill正文
参考资料规划：待创建的参考文件列表及一句话描述
初始参考文件：至少一份完整编写的参考文件作为起点
测试计划：3-5个应触发Skill的测试提示词，以及2-3个不应触发的提示词

Reference files

参考文件

```
references/skill-template.md
```
: A blank SKILL.md template with annotated section guidance, ready to copy and fill in.
```
references/description-cookbook.md
```
: A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs).
```
references/methodology-vs-implementation.md
```
: What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure.

```
references/skill-template.md
```
：带注释的空白SKILL.md模板，可直接复制填写
```
references/description-cookbook.md
```
：描述模式库，包含常见Skill类型（审核、模板、框架、指南）的实战示例
```
references/methodology-vs-implementation.md
```
：说明公开Skill与内部内容的划分标准，以及该规范对用户体验的重要性，还包含审核模式和确保Skill纯方法论的编写清单。