Claude Code skills: how SKILL.md works and when the agent loads it

What skills in Claude Code are

A skill is a folder with a SKILL.md file that holds instructions for a specific type of task: how to deploy a project, how to run a review, how to ship a release. The agent knows that the skill exists from the start of the session, but reads it in full only when the task actually requires it.

Claude Code skills solve a problem familiar to everyone who has maintained a CLAUDE.md for a long time: the instruction file keeps growing. A deployment procedure of 80 lines is needed once a week, but in the file it takes up space in the context of every session — including when you fix a typo in the README. A skill moves such procedures out of the permanent context and loads them on demand.

What a skill consists of

The minimal skill is one folder and one file. Project skills live in the repository, personal ones in the user's home directory:

.claude/skills/deploy/SKILL.md      # project skill, shared by the team through git
~/.claude/skills/review/SKILL.md    # personal skill, available in all projects

Next to SKILL.md you can place auxiliary files: templates, scripts, reference material. The agent opens them only if the main text of the skill refers to them and they are needed:

.claude/skills/deploy/
├── SKILL.md           # main instructions
├── checklist.md       # detailed checklist, read by reference
└── rollback.sh        # rollback script

Frontmatter: name and description

The file starts with a YAML block between --- lines. Two fields matter more than the rest: name — the short name of the skill, and description — a description of what the skill does and when to apply it.

---
name: deploy
description: Deploy the site to hosting over FTP. Use when you need to upload changes to the server, check differences with the server or roll back a deployment.
---

# Deploy

1. First a dry run: `./deploy.sh -n`.
2. Check the list of files: it must not contain secrets or test scripts.
3. Upload: `./deploy.sh`.
4. Open the changed pages and make sure they return 200.

For rollback, see rollback.sh in this folder.

Below the frontmatter is ordinary Markdown: steps, commands, constraints, links to neighboring files. Write it the way you would write instructions for a new colleague who is doing this task for the first time.

When the agent loads a skill

At the start of a session, only the name and description of each available skill enter the context. That is a few lines per skill, so you can keep dozens of them. When the user's request or the current step of work matches a description, the agent invokes the skill — and only then is the full text of SKILL.md loaded into the context.

The main practical rule follows from this: a skill triggers by its description. The agent does not see the body of a skill until it has decided to open it. If the description says "Auxiliary skill", the agent will not understand when it is needed. If it says "Deploy to hosting; use when you need to upload changes to the server or roll back a deployment", it will.

Besides automatic selection, a skill can be invoked explicitly by name with a slash, for example /deploy. This is useful when you know exactly which procedure you need and do not want to rely on the agent matching the request to the description.

How to write a description so that the skill triggers

• What it does — in one verb-led phrase: "Deploy the site", "Review changes before a commit".
• When to use it — list the wordings the user actually uses to ask for this task: "upload to the server", "publish", "roll back".
• When not to use it, if the skill is easy to confuse with a neighboring one: "not for deploying the bot, only the site".
• Avoid vague phrases such as "a useful skill" or "helps with work" — they carry no signal.

Progressive disclosure

Skills are built on the principle of progressive disclosure: information is presented in layers, and each next layer is loaded only when it is needed.

This is the same idea as a router instead of a wall of text in an instruction file: a short map is always at hand, and the details are one link away. The difference is that a skill makes such loading a standard mechanism, rather than relying on the hope that the agent will open the right document on its own. A further benefit: a script from layer 3 can simply be executed by the agent without loading its whole code into the context.

Skills, CLAUDE.md and slash commands: the difference

All three mechanisms pass instructions to the agent, but at different moments and at different cost to the context.

The practical rule for choosing is simple. If an instruction is needed in almost every task, it belongs in CLAUDE.md. If it is needed for tasks of a certain type, it is a skill. If you keep typing the same long request yourself, it is a candidate for a command or for a skill invoked by hand.

Do not move hard prohibitions into a skill. A skill may not load, while the rule "never commit secrets" must always apply. Such invariants stay in CLAUDE.md and, where possible, are reinforced with mechanisms: hooks, access rights, checks in CI.

How to create a skill for Claude Code: step by step

1. Find a recurring procedure. A good sign: you have already explained the same thing to the agent three times, or CLAUDE.md has a section that is needed in one task out of ten.
2. Create the folder .claude/skills/<name>/ and a SKILL.md file inside it.
3. Write the frontmatter with name and description, stating clearly when to apply the skill.
4. Describe the steps with concrete commands and readiness criteria: what to check, what result counts as success.
5. Move long material into neighboring files and refer to them from the main text.
6. Remove the duplicate from CLAUDE.md, leaving one pointer line: "Deploy — the deploy skill".
7. Test it: in a new session, describe the task in your own words, without naming the skill, and see whether the agent picks it up. If not, rewrite the description.

Examples of skills

A deploy skill

The classic candidate: the procedure is rare, long and risky, and a mistake is costly. The skill fixes the order of steps (a dry run first, then the upload), what must not be uploaded, how to check the result and how to roll back. The agent does not have to keep this in mind for every code edit — only when the server comes up.

A review skill

---
name: review
description: Review current changes before a commit. Use when asked to check the diff, find bugs in the edits or prepare changes for a commit.
---

# Reviewing changes

1. Get the diff: `git diff` and `git diff --staged`.
2. For each changed file, check:
   - user input is escaped on output;
   - SQL queries are parameterized;
   - there is no debug output or temporary files.
3. Run the project's tests and linter (the commands are in CLAUDE.md).
4. Report: a list of problems with file and line, from serious to minor.
   If there are no problems, say so, without invented remarks.

Such a skill turns "check that everything is fine" into a reproducible check with the same set of items every time.

A session-closing skill

Another useful type is a ritual at the end of work: stop the local environment, delete temporary files, add to the progress journal what was done and what is left, and make a commit with a detailed description. This directly cures the loss of context between sessions: the next session starts from the actual state of the repository, not from guesses.

Common mistakes

• A vague description. The skill exists, but the agent does not invoke it. Fix it by rewriting the description with concrete triggers.
• A skill that is a wall of text. The whole old 400-line section was moved into SKILL.md. The bloated-context problem is back, just later. Keep the main text short and the details in neighboring files.
• Duplication with CLAUDE.md. The same procedure is described in two places and drifts apart over time. There should be one source of truth.
• Overlapping skills. Two skills with similar descriptions — the agent picks between them at random. Separate them with explicit "use / do not use" statements.
• Outdated commands. A script was renamed, but the skill still points to the old name. A skill is part of the project's code: update it in the same commit as the procedure.

How to tell when a section should become a skill

It is worth going through CLAUDE.md now and then and asking, for each section: in what share of ordinary tasks is it actually needed? If it is needed almost always, it belongs where it is. If it is needed in one task out of ten, it is a candidate for a skill.

The second signal is length. A section that does not fit on one screen almost certainly describes a procedure, not a rule. Procedures are easier to read in full at the moment of execution than to keep in the background for the whole session.

The third signal is repeated explanations. If you keep telling the agent the same clarifications for the same task, write them down once in a skill. A week later, check whether the number of manual corrections has dropped: that is the proof that the skill works.

Summary

Claude Code skills are a way to keep procedures next to the project without paying for them in context in every session. The skill's description is always visible, the body loads on demand, and auxiliary files load later still. CLAUDE.md keeps the project map and the hard rules, while deploys, reviews, releases and other tasks of a particular type move into skills. The structure of instruction files and progressive disclosure of context are covered step by step in our harness engineering course.