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:
- 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.
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 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]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.
Phase 5: Add references for what does not belong in 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.mdfor templates.references/[noun]-checklist.mdfor checklists.references/[noun]-playbook.mdfor end-to-end runbooks.references/example-[scenario].mdfor worked examples.
Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each.
Phase 6: Test and iterate
Skills do not work the first time. Plan to iterate.
Testing checklist:
- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong.
- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire?
- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad.
- [ ] Output test: run the skill on a real task. Is the output what you expected?
- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim.
After testing, common fixes:
- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..."
- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience.
- Output is generic → add a clearer framework or workflow with more specifics.
- Reference is overwhelming → split into multiple references, keep each focused.
Deep dive: description anatomy
The description is hard to get right. Here is the formula in detail.
Sentence 1: What it does
Lead with the verb. Be specific.
- Good: "Audit on-page SEO."
- Bad: "Help with SEO things."
Sentence 2: When to use it
State the primary triggers. Use