Writing Your First Skill

Pick the smallest thing that keeps repeating

Not the impressive one. The dull one. The formatting rule you retype, the phrase you always ban, the structure your team agreed on eighteen months ago and still explains to every AI conversation from scratch.

A first skill should do one job you can state in a sentence. If you cannot finish the sentence "this skill is for when I am ...", you have picked something too broad. Go back to the tally from lesson 2 and take the item with the most marks against it.

The four steps, and they really are four

Make a folder, with a short lowercase name using hyphens instead of spaces. Inside it, make a file called SKILL.md in any plain text editor. At the top of that file, write the labelled lines. Below them, write the instructions.

That is the whole build. What follows is about getting the labelled lines right, because that is where first skills succeed or fail.

--- (a row of three dashes opens the labelled lines)
name: meeting-notes
description: Use when writing up notes from a meeting, or tidying
rough notes somebody else took, for internal circulation.
--- (a row of three dashes closes them, instructions run from here)
Structure every set of notes in three sections, in this order.
Decisions.
One line each. State what was decided, not the discussion around it.
If something was discussed but not settled, it is not a decision.
Actions.
One line each, in the form: what, who, by when. Every action needs
a named person. If nobody was named in the meeting, write
OWNER NOT AGREED rather than guessing.
Open questions.
Anything unresolved, stated as a question.
Always:

No bullet longer than one line
Plain English, no jargon from the meeting unless it is a real term
Never invent an attendee, a date or a figure that was not said
Never:

Do not add a summary paragraph at the top
Do not use the words synergy, leverage or robust

The rows of three dashes are just markers showing where the labelled section starts and ends. Between them sit two things: a name, and a description. Everything after the closing row is ordinary writing. Paragraphs, section titles, lists, whatever makes the instructions clear to read.

The description is the whole game

Remember what lesson 1 said about the shelf of ring binders. Claude reads the spines. The description is the spine.

This means the description is not a summary of the skill. It is not there to tell a human what the skill contains. Its one job is to answer a question Claude is asking about the task in front of it right now: does this apply here?

So write it as a situation, not a topic. Topics are nouns and they match nothing. Situations are moments, described in the words a real request would use.

The practical trick is to write the description last. Write the instructions first, while you know what you mean. Then look at what you have built and ask: in what exact moments do I want this? Write those moments down, in the words you would use when asking. That is your description.

A second trick: think of the three most recent times you explained this. What did you type? Those phrasings are the ones the description needs to catch.

--- (row of three dashes)
name: [short-lowercase-name-with-hyphens]
description: Use when [the exact situation, in the words a real
request would use]. Also use when [a second phrasing of the same
situation, if people ask for it two different ways].
--- (row of three dashes)
[One line saying what the output should be.]
Always:

[rule]
[rule]
[rule]
Never:

[thing you keep having to correct]
[phrase you have banned]
When you are unsure:
[What to do rather than guess. Usually: mark it clearly and stop.]

Keep the first version short. You are going to find out what it gets wrong by using it, and a shorter skill is far easier to correct than a long one you are attached to.

What to leave out

Two things creep into first skills and do no work at all.

Background is the first. Three paragraphs explaining why your team settled on this format, who objected, and what the old one was like. None of that changes the output, and all of it pushes the actual rules further down the page.

Politeness is the second. Please try to, where possible, it would be helpful if. Those phrasings soften an instruction you meant as absolute, and a softened rule is a rule that loses whenever it meets a competing pressure. Write the rule as a rule. Keep the explanation for the colleague who asks.

Below are the instructions from a skill I have written, and three
things I actually typed the last three times I asked for this job.
Write me a description for the skill, one or two lines. It should
name the situations the skill applies to, using the same kind of
wording as my three examples. Do not summarise what the
instructions say. Do not describe the topic. Name the moment.
MY INSTRUCTIONS:
[paste them]
WHAT I TYPED THE LAST THREE TIMES:
[paste them]