How Long Should a Skill.md File Be?

Why Skill.md Length Is a Problem Worth Solving

You've probably seen the flood: thousands of community SKILL.md files on GitHub, each promising to make your agent smarter. The temptation is to install them all.

The hidden cost is brutal. Every skill's metadata — name and description — sits in the context window at all times, costing roughly 100 tokens per skill before it ever fires. Once a skill triggers, its full body loads and competes with your conversation history, system prompt, and every other active skill. Anthropic puts it plainly: the context window is a shared resource, and every token competes for it.

Bloat isn't the only failure mode. A 238-skill analysis from UC Irvine found that over 99% of real-world SKILL.md files contain at least one "skill smell" — a structural flaw that hurts reliability. The most common culprit? Vague descriptions that fail to trigger the skill when it should, or fire when it shouldn't.

Philipp Schmid, Staff Engineer for Developer Experience at Google DeepMind, calls the description field "the trigger mechanism" — it's what Claude matches incoming requests against. Practitioners report roughly 50% improvement in trigger accuracy from tuning that one field alone.

The core tension looks like this:

• Bloat costs tokens — a verbose PDF-extraction instruction runs ~150 tokens; a tight version runs ~50, a 3× difference for the same behavior.
• Vague skills fail to trigger — and once a skill smell appears, research suggests it rarely disappears as the skill evolves.
• The format is spreading — Claude Code, OpenAI Codex, GitHub Copilot, and LangChain all now support skills, so length decisions made today propagate across runtimes.

This is exactly why length deserves deliberate thought. A lean SKILL.md that triggers reliably and offloads detail to reference files outperforms a monolithic blob — both in token cost and in whether the agent actually uses it.

For anyone shipping skills at scale, the natural next question is empirical: does this skill actually lift performance, or does it just add noise? That's the kind of testing SkillzBench is building — a free directory that benchmarks every skill with and without the same model and publishes the lift, so you can see which skills earn their tokens before you install them.

The Official Numbers: Lean Body, Hard Ceilings

If you want the short answer from Anthropic itself: keep the SKILL.md body lean — under 500 lines, roughly 1,500–2,000 words, and never more than 5k tokens. Those are the three official numbers, pulled straight from Anthropic's own documentation, and they exist for one reason: every token in the body competes for the same shared context window that holds your conversation history, system prompt, and the metadata of every other installed skill.

Here is what the official sources actually say:

• The best-practices guide says to keep the SKILL.md body under 500 lines and split content into separate files as you approach the limit.
• Anthropic's own skill-development guidance targets 1,500–2,000 words for the body, moving detailed material into a references folder.
• The architectural overview sets a hard ceiling of under 5k tokens for the body, which loads only when the skill triggers.

Notice the inconsistency: lines in one document, words in another, tokens in a third. They are broadly compatible — all three describe a lean body — but Anthropic has never published a single canonical number, so treat the tightest constraint (5k tokens) as the true ceiling and the word count as your working target.

Independent analysis lands slightly looser. A technical deep dive into Claude Skills recommends keeping SKILL.md prompt content under 5,000 words, or about 800 lines — nearly double Anthropic's 500-line guidance. Community practitioners lean the other way: as one Hacker News commenter put it, "most useful skills are tiny. A markdown file, maybe one script."

Then there is the irony that keeps skill authors humble. The file where Anthropic teaches you to write lean skills — the skill-development SKILL.md itself — runs 637 lines and 22.3 KB, exceeding its own recommended body size. Even the authors of the standard struggle to stay under the line they drew, which tells you two things: the limits are guidance, not law, and staying lean takes deliberate editing, not good intentions.

Length matters, but it is only half the story. Over 99% of real-world SKILL.md files contain at least one "skill smell," and most trace back to vague descriptions rather than oversized bodies. That is why verification beats guesswork: SkillzBench is building exactly this — free sandbox benchmarks that test every skill with the same model, with and without the skill, publishing the Lift in percentage points so you can see whether a file's length actually helps. The waitlist is live now.

ctaText: Skills, proven. Join the free SkillzBench waitlist and be first to see real benchmark Lift for the skills you rely on.

socialProofText: Built on independent research — a 238-skill academic study found over 99% of published SKILL.md files carry at least one flaw. SkillzBench tests so you don't have to trust blindly.

Progressive Disclosure: How to Be Comprehensive Without Being Long

The secret to a comprehensive skill that doesn't bloat your context window isn't writing less — it's writing in layers. Anthropic calls this progressive disclosure, and it's the principle that resolves the entire length debate.

Skills load in three stages, according to Anthropic's architecture documentation: metadata (name plus description, roughly 100 tokens, always in context), the SKILL.md body (loaded only when triggered, capped under 5k tokens), and bundled resources (zero tokens until accessed). That third level is the game-changer. As the docs put it, there's no context penalty for bundled content that isn't used — a skill can ship dozens of reference files at zero cost.

This means SKILL.md should function "like a table of contents in an onboarding guide," per Anthropic's best-practices guide, pointing to detailed files the agent loads on demand. Claude Code's documentation confirms the same: long reference material costs almost nothing until it's needed. The offloaded content follows structural rules:

• Keep references one level deep from SKILL.md — nesting causes partial reads and incomplete information.
• Reference files longer than 100 lines should include their own table of contents.
• For files exceeding 10k words, include grep search patterns in SKILL.md so the agent can find what it needs.
• Never duplicate — information should live in either SKILL.md or the references, not both.

Scripts offer an even sharper efficiency gain. When Claude runs a bundled script, the script's code never enters the context window — only its output consumes tokens, per the overview documentation. A 300-line Python file costs nothing; a 300-line instruction block costs everything, every single turn.

The description field deserves disproportionate attention, too. Philipp Schmid of Google DeepMind calls it "the trigger mechanism" — the text Claude matches against user requests. Practitioners report roughly a 50% improvement in trigger accuracy from tuning the description alone, and a 238-skill study found over 99% of real-world SKILL.md files contain at least one "skill smell," most traceable to vague descriptions. A brilliant body with a weak description never loads at all.

Of course, structure only works if the skill genuinely helps. SkillzBench is building exactly that verification layer: sandbox benchmarking of every skill with and without the skill, so you can see whether the lift justifies any length at all — all free, at skillzbench.com.

Testing and Validating Your Skill's Length in Practice

Length guidance only matters if you can prove it improves the agent's output. Right-sizing a SKILL.md is a four-step loop: draft lean, offload detail, tune the description, then test against every model you plan to use.

Start by drafting the body to roughly 1,500–2,000 words, the target Anthropic's own authoring guidance recommends, keeping detailed material in a references folder that costs zero tokens until the agent actually opens it. Move anything bulky out of the body, since a bundled script's code never enters the context window — only its output does, according to Anthropic's skills overview. Then invest disproportionately in the description field: it is the trigger mechanism, and practitioners report roughly 50% better trigger accuracy from description tuning alone, per an analysis of real-world SKILL.md files.

A practical checklist for the pass:

• Draft lean: aim for a body that reads like a table of contents, not a manual.
• Offload detail: one level deep, with a table of contents for files over 100 lines.
• Tune the description: it carries the trigger, so vague wording costs you activations.
• Test per model: Anthropic's best-practices guide notes Haiku may need more guidance while Opus needs less.
• Benchmark with and without the skill before you trust it.

That last step is where most guidance stops and the real question begins. Over 99% of real-world SKILL.md files contain at least one "skill smell," and community practitioners openly ask where the evidence is that skills improve performance at all, as seen in practitioner discussion. With no empirical length-to-performance data published anywhere, the only way to know a leaner file actually helps is to run the same task with and without it.

That is the verification approach SkillzBench is building: sandboxed testing that publishes Lift in percentage points, paired with security scans and trust scores, because with roughly 26% of published skills carrying a vulnerability, length advice without validation is just guesswork.

The Bottom Line: Small Files, Big Verification

If you take one lesson from this entire article, make it this: the practitioners who use skills daily agree that bigger is not better. As one Hacker News commenter put it, "most useful skills are tiny. A markdown file, maybe one script" — and that's not a corner-cutting hack, it's the design philosophy working as intended.

Andrej Karpathy frames the bigger picture: we should stop writing HTML docs for humans and start writing markdown docs for agents — treating skill-writing as writing curricula for agents. A curriculum doesn't dump the entire textbook into a lecture; it points students to the right chapter at the right time. SKILL.md works the same way.

So here's the rule of thumb one last time:

• Keep the SKILL.md body to roughly 1,500–2,000 words, under 500 lines, and never above 5k tokens.
• Offload detail to reference files — one level deep, with a table of contents for anything over 100 lines.
• Invest your energy in the description field, since practitioners report roughly a 50% improvement in trigger accuracy from tuning it alone.
• Prefer bundled scripts over inline instructions, because a script's code never enters the context window — only its output does.

But a lean file is only half the story. The other half is verification, and that's where the ecosystem gets uncomfortable. Tens of thousands of community skills already sit on GitHub, and a 238-skill study found that over 99% of real-world SKILL.md files contain at least one "skill smell." Length discipline means nothing if the skill itself doesn't help — or worse, carries a vulnerability.

This is exactly the gap SkillzBench is building to close. The free directory will let you browse and test community skills on SkillzBench, where every skill is version-pinned to a commit SHA, security-scanned, and benchmarked in a sandbox with the same model — with and without the skill — so you can see the Lift in percentage points before trusting it with your agent. Everything will be free: the directory, the benchmarks, and the MCP connector that equips your agent with only the skills you choose.

Write small. Then verify what you've written actually lifts performance. Those two habits together turn SKILL.md from a guess into an engineering practice.