What are agent skills? Design rules your agent follows

Agent skills are folders of instructions that a coding agent loads only when the task calls for them. The format is a directory with a SKILL.md file inside it, and that file is the whole contract — metadata at the top, instructions below.

Most explanations stop at the file format. The more useful question is what belongs in a skill, and the answer is broader than "how to process a PDF": a skill is also where you put the judgment calls you keep making by hand.

What is an agent skill, exactly?

A skill is a folder containing a SKILL.md file with YAML frontmatter (name and description, at minimum) and markdown instructions. It can bundle anything else it needs alongside that entrypoint — scripts, reference documents, templates:

my-skill/
├── SKILL.md          # required: metadata + instructions
├── references/       # optional: documentation loaded on demand
├── scripts/          # optional: executable code
└── assets/           # optional: templates, resources

The format was developed by Anthropic and released as an open standard, and it is now read by a long list of agents and editors beyond Claude Code. A skill you write once is portable across the tools your team already uses.

In Claude Code, where the folder lives determines who gets it. ~/.claude/skills/<name>/SKILL.md is personal and applies to all your projects; .claude/skills/<name>/SKILL.md is committed to the repo and applies to that project only. The directory name becomes the command, so .claude/skills/deploy-staging/ gives you /deploy-staging.

How does an agent decide to load a skill?

Through progressive disclosure, in three stages. The distinction matters because it determines what a skill costs you.

Level 1 — metadata. At startup, the agent loads only the name and description from every available skill, roughly 100 tokens each. This is the listing it matches your request against.

Level 2 — instructions. When a request matches a description, the agent reads SKILL.md from disk and its body enters context. Anthropic's guidance puts this level under 5k tokens.

Level 3 — bundled files. Reference documents load when the instructions point to them and the task needs them. Scripts run through bash, so only their output costs tokens, never their source.

The practical consequence: you can install many skills without paying for them. Until one triggers, it costs you a name and a description. A skill can bundle an entire API reference and that reference stays free until something reads it.

One caveat worth knowing before you write a long skill. In Claude Code, once a skill's rendered content enters the conversation, it stays there for the rest of the session — the file is not re-read on later turns. Every line in the body is a recurring cost, not a one-time one. Write standing instructions, not a narration of steps.

Skills or CLAUDE.md — which one holds this rule?

This is the question that trips people up, and the split is cleaner than it looks.

CLAUDE.md holds facts that are true for every session in this repo: the package manager, the test command, the directory layout, the conventions that apply whether you are fixing a typo or shipping a feature. It loads every time, so it should stay short.

A skill holds a procedure. The signal that something has outgrown CLAUDE.md is that a section of it has turned into steps — first do this, then check that, then verify. Move it into a skill and it stops costing context on the sessions that don't need it.

The failure mode of getting this wrong is quiet. Procedures pile up in CLAUDE.md, the file grows past what the agent reliably attends to, and the rules at the bottom stop being followed without anything reporting an error.

What goes in the frontmatter?

Two fields carry real weight, and both have limits worth knowing.

---
name: reviewing-migrations
description: Reviews database migration files for reversibility, locking risk, and data loss. Use when the user adds or edits a migration, or asks to review schema changes.
---

name is capped at 64 characters and accepts lowercase letters, numbers, and hyphens only. It cannot contain the reserved words "anthropic" or "claude". Gerund form (reviewing-migrations, analyzing-spreadsheets) reads well in a listing, though noun phrases work too.

description is capped at 1,024 characters and is the single highest-leverage line in the file. It is the only thing the agent sees when deciding whether your skill applies, so it needs to state both what the skill does and when to use it — including the words a person would actually type. Write it in third person: the description is injected into the system prompt, and mixing points of view ("I can help you...") degrades matching.

Two symptoms map directly back to this field. A skill that never fires usually has a description missing the keywords people use. A skill that fires when you don't want it usually has a description that is too broad — narrow it, or add disable-model-invocation: true so it only runs when you type /name.

Claude Code adds optional fields on top of the standard — allowed-tools to pre-approve tools for the invoking turn, context: fork to run the skill in its own subagent, paths to limit activation to matching files. All of them are optional. Only description is genuinely recommended.

What separates a skill that works from one that doesn't?

Three things, in rough order of impact.

Assume the model is already competent. Anthropic's authoring guidance is blunt about this: only add context the agent doesn't already have. An explanation of what a PDF is, or why migrations need reversibility, is tokens spent teaching something already known. State the decision, not the background.

Match specificity to fragility. Where several approaches are valid and context decides, give direction and let the agent choose. Where the operation is fragile and a specific sequence must hold, give the exact command and say not to vary it. The mistake is applying one register everywhere — rigid instructions for open-ended work produce brittle output, loose instructions for fragile work produce broken output.

Keep the body short and the references flat. The recommendation is a SKILL.md body under 500 lines, with detail split into separate files. Keep those references one level deep from SKILL.md — an agent that follows a reference to a reference tends to preview files rather than read them, and preview means incomplete.

Can a skill encode design decisions, not only capabilities?

Most published skills add a capability the agent lacked: read this file format, call this API, run this deployment. That framing undersells the format. A skill can equally well constrain quality — encoding the judgment that separates output that looks designed from output that looks generated.

Design rules are a good fit for the format because they are procedural, they are the same every time, and they are exactly what an agent has no way to infer from your repo. A marketing page has constraints a general-purpose model will not guess at:

• A headline budget. Every heading fits on at most two visual lines in its block. Size the copy to the budget, not the block to the copy.
• Section rhythm. Adjacent sections alternate — text and media swap sides, centered layouts alternate with split ones — so the page reads with movement instead of monotony.
• Even measure across a row. List and grid item descriptions stay similar in length, so text lines land evenly.
• No invented proof. When a claim has no evidence behind it, soften the claim or ask for evidence. Never manufacture a metric or a testimonial.

None of these are capabilities. They are constraints, and each one is a decision a designer would make without being asked. Written into a skill, they apply on every page the agent touches, including the ones you edit six months from now.

The same reasoning extends past design. Copy rules, accessibility requirements, the sections your funnel actually needs — anything you keep correcting by hand after the agent finishes is a candidate.

Installing a skill pack you didn't write

Skills are files, which means they can ship through a registry like any other component. Initium's skill pack installs through shadcn:

npx shadcn@latest add @initium/initium-agent

That places the entrypoint at .agents/skills/initium/SKILL.md with its supporting documents in .agents/skills/initium/references/ — the progressive disclosure pattern applied to a real workflow. The entrypoint sequences the build (setup, strategy, copy, blocks, QA) with a gate at each step; the references hold the style rules, copywriting constraints, and block selection guidance that load only when that step is reached.

If your agent discovers project skills automatically, it picks the pack up from there. If it doesn't, point it at the entrypoint directly:

Read .agents/skills/initium/SKILL.md before changing UI code.

Because the format is an open standard, the same folder works whether your team is on Claude Code, Cursor, or something else — the rules travel with the repo rather than with one person's setup.

The skills documentation covers installation requirements and the manual fallback if your project can't install through the registry.