Claude Code Skills: Turn Each Agent Mistake Into a Rule

Claude Code skills are folders with a SKILL.md file: YAML frontmatter whose description tells Claude when to use the skill, and markdown instructions it follows when the skill runs (Claude Code docs: skills). Until a task matches that description or you type /skill-name, Claude sees only the description, so the body costs almost nothing until it is used. The harder question is what deserves a skill. My answer comes from a recorded talk by Lauren Tan, an engineer at Cursor: write one each time you watch an agent fail, and back the rules that must never fail with something harder than a skill.

What is in a Claude Code skill?

A folder whose name becomes the command, unless the frontmatter sets a name. It holds SKILL.md and, optionally, reference files Claude opens only when needed and scripts it can run (supporting files). Every frontmatter field is optional, but description is recommended, because Claude uses it to decide when to apply the skill (frontmatter reference). Claude Code skills follow the Agent Skills open standard, and older custom commands in .claude/commands/ now work the same way as skills. Claude Code also ships bundled skills, such as /code-review, /debug and /loop.

Where do Claude Code skills live?

If names collide, personal beats project (where skills load).

How does Claude decide to load a skill?

By default every skill's description sits in context, and the full body loads when you or Claude invoke it. disable-model-invocation: true makes a skill manual only, for anything with side effects like a deploy; user-invocable: false hides it from the / menu for background knowledge (who invokes a skill). The listing cuts description plus when_to_use at 1,536 characters, so put the main use case first. Once invoked, the body stays in the conversation without being re-read; after compaction Claude Code re-attaches at most the first 5,000 tokens of each skill, so the instructions that matter most belong at the top (skill content lifecycle).

How do I write a SKILL.md?

Write the description in the third person, naming both what the skill does and when to use it, because it is injected into the system prompt (writing effective descriptions). Keep the body short: once the skill loads, every line is a recurring token cost, so state what to do rather than why (types of skill content). Here is the consent rule from the table below, sketched as a skill:

---
name: consent-claim-check
description: Re-checks any claim about consent state, Consent Mode or a cookie banner before it goes into a report or an email. Use when a finding says consent is denied or a banner is missing.
---
 
A consent observation made from an EU location is EU-only.
 
1. Note where the check ran from.
2. If it ran from the EU, repeat it from outside the EU before stating it.
3. If it cannot be repeated, label the finding "seen from the EU".
4. Never send a consent claim that only the EU check supports.

Save it as .claude/skills/consent-claim-check/SKILL.md and test it by asking something that matches the description, or by typing /consent-claim-check. Claude can also draft one for you, since it knows the format natively (develop skills with Claude).

Which agent mistakes should become a skill?

Lauren Tan describes building her skill set one failure at a time. Reading an agent's tool calls, she saw it confidently name the cause of a bug without reading the code she expected to be affected; failure modes like that became skills telling the agent to stop guessing, look up the code and use subagents. She frames a skill as onboarding a strong engineer who has no business context, and reminds the audience that it is "just markdown". Anthropic's skill authoring guide puts it the same way: run Claude on representative tasks without a skill, document the specific failures, then write just enough instructions to close them.

Four problems from this blog and where each rule went

This blog's articles go through a multi-agent workflow: one writer per article, an independent fact-checker that re-reads the vendor's help pages and fixes or cuts claims, editor passes, and a render check in a real browser. Not every lesson became a skill file:

The format is a procedure a writer needs only while writing a manual, so it fits a skill better than the memory rule it sits in now; the parts a script can count already moved into the linter. The consent rule needs judgment about where a check ran, so it stays an instruction; the details are in testing Consent Mode from Europe. For the third-party skills, my block says it overrides everything below it and sits where the docs want the most important instructions, at the top. Read the allowed-tools of any skill you install, too: it grants tools without a prompt for the turn that invokes the skill, and workspace trust does not gate it (pre-approve tools).

CLAUDE.md, skill or hook: where should a rule go?

Lauren Tan draws the same line in the talk. She layers rules and skills but calls them soft, since an agent can forget them, and leans on lint rules and CI failures for anything that must hold. I cover the hook side in Claude Code hooks that enforce rules.

How do I know a skill works?

A skill that triggers only proves Claude found it. The docs' test is a baseline: run a few realistic prompts in fresh sessions with the skill available, again with it set to "off" in skillOverrides, and compare (evaluate a skill). The skill-creator plugin automates that loop, including a blind comparison of two skill versions. Lauren Tan treats evals as unit tests for skills and runs one each time she changes a skill; more in evals for agent skills.

What comes after skills?

A skill makes a mistake less likely; it does not make it impossible. The order that follows from the docs and the talk: a fact Claude keeps forgetting goes into CLAUDE.md or memory, a procedure becomes a skill, and anything a script can detect becomes a check that fails. That last layer is the one to trust, and here is how I build hard checks for agents.