Claude Code Skills: When a Skill, When the CLAUDE.md

A Claude Code skill is a folder with one file in it: SKILL.md, a YAML header with two required fields, Markdown below. The format asks for nothing more. The decision that actually costs you something comes later: what belongs in a skill and what belongs in the CLAUDE.md, and which of four places the folder has to sit in so the session that needs it can find it.

Libraries fail on the second half of that question, not on the syntax. A skill under ~/.claude/skills applies to every project on this machine, but not to Cowork and cloud sessions (code.claude.com/docs/en/skills). Set up a routine that runs overnight without you, and you find that out on the day the routine first works without its skill.

What are Claude Code skills?

A skill is packaged procedural knowledge that the agent pulls in when it is needed.

Definition: An Agent Skill is a directory containing at minimum a SKILL.md file. That file carries metadata, at least name and description, plus instructions telling an agent how to perform a specific task. A skill can also bundle scripts, reference material, templates and other files (specification, agentskills.io).

The mechanism behind it is called progressive disclosure, and the specification puts sizes on its three stages:

1. Metadata, roughly 100 tokens. At startup the agent loads only name and description for each available skill, just enough to know when it might be relevant.
2. Instructions, recommended under 5,000 tokens. When a task matches the description, the agent reads the full SKILL.md into context.
3. Resources, on demand. Files in scripts/, references/ or assets/ load only when they are required.

That produces the property which separates skills from every other kind of instruction: you can keep thirty of them on hand and normally pay for thirty descriptions, not thirty manuals. The documentation states the same thing from the other side: unlike CLAUDE.md content, a skill's body loads only when it is used, so long reference material costs almost nothing until you need it (code.claude.com/docs/en/skills).

The format is not Anthropic's alone. It was built there, announced on 16 October 2025 and published as an open standard in December 2025 (claude.com/blog/skills). The client showcase on agentskills.io listed 46 products on 25 September 2026, among them Cursor, VS Code, GitHub Copilot, Gemini CLI, Codex and Goose. A skill you write today is not a one-way format.

How is a SKILL.md put together?

Two required fields in the header, then Markdown with no format restrictions at all. The whole minimal version fits in five lines:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Your instructions go here.

The specification puts hard limits on both required fields, and this is where most guides get vague:

Source: agentskills.io/specification, retrieved 25 September 2026.

Claude Code adds fields of its own that the specification does not carry, among them disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, paths and context. It also counts differently: description and when_to_use together are truncated at 1,536 characters in the skill listing (code.claude.com/docs/en/skills). Both numbers are correct, they simply measure different things. The 1,024 is the format's limit, the 1,536 is where one product cuts. Stay under the smaller one and you stay portable.

The description is not decoration, it is the trigger. It is the only part in context at startup, so it is the only basis on which anything decides whether your skill gets loaded. The specification therefore tells you to put concrete keywords in it, the ones an agent can use to recognise a matching task.

When does something belong in a skill and when in the CLAUDE.md?

Facts in the CLAUDE.md, procedures in a skill. The documentation frames the line as something you notice about your own behaviour: create a skill when you keep pasting the same instructions, the same checklist or the same multi-step procedure into chat, or when a section of your CLAUDE.md has grown into a procedure rather than a fact (code.claude.com/docs/en/skills).

The reason is the price, not the style. The CLAUDE.md loads in every session whether it is needed or not. A skill at rest costs you its description.

Our own files let you do the arithmetic. The rules file for this website runs 414 lines and consists of facts: which Next version is pinned, why the database sits in Frankfurt, which route has to stay static, what may never be claimed. None of it is a procedure, and any of those lines can be needed in any session. The skill that writes this article runs 1,390 lines and is almost entirely sequence: validate demand, read the SERP, rule out cannibalisation, draft, pass two blocking gates, publish. Putting those 1,390 lines in a rules file would mean paying for them on every day nobody writes an article.

Two sentences as a rule of thumb you can apply without seeing our files:

• In the CLAUDE.md, whatever anyone touching this project at all needs to know.
• In a skill, whatever someone touching this one task needs to do.

Where do skills live, and why is that an operating decision?

In four places, and the difference between them is not a matter of taste. The documentation lists them in a table headed "Choose where skills load":

Source: code.claude.com/docs/en/skills, retrieved 25 September 2026.

The bold qualifier in the first row is where a filing question turns into an operating question. As long as you are the one sitting at the terminal, ~/.claude/skills is the most convenient home for everything. The moment a run starts without you, in the cloud, out of a fresh checkout, that directory does not exist. The run sees only what is in the cloned repository.

That turns into a two-track rule, and it is how we run our own library.

What does a skill library look like in operation?

It is two tracks with different obligations, not one folder with a lot of subfolders.

Track one: skills only you invoke. They sit in ~/.claude/skills, apply to all your projects and need no versioning, because the only reader is sitting in the same session you edit them in.

Track two: skills something other than you reads. A scheduled routine, a colleague, a second machine. Those live in a repository of their own, marcokohns/claude-skills, which the routine clones as a second source on every run. Three things make that track hold, and all three are paid once:

1. The path is pinned in the prompt. The routine's prompt names skills/create-blog-article/SKILL.md from the cloned repository, so a skill of the same name under .claude/skills in the target project cannot shadow it. Without that line, load order decides which procedure runs, and nobody notices while the two look similar enough.
2. What is not pushed does not exist for the run. Our local folder is a symlink into that repository, so editing and committing are the same motion. Pushing is not, and it is the one place where a forgotten step quietly puts a whole run on an old version.
3. The history is the rationale. 14 commits since 9 September 2026, nine of them on a single skill. Each of those nine carries the reason a rule was added, usually a run that went wrong without it.

What did measuring our own library show?

That the field everything hangs on is the one nobody checks. We counted the three skills on 25 September 2026, and one result was uncomfortable.

One skill of three sits at 1,105 characters, over the 1,024 the specification sets. It was written by the same workshop that puts its articles through two blocking gates. Nobody spotted it for a simple reason: an over-long description throws no error. It is truncated silently, and what is lost sits at the end, which is where you put the fine distinctions. The skill still loads, the cases at the edge of its description just get recognised less often over time.

The second number is as clear. The specification recommends keeping a SKILL.md under 500 lines and moving reference material into separate files. Our largest skill runs 1,390 lines and 116 kilobytes, two and a half times the recommendation, and moves nothing out yet. That breaks nothing, it is a bill that comes due on every activation. The specification names the way out in the same paragraph: the agent loads the whole file on activation, so anything needed only sometimes belongs in references/.

Two checks you can run against your own library in a minute, both of which would have caught what we found here:

# descriptions over 1,024 characters
for f in skills/*/SKILL.md; do
  python3 - "$f" <<'PY'
import re, sys
t = open(sys.argv[1], encoding="utf8").read()
fm = re.match(r"---\n(.*?)\n---\n", t, re.S).group(1)
d = re.search(r"^description:[ ]*(.*)$", fm, re.M | re.S).group(1).strip()
print(sys.argv[1], len(d), "TOO LONG" if len(d) > 1024 else "ok")
PY
done

# SKILL.md files over 500 lines
wc -l skills/*/SKILL.md

The official reference library also ships a checker for this, skills-ref validate, which validates the YAML header against the naming rules (agentskills.io/specification).

Where does a skill fail in daily use?

In three places, and none of them is the syntax of the file.

The description is too general. "Helps with PDFs" is the specification's own example of a bad one, set against a version that lists the actions and names the trigger. Since the description is the only thing read at startup, it alone decides whether your skill ever gets its turn. That is also why the temptation to overload it is strong enough to push it past 1,024 characters.

Two skills with the same name in different places. As soon as one name exists personally, in the project and in a plugin, your intent is no longer what decides which one runs. In an order that executes without you, the path belongs written out.

The collection grows faster than its rationale. A skill whose rules nobody can explain any more gets kept at the next rebuild, just in case. That is why our reasons sit in the commit rather than in a file beside it. Anyone who wants to delete a rule first reads what it once prevented.

Which skill should be your first?

With a procedure you have pasted into chat for the third time this month.

1. Create ~/.claude/skills/<name>/SKILL.md, with name and description in the header and your steps below. The directory name has to match the name field.
2. Write the description for selection, not for execution. What the skill does and when it is due, in the words that actually appear in your own orders, under 1,024 characters.
3. Decide which track it is before the second skill. If a run without you will ever read it, it belongs in a repository and not in your home directory. Moving it later is possible, but you notice the need through a failed run.

Which tool suits the way you work in the first place we answered in Claude Code vs Cursor, and which language to write your instructions in is settled in Using Claude Code in German. A single order in four blocks you can build with the Prompt Generator before you compress it into a skill, and the Claude Code cost calculator puts a number on what all of this costs per month.

One skill is not yet a way of working. That takes rules which hold when nobody is looking, checks that stop a run instead of waving it through, and tasks that finish while you are sitting on something else. That is what we teach, in German, in Das Claude Code System, four weeks with weekly live sessions. To see a session first, join a free live webinar. Every course is listed under Courses, and the people behind them are on About.