How Claude Code SKILL.md triggers work: format, templates, and how Anthropic’s skills behave

Anthropic's docs are clear: a SKILL.md should be under 500 lines. Their own docx skill is 590. I read all 17 of Anthropic's official skills, frontmatter by frontmatter, while building my own marketplace alongside. Every time, the same gap: the docs say one thing, the corpus does another. And the corpus is the one that's right. Here's what actually comes out when you read the code instead of the docs. The description is 90% of the skill A skill is useless if it doesn't trigger at the right moment. And what decides triggering isn't the body of the SKILL.md, it's its description in the frontmatter. Claude reads the list of available skills (just name + description) and picks. So all of the "when to use it" must live in the description, not the body. The counter-intuitive part, which Anthropic repeats in its own skill-creator: Claude under-triggers skills far more than it over-triggers them. It only consults a skill for a task it can't handle trivially. "Read this PDF" will never fire the PDF skill, even with a perfect description. Hence an explicit instruction: write descriptions that are a little pushy. You see it in the code: the xlsx skill says "Use this skill any time a spreadsheet file is the primary input or output", pptx says "any time a .pptx is involved in any way". No shyness. You push triggering, you don't hold it back. The 500-line rule nobody follows "Keep the SKILL.md under 500 lines" is one of the most quoted rules. In practice, docx is 590 lines, and the docs themselves add "feel free to go longer if needed". The others range from 32 to 404. The truth: 500 is a target, not a law. The real principle behind it isn't length, it's the context budget. The SKILL.md body loads on every trigger. If it's big because it holds the essentials, fine, go over. If it's big because it drags along detail that could live elsewhere, that's the fault. Size alone isn't the sin. Progressive disclosure: mostly scripts, rarely references The central skill pattern is staged loading: metadata (name + description) always in context, the body loaded on trigger, and resources (scripts/, references/) only on demand. A script can even execute without being loaded into context. Except that in the corpus, 11 skills out of 17 are a single SKILL.md, with no subfolder at all. Splitting isn't the norm, it's the exception you reach for when the domain warrants it. And when you do split, it's mostly scripts/: pdf, docx, xlsx, pptx are first and foremost script boxes for deterministic operations. The references/ (docs loaded on demand) appear on only two skills. The lesson: pull the deterministic stuff into executable code long before you pull prose into a side file. The "NOT for" Anthropic never writes Writing my own skills, I systematically added a "NOT for X" clause to the description, to avoid false triggers. Reading the official ones, surprise: they almost never do it. Their descriptions list inclusions ("this includes…"), not exclusions. The reason fits in one word: their domains don't overlap. The PDF skill and the Excel skill can't be confused, so no exclusion is needed, and they'd rather maximize triggering. My case is different: my skills touch each other (reviewing a diff, shipping a feature, wrapping up a branch are adjacent). The "NOT for" lets me disambiguate between my own skills. So it isn't a universal rule, it's a response to overlap. If your skills don't compete, don't add it: you'd only reduce your triggering, the worst flaw of all. How they actually optimize a description The most instructive part of the official skill-creator is that they don't guess a good description, they measure it. The protocol, unrolled: 20 eval queries: 8-10 that should trigger, 8-10 that shouldn't. Realistic and messy, the way a real user would type (file paths, personal context, typos, lowercase). The negatives are near-misses, not obvious ones. "Write a fibonacci function" as a negative for a PDF skill tests nothing. Good negatives share keywords with the skill but need something else. Each query run 3 times for a reliable trigger rate, then an improvement loop over 5 iterations. You pick the description by its score on a held-out test set (60% train, 40% test), so you don't overfit the queries you already know. It's an eval pipeline, not a finger in the air. Most people write a description by feel and move on. Anthropic treats it as the product. At a glance: the assumption vs the practice The gap, row by row, across the 17 official skills: The common assumption What the official corpus does A SKILL.md is under 500 lines docx is 590, and the docs add "go longer if needed" The description just says when to use the skill It must be pushy: the real risk is under-triggering You split into references/ and scripts/ (progressive disclosure) 11 of 17 skills are a single file; when you split, mostly scripts/ You restrict the description ("NOT for") to avoid false triggers Almost never written: distinct domains, they maximize triggering A good description is written by feel It's measured: 20 queries, each run 3 times, a 5-iteration loop, scored on a held-out test set What to remember The real lesson isn't in the list of rules, it's in the gap. The docs give clean heuristics; the corpus shows how competent people bend them when the ground demands it. Reading the 17 skills teaches more than reading the doc page, because you see the real trade-offs: going past 500 lines when the content deserves it, skipping the split two-thirds of the time, pushing triggering rather than restricting it. If you keep one thing: the risk isn't that your skill triggers too much, it's that it doesn't trigger at all. Write the description to be found. 🧩 My skills, installable I built a marketplace of Claude Code skills from my real workflow, applying these patterns. Browse and install them on the Skills page, including a skill-builder skill that condenses these principles. To frame an agent, see also the CLAUDE.md contexts. Frequently asked questions How many lines should a SKILL.md be? Aim for under 500, but it's not a law: the official docx skill is 590. What matters is that the body doesn't drag detail that should live in a script or a reference file. Go over if the essential content warrants it, then add pointers to side files. Why doesn't my skill trigger? Almost always the description. Claude under-triggers by default and only consults a skill for a non-trivial task. Make the description more inclusive and "pushy" ("use this skill whenever… even if the user doesn't say…"), with real trigger phrases. And test: a one-step task will never trigger a skill, and that's normal. Do I need references/ and scripts/ folders? Not by default: 11 of the 17 official skills are a single SKILL.md. You split when the domain is heavy, and then mostly into scripts/ for deterministic work (file manipulation, validation). references/ only earns its place for large multi-variant domains. Skill, CLAUDE.md or hook? Skill = a capability triggered by its description when the situation calls for it. CLAUDE.md = context always loaded for a specific project. Hook = deterministic automation on an event, enforced by the harness, not the model. If it's "always do X", it's a hook or a CLAUDE.md, not a skill.

Claude Code skills answer a specific pain: you keep pasting the same checklist into chat, or a section of your CLAUDE.md has quietly grown from facts about the project into a multi-step procedure. The official guidance is exactly that — when instructions become a procedure you re-explain, move them into a skill. Unlike CLAUDE.md content, a skill's body loads only when it's used, so a long runbook costs you almost nothing until the moment you need it. This post covers the SKILL.md format end to end: the frontmatter fields, how triggering actually works, arguments, supporting files, and a template you can copy. The mental model: two-stage loading Everything about writing a good skill follows from one design fact: The description is always visible. Claude sees your skill's name and description in every session, and uses them to decide when the skill is relevant. The body loads only on use. The instructions below the frontmatter enter context only when the skill fires (or when you invoke it with /skill-name). So the description is not documentation — it's the trigger. The body is not a summary — it's the procedure. Most broken skills I've seen get these backwards: a vague description ("Helps with releases") that never matches anything, and a body that's a one-liner. A minimal working skill A skill is a directory with a SKILL.md file. In a project: .claude/skills/release-notes/SKILL.md (Personal skills live under ~/.claude/skills/ and follow you across projects.) --- name: release-notes description: "Draft release notes from merged PRs. Use when the user" asks for release notes, a changelog entry, or "what shipped". --- Collect merged PRs since the last git tag, then write release notes. 1. Run `git describe --tags --abbrev=0` to find the last tag. 2. List merges since then: `git log <tag>..HEAD --merges --oneline`. 3. Group changes into Added / Fixed / Changed. 4. Write entries as user-facing outcomes, not commit messages. 5. Show the draft before writing to CHANGELOG.md. That's a complete, working skill. Type /release-notes to run it directly, or just ask "can you draft release notes?" and let the description do its job. If you've used custom commands before: commands and skills are now the same thing. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Skills just add optional extras — a directory for supporting files and frontmatter to control invocation. Frontmatter: four fields you'll actually use All fields are optional. Only description is recommended — without it, Claude has nothing to match against, and the skill is effectively manual-only. --- name: my-skill description: What this skill does disable-model-invocation: true allowed-tools: Read Grep --- name — the command name (/my-skill). Defaults to the directory name, so most skills omit it. description — the trigger. Write it for the matcher, not for humans browsing. Include the literal phrases people say: "Use when the user asks to X, Y, or mentions Z." disable-model-invocation: true — Claude can never fire this on its own; only you can, via /name. Use it for anything with side effects you want a human to initiate: deploys, commits, publishing, sending messages. This is the difference between a reference skill (let Claude pull it in when relevant) and a task skill (you pull the trigger). allowed-tools — pre-approve the tools the skill needs (e.g. Read Grep), so a read-only helper doesn't stop to ask permission mid-run. That last pairing is worth internalizing: knowledge skills → model-invoked; action skills → slash-only. The frontmatter is where you encode that decision, and it's the single biggest safety lever in the format. Arguments Skills take arguments when invoked as commands, with real substitution syntax: $ARGUMENTS — everything you passed. (If it doesn't appear in the body, arguments are appended as ARGUMENTS: <value> instead.) $0, $1 — positional access, shorthand for $ARGUMENTS[0], $ARGUMENTS[1]. Named arguments — declare arguments: [issue, branch] in frontmatter and $issue / $branch expand by position. Self-documenting, so I'd default to this for anything with two or more parameters. So /fix-issue 1423 hotfix/login with arguments: [issue, branch] gives you a body that reads like prose: "Fix issue $issue on branch $branch." Supporting files: the 500-line rule Official guidance: keep SKILL.md under 500 lines and move detailed reference material into separate files in the skill directory: my-skill/ ├── SKILL.md (required — overview and navigation) ├── reference.md (detailed API docs — loaded when needed) ├── examples.md (usage examples — loaded when needed) └── scripts/ └── helper.py (executed, not loaded) The important part is the navigation: link each file from SKILL.md with a note about what it contains and when to read it — ## Additional resources - For complete API details, see [reference.md](reference.md) - For usage examples, see [examples.md](examples.md) This is the same two-stage trick again, one level down. SKILL.md stays a lean table of contents; the 2,000-line API reference costs nothing until Claude actually follows the link. Scripts are even cheaper — they get executed, not read into context. When a skill won't trigger (or triggers too much) Almost every triggering problem is a description problem: Never fires: the description describes the domain ("Release management helpers") instead of the moment ("Use when the user asks for release notes, a changelog, or what shipped"). Rewrite it around the phrases users actually say. Front-load them — long descriptions get truncated in listings. Fires too often: the description is too broad ("Use for anything git-related"). Narrow the trigger, or if it's a task skill that should never auto-fire anyway, set disable-model-invocation: true and stop fighting the matcher. You can't tell if it loaded: invoke it explicitly with /skill-name once. If it works manually but never automatically, it's the description. It's almost always the description. One more option worth knowing: skills can run in their own subagent context (context: fork), which keeps a noisy multi-step procedure from flooding your main session. Useful for research-style skills that read a lot but should report back a summary. Portability note SKILL.md follows the Agent Skills open standard, and the same format is now read by several coding agents (Claude Code extends it with invocation control, subagent execution, and dynamic context injection). Writing your team runbooks in this format is a reasonably safe bet even if your tool mix changes later. I maintain Rulestack, a set of focused rule and skill packs for Claude Code, Cursor, and Codex — including a full Claude Code skill-authoring pack. Daily AI-coding-agent tips on Bluesky: follow @ai-shop.bsky.social.