Claude Code skills, explained: what loads, when it fires, and how to write one

Strip the branding and a skill is a directory with one required file. SKILL.md opens with YAML frontmatter carrying a name and a description, then continues as ordinary Markdown instructions. The folder can also hold scripts the instructions invoke, reference documents, and asset templates. That is the whole format, and it is deliberately boring: a skill is a procedure written down, packaged so an agent can find it.

---
name: brand-audit
description: Check UI code against the project design system. Use when reviewing components, screens, or PRs for hardcoded colors, off-scale spacing, or fonts that bypass the tokens in DESIGN.md.
---

# Brand audit

1. Read DESIGN.md at the repo root before judging anything.
2. Flag any literal hex value, arbitrary Tailwind color, or font-family
   that does not come from the token set.
3. Report violations as file:line with the token that should be used.

The same format now works beyond Claude Code: it grew into an open agent-skills convention that OpenAI's Codex and Cursor have adopted with their own discovery paths, which is why a skill you write once increasingly travels with you. We cover the Codex side in Codex skills.

Claude Code does not read your skills into every conversation. At session start it indexes only the frontmatter: each skill contributes its name and description to context, a couple of lines, nothing more. The full body, the scripts, the reference files load only when Claude decides the current task matches a description, or when you invoke the skill explicitly. Anthropic calls this progressive disclosure, and it is the design decision the whole feature hangs on.

Two practical consequences follow. First, installing fifty skills costs you almost nothing in context, so hoarding is cheap; a hundred descriptions weigh less than one loaded skill body. Second, and this is the part the roundup posts miss, a skill with a weak description is *installed but unreachable*. Claude cannot match a task to "Helps with frontend stuff." The complaints that fill Reddit threads, I installed twenty skills and nothing changed, are usually this: the bodies were fine, the descriptions never gave the model a reason to open them.

• ~/.claude/skills/<skill-name>/SKILL.md: personal skills, available in every project you open.
• .claude/skills/<skill-name>/SKILL.md: project skills, committed to the repo so every collaborator and every agent session gets them.
• Plugins: a plugin can bundle skills alongside commands and agents, which is how teams distribute a set in one install.

The repo location matters more than it looks. A personal skill fixes your sessions; a committed one fixes your teammate's sessions and your CI agent's sessions too. Anything that encodes a project contract, how we review UI, how we write migrations, how we apply the design system, belongs in .claude/skills/ next to the code it governs.

Claude Code gives you three places to put knowledge, and they answer different questions. CLAUDE.md is always loaded: it is for constraints that apply to every request, and every line in it is paid for on every prompt, so it should stay short. A skill loads on demand: it is for procedures that are only sometimes relevant, and it can be long because it costs nothing until it fires. A subagent is a separate context entirely: it is for work whose intermediate output would pollute your session.

The dividing line for the full file taxonomy, including AGENTS.md and DESIGN.md, is in CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

1. 1

   Start from a repeated correction

   The best skill candidates are the things you keep typing: the review checklist you paste, the deploy sequence you re-explain. If you have never corrected the agent about it twice, it does not need a skill yet.

2. 2

   Write the description first, as trigger conditions

   Before the instructions, write the sentence that decides when this loads: the verbs and situations a matching request would contain. If you cannot name the situations, the skill will not fire and you have discovered that early.

3. 3

   Make the body an executable procedure

   Numbered steps, exact commands, exact file paths. Reference files in the skill folder for anything long. An agent follows a procedure far more reliably than it channels a vibe.

4. 4

   Point at artifacts, not adjectives

   A skill that says "keep the UI consistent" does nothing. A skill that says "read DESIGN.md and use only its tokens" works, because the judgment is externalized into a file the agent can open. Put the knowledge in an artifact and let the skill be the pointer.

5. 5

   Test it by asking, not invoking

   Do not test with an explicit invocation; that proves nothing about the trigger. Phrase a request the way you naturally would and check whether the skill loads. If it does not, the description, not the body, is what needs editing.

Design is the perfect skill use case, and the perfect illustration of the artifact rule above. Anthropic ships a frontend design skill for Claude Code, and it genuinely improves single screens; we tested it and wrote up exactly what it does and what it misses. What it misses is memory between screens: the skill carries taste, not your values, so screen twenty drifts from screen one. Taste generalizes; identity does not.

The fix is the pattern from step four: the skill stays a thin procedure, and the identity lives in an artifact, a DESIGN.md at the repo root with real tokens, type choices, spacing rules, and do-not rules. The brand-audit skill at the top of this page is only twelve lines because everything it enforces is defined in that one file. That is what a design system for an agent is: not a plugin, a readable contract.

npx --yes identityforge@latest install --client claude-code

The skill format stopped being Claude-specific in a way that matters for what you invest in. OpenAI's Codex discovers SKILL.md folders under .agents/skills/ and ~/.agents/skills/ and invokes them with $; Cursor added Agent Skills with the same on-demand loading next to its always-on Rules, and has been steering long procedural rules toward skills. The convention is converging on the same shape everywhere: frontmatter that advertises, a body that instructs, loading that waits for relevance. Skills you write against artifacts in your repo, rather than against one tool's quirks, survive the tool churn.