Learning path map
Detailed content
🧬 Anatomy of a Skill
What a SKILL.md, the frontmatter name/description, the instruction body, and how Claude discovers and triggers the skill on its own.
A Markdown file with YAML frontmatter that teaches Claude to perform a specific task on demand.
It's the smallest unit of everything. Whoever understands the file understands the whole system.
Text, not code. Versionable, readable, portable between machines.
The skill’s unique identifier, in kebab-case, which Claude uses internally.
An ambiguous name = a skill nobody can find. It’s the first field that matters.
Short, descriptive, stable. Changing the name breaks references.
The sentence that tells Claude what the skill does AND when to use it. It’s what Claude reads to decide whether to trigger it.
90% of a skill's success lives here. A weak description = a dead skill.
Does + When. Action verbs, concrete triggers.
Everything below the frontmatter: the step-by-step instructions, rules, examples, and expected output format.
It’s where execution quality is determined. Vague instructions produce vague results.
Workflow, hard rules, output format, principles.
At the start, Claude only sees the name + description of each skill — never the full contents of all of them.
Understanding this explains why the description is everything and why too many skills cause confusion.
Lightweight index, semantic matching, on-demand loading.
When the request matches a description, Claude loads that SKILL.md and starts following its instructions.
It's the difference between a skill that activates on its own and one you have to invoke manually.
Automatic trigger, explicit invocation, conversation context.
📂 Progressive disclosure & structure
The folders references/, scripts/ e assets/, lazy loading, and the golden rule: keep the SKILL.md lean.
A strategy of showing only the essentials first and revealing details only when needed.
It’s the principle that keeps context light and the skill quick and inexpensive to load.
Layers, on demand, context savings.
Supporting files (templates, design systems, tables) that the SKILL.md says to read when needed.
It’s where the detail lives that would make SKILL.md huge if it were inline.
Supporting documents, conditional reading, modularity.
Scripts (Python, shell, etc.) that the skill runs instead of asking Claude to rewrite logic every time.
Deterministic code is more reliable and cheaper than regenerating the logic on every call.
Determinism, reuse, separating logic from prose.
Static files — fonts, images, HTML templates, examples — that the output uses or references.
Keep the skill self-contained: everything it needs travels with it.
Self-contained, versioned resources, output examples.
SKILL.md should contain the workflow and decisions; the supporting files hold the heavy details.
An bloated SKILL.md costs context every time it runs, even when the details aren't used.
A router, not an encyclopedia. It points; it doesn't dump.
The pattern of instructing Claude to open a supporting file only under specific conditions.
It’s what turns a set of files into a self-navigating skill.
Reading conditions, routing table, task-based trigger.
🎯 Descriptions that trigger
The anatomy of a description that activates at the right time: triggers, examples, anti-patterns and—just as important— when NOT to trigger.
Every good description has two parts: what the skill produces and when it should be used.
Descriptions that only say "what they do" don't give Claude the signal for when to trigger.
Capability + condition, action + context.
Real words and requests ("create an itinerary", "/travel") that signal the skill applies.
Concrete triggers dramatically increase the correct activation rate.
User language, synonyms, slash commands.
Include short use cases in the description itself to anchor the matching.
Examples give Claude semantic anchors that abstract descriptions don’t.
Use cases, anchors, "use when...".
Vague, overly generic, or purely technical descriptions that don't say when to use the skill.
Recognizing the anti-pattern is the fastest way to fix a skill that doesn’t trigger.
Vague, redundant, no trigger, jargon without context.
Make clear in the description (and body) the cases when the skill should NOT be used.
False positives are just as disruptive as false negatives. Boundaries prevent both.
Negative scope, "don't use for...", disambiguation.
Run varied, real requests to see whether the skill activates when it should and stays quiet when it shouldn't.
A description is a hypothesis; only testing confirms it. It's a loop, not a one-time guess.
Test cases, false positives/negatives, iteration.
📐 2026 rules
The current rules from Anthropic’s skills best practices guide and Claude Code docs, adjustments for 5.5 models, a copyable checklist and the validator to audit your skills.
SKILL.md under 500 lines, references linked directly from it, and a summary at the top of any reference over 100 lines.
A nested reference is only previewed: rules at the end of the file disappear without warning.
500 lines, one level deep, table of contents.
How much control each step deserves: a text instruction, a model with room to vary, or an exact script.
A costly error calls for an exact script; an open-ended task needs only direction.
Risk, fragility, “what if the agent does something different?”
What the skill does and when to use it, in third person, with up to 1,024 characters; the description + when_to_use are cut off at 1,536 in the listing.
The model can’t see what’s cut off, and the skill won’t trigger.
Third person, “when to use,” size limits.
A checklist the agent copies into its response and checks off, with a way back, and a loop to run, fix, and repeat.
A long task without a checklist skips steps; output without a loop stops at the first error.
Checklist, pass-or-fail criterion, verifier.
Run the skill on the models that will use it and check whether it guides them enough without overexplaining.
Each model responds differently to the same instruction.
Does Haiku guide? Is Sonnet concise? Does Opus avoid excess?
An installation command for each package, hooks in the skill frontmatter, and critical rules at the top, because compaction keeps only the first 5,000 tokens.
That’s what makes the skill work on a colleague’s machine and in a long session.
Installation, hooks, compaction, 5.5 models.