Skills

What skills are in Claude Code, how they get invoked, where they live, and how to write a simple SKILL.md.

A skill is a package of instructions that teaches Claude how to handle one kind of task — your deploy steps, a code review checklist, the conventions of a particular module. Instead of explaining the same thing every time, you write it down once as a skill.

The key part is that skills load on demand. Only a short description sits in the context; the full instructions come in when the task calls for them. That’s why you can keep many skills around without weighing the session down.

How they’re invoked

That makes description the most important field: it’s the only thing Claude sees before deciding whether to open the skill.

/create-commit
/deploy-staging

Skills that come from a plugin are invoked with a prefix — the plugin name, a colon, the skill name:

/mattpocock-skills:tdd

Where they live

A simple SKILL.md

The minimal skill is YAML frontmatter with name and description, followed by Markdown instructions:

---
name: deploy-staging
description: Deploys the current branch to staging. Use when the user asks to deploy, ship, or push to staging.
---

# Deploy to staging

## Before deploying

1. Check that the tests pass: `pnpm test`
2. Check that there are no uncommitted changes: `git status`

## Deploy

```bash
pnpm build
pnpm exec vercel deploy --prebuilt
```

## After deploying

Check the health endpoint and report the deployment URL.

What makes a description good

A skill can be just a prompt

Not every skill wraps scripts and reference files. If there’s a paragraph you keep retyping — a review stance, a formatting rule, a request you make at the start of every project — that paragraph already is a skill. Save it once and it becomes one command.

The clearest example is grilling, Matt Pocock’s interview skill. Its entire body:

Interview me relentlessly about every aspect of this until we reach a shared
understanding. Walk down each branch of the decision tree, resolving dependencies
between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before
continuing. Asking multiple questions at once is bewildering.

If a *fact* can be found by exploring the environment (filesystem, tools, etc.),
look it up rather than asking me. The *decisions*, though, are mine — put each one
to me and wait for my answer.

Do not act on it until I confirm we have reached a shared understanding.

Why it earns a permanent slot: a brain dump always has gaps you can’t see, because you don’t know which parts of your own context are missing. An interview finds them — one question at a time, each arriving with a recommended answer so you’re editing instead of authoring. It’s the packaged form of the “make it ask until it’s sure” habit.

It ships in the official plugin marketplace: run /plugin, install mattpocock-skills, then say “grill me about this plan” — or invoke it directly with the plugin prefix.

Supporting files

A skill isn’t only one file. Next to SKILL.md you can put:

• references/ — long reference material Claude reads only when it needs it.
• scripts/ — ready-made scripts the skill calls instead of rewriting them each time.
• assets/ — templates, configs, patch files.

The idea is to keep SKILL.md short and have it point at the rest: “for the full list, see references/checklist.md”.

Skill or subagent?

The two combine well: a subagent that loads a skill is a very common setup.