How to write a skill for your own practice

A Part 2 gets about ten minutes before their first issue sheet. Ten minutes covers the numbering, the revision letters, who signs, and the two mistakes everybody makes. It does not cover the rest, so the rest arrives over the following year, one correction at a time.

Those ten minutes are a skill. So is most of what an office knows and has never written down. The only question is which ten minutes to write first, and the test is not importance. It is repetition: have you explained this to someone twice?

Pick something narrow you have explained twice

The instinct is to start with something important. Start with something small and frequent instead. The first skill you write is where you learn the format, and a modest one that works will teach you more than an ambitious one that sits unused.

Good candidates share a shape. They are tasks with a right answer you could describe in a sentence: the structure and order of a document your office produces the same way every time, a checking pass with a fixed sequence, a naming or numbering convention, the way a consultant's report gets reduced to something a client will read, the register and structure of a particular kind of letter.

The bad candidates are the ones that feel most valuable. Design judgement does not compress into instructions. Neither does anything resting on facts the assistant cannot check — a task that needs this week's fee scale or the current version of a code document produces a skill that is confidently out of date by spring. And anything you do twice a year will never be maintained, which means it will be wrong the third time you reach for it.

One test before you write a word: can you say in a single sentence what a correct output looks like? If you cannot, the procedure is not agreed, and no amount of drafting will settle it.

Write the description before the instructions

Every skill carries a name and a description at the top of its file, in a short header block called frontmatter. The name is a label — lowercase, hyphens, under sixty-four characters. The description is the whole game.

It is the only part of your skill an assistant sees before deciding whether to open the file, and it has to carry two things: what the skill does, and when it should be used. Write it in the third person, and put in the words your colleagues actually say. Issue sheet, DAS, RFI schedule, stage two report — the vocabulary of the request rather than the vocabulary of the procedure. Anthropic's specification allows 1,024 characters, which is more room than it sounds.

A description works something like a drawing register: nothing gets found that is not indexed under a name somebody would think to look for, and a sheet titled "Miscellaneous" is a sheet nobody opens. The comparison stops short at the place that matters. A register is searched by a person who already knows roughly what they want, whereas the assistant is matching a request against every description it holds without knowing your office's habits of speech. Assistants under-reach for skills far more often than they over-reach. Write the description for the version of the request a tired colleague would type at five o'clock.

Then brief a competent stranger

The body of the file is the instructions, in plain Markdown, and the register to aim for is a brief to someone capable who has never worked here.

That means not explaining what a design and access statement is, and explaining precisely what yours contains, in what order, and what gets checked before it leaves the office. Assume general competence and supply only what is particular to you. Anthropic's authoring guidance puts the same rule in a line: add only the context the model does not already have.

Match how specific you are to how fragile the task is. Where several approaches would all be acceptable, give direction and leave the route open. Where the sequence genuinely matters — a checking order, a numbering rule, a clause that must appear verbatim — state it exactly and say it is not to be varied. Most first drafts get this backwards, over-specifying the open parts and waving a hand at the fixed ones.

Two habits keep a skill usable. Choose one word for each thing and never vary it, because synonyms read as different instructions. And keep the main file short: the published guidance is to stay under five hundred lines and move detail into separate reference files linked directly from SKILL.md, one step away rather than three. Those files stay unread until the task calls for them, so a long reference costs nothing until it is needed.

Test it against real work

Do this before you write much, not after.

Run three real tasks — actual jobs from the office, not invented examples — with no skill installed, and write down exactly where the output came back wrong or thin. That list is your specification. It is also the only reliable defence against the usual failure, which is a skill that documents an imagined problem beautifully.

Then run the same three with the skill loaded, and watch two things. Did it trigger at all, without you naming it? If not, the description is the problem and the instructions are innocent. And did the output actually change? A skill that produces what you would have got anyway is a document rather than a skill, and it is still spending everyone's attention.

Then hand it to someone who did not write it. They will phrase the request differently, which is the test that counts.

Give it a version, an owner and a date

The same discipline as a drawing. A skill with no revision marker goes wrong quietly, and a stale skill is worse than none, because it is wrong in the house style and therefore convincing.

Put the version and the author near the top of the file, and decide who reviews it and when. Then work out how a revision travels. In the Claude apps each person holds their own uploaded copy, so an update reaches nobody until every one of them uploads it again. That is an administrative fact rather than a technical one, and it is where most office-wide skills quietly fall out of date.

FIG. 01 — Rev C, and the two before it. A skill with no revision marker goes wrong quietly.

What you actually end up with

The file is the smaller half of it.

Most practices discover, somewhere around the second draft, that the procedure they were writing down had never been agreed. Two people build the drawing register differently. The check nobody skips turns out to be a check two people had never heard of. Settling those arguments is most of the work, and it produces something the office did not have: a written account of how it does a thing, readable by anyone, owned by someone.

Keep that document even if you never install it.