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.
SkillScore95Maintained
Automatic
◆AI Engineer pack
Last verified 8/20/2026
What it changes
Passed 21 of 22 test cases with the skill, and 12 of 22 without it.
Without skill55%
With skill95%
Checks it passed that the model alone missed
Includes a test plan in the deliverables
Uses the pattern references/[noun]-template.md
Specifies 4 parts for the description structure
and 9 more in the full report
9 fixed12 passed either way1 still failing0 broke
Pass-rate lift
+41 pp
Tokens
+121%
Agent turns
0%
Response time
-27%
Model gemini-3.6-flashMeasured 8/20/2026v121 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 9 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 9
Prompt
What standard file naming pattern should be followed for an audit checklist document located in the secondary materials directory?
What was checked, without and with the skill
Checked
Without skill
With skill
Uses the pattern references/[noun]-checklist.md
Missed
Passed
case-11 · gemini-3.6-flash · 8/20/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md253 lines4 files
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.