Custom skills and SKILL.md design

What you’ll be able to do

Decide when a task deserves a skill versus a plain instruction
Structure a SKILL.md so it triggers reliably and reads clearly
Design a skill’s output to stay short so it doesn’t bloat the calling session

What you need to know

A skill is a packaged, reusable procedure — not a one-off instruction

A Skill is a named, discoverable unit of instructions Claude Code loads on demand when a task matches its description. The architectural test for "does this deserve a skill" is repetition and shape: if a team runs the same kind of procedure — a release checklist, a codebase audit, a migration pattern — often enough that its steps are worth writing down once and triggering by name, that's a skill. A task done once, for one PR, is a prompt.

The description field is the trigger. It has to be specific enough to fire on the right requests and not so broad that it fires (or fails to fire) unpredictably. "Helps with code" will never trigger reliably. "Run the pre-release checklist: version bump, changelog, tag" triggers on exactly the requests that mean that.

Structure: frontmatter, then procedure

A SKILL.md is a markdown file with YAML frontmatter (name, description, and any execution directives) followed by the actual instructions. Good skill bodies read like a runbook: numbered steps, explicit tools to use, and the conditions under which the skill should stop and ask rather than guess.

Name and description carry the triggering weight — write them for the matcher, not just for a human skimming a file list.
The body is the actual procedure — concrete steps, not a restatement of the description.
Bundled files (templates, reference data, scripts) belong alongside the skill and are loaded only when the skill actually runs — this is what keeps having many skills cheap.

Design the output, not just the procedure

The most common architectural mistake is designing what a skill does without designing what it reports back. A skill that reads forty files and returns all forty files' contents to the main session has, from the calling session's point of view, done nothing to reduce context load — it just moved the reading step one layer down.

before — skill dumps its full working transcript back to the caller

Skill reads 40 files, prints every file's contents and its reasoning about each one. → full transcript returned

after — skill returns a short structured summary

Skill reads 40 files internally, returns: 6 modules mapped, 3 architectural risks flagged, file:line references only.

Design the report first: what does the calling session actually need to act on next? Usually it's a short structured summary and a handful of file:line references, not a transcript of the work. (Isolating that internal work in its own subagent context is the mechanism for this — covered in the next lesson.)

Key concept

A skill earns its place through repeated, shaped use, triggers on a specific description, and is judged by what it reports back — not just what it does internally.

When a scenario describes "skills that never trigger" or "skills that clutter every session," the fix is almost always the description (too vague) or the output design (too verbose), not the underlying procedure.

Practice scenario

ScenarioA team wrote a skill called "helper" with the description "assists with various development tasks." It rarely triggers when they want it, and when it does trigger it's often the wrong moment.

Work it through, then open this

The description is the entire problem. A matcher can’t reliably fire on “various development tasks” because it describes almost nothing specific. Rename and rewrite it around the actual repeated procedure it performs — for example “Run the API contract-compatibility check between two branches” — so the trigger condition is unambiguous. If the skill genuinely does several unrelated things, split it into several narrowly-described skills rather than one broad one.

Build exercise — Design a skill’s output before its procedure

Intermediate · 25 min

What you’ll learn

Writing a triggering description that fires on the right requests
Separating “what the skill does” from “what it reports”
Spotting a skill whose output will bloat every session that calls it

Take a repeated procedure your team does manually and write a one-sentence description specific enough to trigger only on that procedure.
- Why: A vague description either never fires or fires on the wrong requests — the description carries all the matching weight.
- You should see: A description that names the specific procedure, not a general capability area.
Before writing the skill’s steps, write down exactly what it should return to the calling session — in one or two sentences.
- Why: Designing the report first prevents a skill that quietly dumps its full internal working output back into every session that calls it.
- You should see: A short, structured summary shape — not “everything it read or did.”

Exam traps

Creating a skill for a task that’s only ever done once

Skills exist for repeated, shaped work. A one-off task is a prompt, not a skill.

Writing a vague skill description that never triggers or triggers on everything

The description is the entire matching signal. Specific and narrow beats broad and general.

Letting a skill’s full working output land back in the main session

The report should be a short structured summary, not a transcript of everything the skill read or did.

Duplicating logic across two skills instead of one skill both paths can call

Shared procedure belongs in one skill; two near-identical skills will drift apart the first time one gets updated and the other doesn’t.

Assuming a skill runs with the same permissions and context as the main session by default

A skill’s execution context and access are governed by its own configuration, not inherited assumptions from the calling session.

Sources

Claude Code Docs