Claude Code skills: teach your agent once, load it only when it matters

You taught Claude Code how your team writes database migrations. It took an afternoon to get right: the naming convention, the rollback rule, the one table nobody touches. The lesson went into CLAUDE.md, where it joined the release notes procedure, the chart styling rules, and the incident report template. Line by line, your instructions file grew into a manual.

Here is the bill for that manual: every session pays for all of it on every turn, including the session that is renaming a variable. And when an agent finally does write a migration, your checklist competes for attention with two hundred lines of unrelated advice. The more you teach this way, the worse each lesson works. Claude Code skills exist to break exactly that trade.

What a Claude Code skill actually is

A skill is a folder. At its center is a SKILL.md file: a few lines of YAML frontmatter (a name and a description) followed by instructions in plain Markdown. Around it sit whatever the job needs: reference docs, templates, a script that handles the deterministic part. Put the folder in .claude/skills/ for one project or ~/.claude/skills/ for every project, and Claude Code discovers it on its own. Anthropic's public skills repository is a good gallery of what real ones look like.

The key property: skills load on demand. At session start the agent sees only each skill's name and description, roughly a hundred tokens per skill. When your task matches a description, the agent opens the folder, reads the full instructions, and pulls in supporting files only if it needs them. When the instructions point at a script, it runs the script and only the output enters the conversation. You can install fifty skills and pay, in context, for the two that today's work actually uses.

On-demand context beats a bigger CLAUDE.md

Your instructions file is always in context. That is its job: project conventions ride along on every single turn. It is also its limitation, because context is the resource long sessions run out of first, and every specialist paragraph you add taxes every generalist turn.

Skills invert the economics. Deep expertise costs nothing until it is needed, and it arrives complete when it is: not a half-remembered summary that survived compaction, but the full checklist, read fresh from disk at the moment of use. That makes a skill the natural home for know-how that is deep but occasional, which describes most of what teams currently stuff into their instructions file.

One home for every rule

Claude Code now gives you several places to put knowledge, and most agent frustration traces back to the right rule living in the wrong home:

• CLAUDE.md holds what is true on every turn. Project layout, tone, the test command. Short, universal, always loaded.
• Skills hold expertise used occasionally. Migration rules, release procedures, report generation. Deep, specialized, loaded when relevant.
• Slash commands hold workflows you trigger. The difference is who decides: you invoke a command by name, while the model reaches for a skill because the task fits its description.
• Hooks hold rules that must never break. A skill can teach the formatter's style; only a hook guarantees the formatter runs.

Sort your current CLAUDE.md into those four buckets and it usually shrinks by half, while the specialist knowledge gets sharper, because it no longer has to stay short enough to rent context permanently. And when the same buckets need to reach another repo or teammate, package them as a Claude Code plugin and install them instead of pasting them.

Where Claude Code skills go wrong

The honest section, because the failure modes are real:

• The description decides everything. The agent picks skills by matching your task against that one frontmatter line. Write "helps with documents" and it fires never, or constantly. Write "generate the monthly revenue report PDF from the exports folder" and it fires on target. Treat the description as an API contract, not a caption.
• Non-use is silent. A skill that does not trigger produces no error; the agent just improvises without it, and the output still looks plausible. After writing a skill, ask for a matching task once and watch whether it actually loads before you trust it.
• Skills rot with confidence. When the convention changes and the skill does not, agents keep applying the old procedure with full conviction. A wrong skill is worse than no skill, because you stopped explaining the task in prompts the day you packaged it. Version skills and review their changes like any other code.
• Third-party skills are code you are choosing to run. A skill folder can carry executable scripts, and its instructions steer your agent. Read a stranger's skill the way you would read a stranger's pull request.

Skills scale the knowledge; SanuDesk scales the sessions

A skill travels well: write the release-notes skill once and every project and teammate can load it. What it cannot do is run the work. Somebody still opens sessions, hands out tasks, and checks results, and that operator layer is what SanuDesk is built for.

It is a desktop app that puts your Claude Code, Codex and Gemini sessions in one tiled grid next to a Kanban board that does the dispatching: write the task as a card, deploy it to a fresh session with one click, and when the agent stops, the card parks itself in a review lane with a "what changed, how to test it" note. Skills pair naturally with Loops, SanuDesk's recurring jobs: the weekly changelog Loop fires, the session it opens finds your changelog skill, and the same procedure runs the same way every Friday without the card having to carry the how. It is bring-your-own-model, so your existing agent subscriptions do the work, and the grid and board are in the free plan (details on pricing).

Skills make any single session an expert. The board is how a fleet of expert sessions stays accountable.

Try this today

Open your CLAUDE.md and find the longest section most sessions never use. Move it into .claude/skills/<name>/SKILL.md, spend five careful minutes on the description line, then delete the section from CLAUDE.md. Ask the agent for a task the skill should catch, and watch the transcript for the moment it reads the file before doing the job. The official skills docs cover the frontmatter options if you want to go deeper.

You have made your instructions file lighter and one piece of know-how permanent in the same move. Next week, promote the next section the same way.

Download SanuDesk free to give your newly expert sessions a grid and a board, or see how the grid, board and Loops fit together on the features page.