/skill-creation-walkthrough

name: skill-creation-walkthrough
description: Step-by-step guide for creating your own Claude Skills, from deciding whether a skill is the right tool to writing the SKILL.md file, structuring reference material, and making it trigger reliably. Use when you want to package a workflow, framework, or repeated task into a reusable Skill, when an existing skill is not triggering or not loading the right context, when you are auditing a skill that is underperforming, or when you want to publish a skill for others. Also triggers when someone asks "how do I make a skill" or "what makes a good skill". Useful for individuals, teams, and anyone publishing skills publicly.
category: process-and-team
catalog_summary: "The meta-skill: how to write your own custom skills"
display_order: 5

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.

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.

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).

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.

The framework: how skills work

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.

Workflow

Phase 1: Decide if a skill is the right shape

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.

Phase 2: Define the trigger

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.

Phase 3: Write the description

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:

1. **What it does** (one sentence, action-oriented). 2. **When to use it** (the trigger phrases or situations). 3. **Edge cases** with "Also triggers when..." (catches less obvious situations). 4. **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.

Phase 4: Structure the SKILL.md body

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]

## 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 follow