Build
July 21, 2026 · 5 min read
I spent an afternoon measuring a Claude Code skill folder, because I wanted a number instead of a theory. The .claude/skills/ directory holds 15 skills that run every day. Their SKILL.md files add up to 49,214 characters, but only 9,321 of those sit in the context window when a session opens. That's 18.9%. The other 81% loads on demand.
This is for anyone who keeps pasting the same wall of instructions into Claude Code. By the end you'll know what a working skill file looks like, how long it should be, and which line does the real work.
One honest catch: I measured characters, not tokens. No API key on this machine for Anthropic's count_tokens, and OpenAI's tokenizer gives the wrong answer for Claude. Characters are the honest unit.
I wanted to know what the folder version actually costs to keep around. People make the swap to stop re-explaining themselves: a long prompt does its job once, then the session's over and the knowledge goes with it, so every new session starts with the same rules about tone, structure and quality bars, and every session drops a slightly different piece of them. Claude Code is a terminal agent that reads and edits files in your project, and that file access is what makes the folder version possible.
A skill is a directory with one SKILL.md file in it, and that's the entire format.
The difference is when the text enters the context window. A prompt is in context the moment you paste it, and it stays there for the rest of the session whether it's relevant or not. A skill splits into two pieces: a short description in the YAML frontmatter, and the body underneath it. Anthropic's official skills documentation puts it plainly: skill descriptions are loaded into context so Claude knows what is available, but full skill content only loads when invoked.
So the description is a permanent tenant and the body is a guest. That's the trade, and it's why these 15 skills cost 9,321 characters of standing context instead of 49,214.
The plan was to stop theorising and count. Three questions: how long is a SKILL.md that works, what the descriptions have in common, and how much one skill pulls in when it fires. Every number below came from a script over those 15 files.
Shorter than I expected. The median file is 40 lines and 439 words. The shortest is 222 words, the longest is 701. None is the sprawling document I assumed a "real" skill would be.
That surprised me, because my instinct with a long prompt is always to add more. In a skill folder the incentive flips. Anything that doesn't need to be in SKILL.md goes into a separate file in the same directory, and Claude reads it only when the task calls for it. The body stays a procedure, not an encyclopedia.
One line decides whether a skill ever fires, and it's the description. Claude reads every installed skill's description to work out which matches your request, so a vague one means a skill that quietly never activates.
There's a hard number attached to this. The docs state that the combined description and when_to_use text is truncated at 1,536 characters in the skill listing, specifically to reduce context usage. So the description has a budget. The longest one here is 794 characters, which is 52% of the cap. The median is 596. Headroom, but not unlimited: anything past 1,536 characters is text Claude never sees.
The shape is consistent. Across the 15 files, 14 descriptions contain literal quoted trigger phrases, 100 of them in total, and 12 use an explicit "use when" list. They're not written like documentation. They read like a list of things a user might actually type.
description: [What the skill does, in one clause]. [How it does it: which files it loads, which steps it runs]. Use when: "first thing a user would type", "second phrasing", "third phrasing". Also fires automatically whenever [the situation that should trigger it], even without the word [obvious keyword].
That last clause is the one that earns its keep. Naming the situation, not just the keyword, is what keeps a skill from sitting idle while you type around it in different words.
The failure mode is a skill that exists and never runs, and these 15 files show what causes it. Not one description reads like a table of contents entry. "Writes an article." "Checks SEO." Accurate and useless, because nothing a person actually types sounds like a summary of a feature.
The second thing the files gave away: nobody treats a skill as finished. In this repo 14 commits touch .claude/skills/, and the pattern in them is corrections landing as diffs. One skill grew from a five step process to a six step process after a run produced something thin. With a long prompt that fix lives in someone's head until they forget it. Here it's a two line change in a file that every future run reads. That's another hour saved, every time.
A lot more than its description, which is the whole point. The largest skill in the set pulls in 22,327 characters across six files when it activates: its own SKILL.md plus a style guide, an author profile, a template and two reference files. Its description is 794 characters.
That's a factor of 28: twenty eight times the material at zero standing cost until the moment it's relevant. As a single pasted prompt those 22,327 characters would sit in context for the whole session, including the parts that have nothing to do with what I'm doing.
Fifteen skills, 49,214 characters of instructions, 9,321 characters of standing cost. The library keeps growing and the baseline barely moves, because each new skill only adds its description. What isn't solved: nothing tells you a skill failed to trigger. You just get a mediocre answer and have to notice it yourself, which is a stranger kind of debugging than anything in building a landing page in a day or comparing two builders side by side.
Yes, and I'd start with the description instead of the body. I spent most of the afternoon reading procedures inside SKILL.md files that were already good enough, and every interesting number was attached to the one line that decides whether any of that gets read. Next time: trigger phrases first, steps second.
The other thing I'd change: convert fewer prompts. A prompt you use once a month is fine as a prompt. The ones worth a folder are the ones you've pasted more than three times, because those are the ones where a correction needs somewhere permanent to live. Fair enough if that's only two or three of yours. Good enough ships.
Time: an afternoon of reading and counting
Cost: $0 beyond normal Claude Code usage
Tools: Claude Code, one Python script
Difficulty: 2 out of 5
.claude/skills/your-name/SKILL.md.description that quotes three phrasings you would actually type, and keep the whole thing under 1,536 characters.Claude Code vs v0 vs Lovable: I gave three AI tools the same app brief. One I built and measured, two I judged on documented behavior. Here's the winner.
I built the same website three ways with AI in one afternoon. Here's the real decision tree for picking a coding agent, UI generator, or no-code builder.
AI vs human web development: I hand-built a one-page site, measured a real client tweak, and set it against what AI builders are documented to do.