Skill · Skill creation walkthrough
Skill creation walkthrough.
The description is everything for triggering.
A walkthrough for designing, writing, and maintaining your own Claude Skills. It covers when a skill is the right shape for the problem, how to write a description that actually triggers, how to structure the SKILL.md body and references, and how to test and iterate until the triggers fire correctly.
Skills run on progressive disclosure: the description lives in the system prompt and the body loads only when triggered. Get the description right or the skill never loads, however good the body is.
Audience: anyone packaging a repeated workflow into a reusable skill, fixing a skill that will not trigger, or auditing one that underperforms.
The framework
Six phases from idea to a tested skill.
The walkthrough runs in order. The first phase decides whether to build a skill at all; the last accepts that skills never work the first time.
- 01Decide if a skill is the right shape: build one when you repeat the workflow 5-plus times, the output benefits from structure, and there is a clear trigger. Otherwise use a saved prompt or a system instruction.
- 02Define the trigger: write down the exact phrases and situations that should load it. If you cannot articulate the trigger crisply, the skill will not load reliably.
- 03Write the description: the most important sentence or two in the skill, and the only part Claude sees when deciding whether to load it.
- 04Structure the SKILL.md body: the standard sections (when to use, when not to use, required inputs, the framework, the workflow, failure patterns, output format), adapted as needed.
- 05Add references: the second tier of progressive disclosure, for long checklists, templates, and anything over 100 lines that not every invocation needs.
- 06Test and iterate: trigger test, edge-case test, false-positive test, output test, and length test, then fix and repeat until the triggers fire correctly.
Description anatomy
Four parts of a description that triggers.
The description is what Claude reads in the system prompt to decide whether to load the skill. A one-sentence description is usually not specific enough.
01
What it does
One action-oriented sentence, leading with the verb. 'Audit on-page SEO,' not 'help with SEO things.'
02
When to use it
The primary triggers, in phrases users would actually say ('asks for a page audit', 'why is this page not ranking').
03
Also triggers when...
The secondary triggers and edge cases the primary phrases miss (mentions of Core Web Vitals, internal linking, schema).
04
Useful for...
The audience or scope, to help disambiguate from neighboring skills ('individual page reviews and small-batch audits').
What makes a skill work
Progressive disclosure, and methodology over implementation.
A skill is a folder with a SKILL.md file: YAML frontmatter (name and description) plus a body of instructions, and optionally reference files. The key property is progressive disclosure. Claude does not read every skill on every turn; the description lives in the system prompt, and the body and references load only when the skill triggers. That is what lets a user keep hundreds of skills without polluting context, and it is why the description carries the entire weight of triggering.
A skill that is too narrow never fires because it requires exact phrases the user does not say; one that is too broad fires constantly for unrelated tasks. The fix is concrete trigger phrases plus an explicit 'when not to use' that cross-references sibling skills, so overlapping skills do not load ambiguously.
A public skill teaches methodology: frameworks, decision criteria, taxonomies, and anti-patterns. Implementation specifics (page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. A skill written around a single use case fails at adjacent ones, and one that hardcodes your stack fails for everyone else, so generalize before publishing.
Reference files
Three references that go alongside the SKILL.md.
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 and what stays internal, the audit pattern, and the authoring checklist for keeping skills methodology-pure.
Open source under MIT
Read the SKILL.md on GitHub.
The skill source lives in the rampstackco/claude-skills repository alongside dozens of other skills covering the full lifecycle of brand and product work. This page is a structured overview; the SKILL.md is the source. MIT licensed.
Frequently asked questions.
- When should something be a skill versus a prompt?
- Build a skill when you repeat the same workflow five or more times, the output benefits from a consistent structure, the task has a clear trigger (a question shape, a file type, a domain), the instructions exceed about 200 words, templates or reference material would help, and others might benefit from the same workflow. Use a saved prompt or a one-line system instruction instead when you used it once, each output is bespoke, the task is already part of every conversation, or a single sentence would do.
- What is progressive disclosure?
- Claude does not read every skill on every turn. The skill's description lives in the system prompt, and the SKILL.md body and its references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context, and it has direct consequences for authoring: the description is everything for triggering, the body holds the workflow, and references hold the content (long checklists, templates, deep material) that does not need to be in every invocation.
- What makes a good skill description?
- Four parts. What it does (one action-oriented sentence that leads with the verb), when to use it (the primary triggers, in phrases users would actually say), 'also triggers when...' (the secondary triggers and edge cases), and 'useful for...' (the audience or scope, which helps disambiguate from neighboring skills). 'Helps with SEO' fails because it is vague and has no trigger phrases. If your description is a single sentence, it is probably not specific enough to fire reliably.
- How do I test a skill?
- Run five tests. A trigger test (write the trigger phrase in a fresh conversation and confirm the skill loads), an edge-case test (write something that should fire via the 'also triggers' clause), a false-positive test (write something close but irrelevant and confirm the skill does not load), an output test (run it on a real task and check the result), and a length test (SKILL.md under 250 lines, references under 400). Skills do not work the first time, so plan to iterate: broaden the description if it never fires, narrow it if it fires constantly.
- What belongs in a public skill versus an internal one?
- A public skill teaches methodology: the frameworks, decision criteria, taxonomies, and anti-patterns that transfer across users and stacks. Implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. A public skill that hardcodes your stack or is written around your single use case fails for everyone else, so generalize before publishing and keep the stack-specific detail in internal material.