Skills (SKILL.md), Explained From Zero

You've built a system of always-on instructions, scoped instructions, and on-demand prompt files. Skills fill the last gap: deep, specialised knowledge you need only occasionally — and they're perhaps the most powerful way yet to capture expertise.

1 · The knowledge you only sometimes need

Some knowledge is deep and detailed — how to correctly work with a tricky internal system, the full procedure for a database migration, the many steps of your deployment — but you only need it occasionally. It's too big to cram into your always-on instructions, where it would clog every request and waste context. Yet you want it available, in full, the moment a relevant task comes up. That's what skills are for: a skill packages a chunk of expert knowledge the assistant loads only when it's needed — deep know-how ready on the shelf without carrying it on every request.

2 · A skill is a folder of know-how

A skill is a small folder containing a main file — conventionally SKILL.md — and optionally some supporting files. Inside, you write, in plain language, the detailed instructions for a particular task: the steps, the gotchas, the commands, the do's and don'ts. Critically, the skill has a name and a short description of what it's for. That description is the clever part: the assistant reads just the little descriptions of all available skills all the time — which is cheap — but only pulls the full contents of a skill onto its desk when a task matches that description. The deep detail stays out of the way until it's relevant, then appears in full exactly when useful.

3 · How the agent picks a skill

Suppose you've written a skill called database-migration with a description like “use when creating or running database schema migrations.” You ask, in plain language, to add a new column to a table. The assistant, scanning its short list of skill descriptions, recognises the match — so it opens that skill and pulls the full procedure onto its desk. Now it follows your exact migration steps: the right command, the naming convention, the rollback file, the safety checks. You didn't name the skill; the task itself triggered it. That's the magic — the assistant reaches for the right playbook on its own. Well-written descriptions are what make that matching reliable.

4 · Why not just always-on instructions?

Why not put everything in always-on instructions? Because of the limited desk. Load every detailed procedure — migrations, deployments, that fiddly integration — into always-on instructions and three things break: requests get expensive (all that text ships every time), the context desk fills with detail irrelevant to most tasks, and the truly important always-on rules get diluted under mountains of occasional knowledge. Skills fix all three by inverting the default: deep knowledge sits on the shelf, summarised by a cheap description, and only its full weight loads when a matching task arrives. Unlimited depth of expertise, available without paying for it on every request.

5 · What makes a good skill

A good skill covers one clear job — “handle database migrations,” not “everything about the backend” — because a focused skill is easier to match and follow. It has a sharp description, since that one line decides whether the agent picks it at the right moment; vague descriptions get missed or misused. It gives concrete, actionable steps — the actual commands, conventions, and gotchas — rather than vague advice. And it can bundle helper files the main instructions point to: a template, a checklist, an example. Think of a skill as a well-organised playbook a senior engineer would hand you for a specific tricky task — complete, precise, self-contained.

6 · Skills, instructions, prompt files

Keep the toolkit distinct. Custom and scoped instructions are always-on rules, applied automatically. Prompt files are tasks you invoke on demand. Skills are deep knowledge the agent loads on demand when it recognises a match. The trigger differs — instructions are automatic, prompt files are triggered by you, skills by the agent — and the content differs — instructions are rules, prompt files are task recipes, skills are bodies of expertise. You use all three together: rules set the baseline, prompt files handle common tasks, and skills give the agent a library of deep expertise to reach into exactly when a task calls for it.

7 · Shared, versioned expertise

Skills are perhaps the most powerful way to make expertise collective, because they capture your deepest knowledge. When a senior engineer's hard-won understanding of the tricky payment integration is written into a skill and committed to the repo, that expertise becomes available to every developer's assistant on demand. A junior asking to touch the payment system automatically gets the senior's playbook — the safeguards, the sequence, the gotchas — without knowing it exists or interrupting anyone. The knowledge that usually lives in a few heads and leaks out slowly through review gets encoded, versioned, and applied automatically. Skills turn deep, specialised know-how from tribal folklore into shared, executable infrastructure — mentorship that scales.

8 · A simple test you can run this week

9 · Glossary — every term, spelled out

Skill

A folder packaging expert knowledge for a task, loaded by the agent on demand when a task matches.

SKILL.md

The main file of a skill, holding the detailed, plain-language instructions.

Description

A short summary of when a skill applies — the cheap index the agent scans to decide whether to load it.

On-demand loading

Pulling a skill's full contents onto the desk only when a task matches, keeping the rest lean.

Helper files

Templates, checklists, or examples a skill's main file points to.

Executable infrastructure

Deep expertise, encoded and versioned in skills, applied automatically instead of living in a few heads.