A skill is a markdown file. That’s the whole technology. If you can write a decent handover note for a colleague, you can write a skill — and the mental model is almost exactly that: you’re briefing someone competent who has never done this specific task at this specific company.

Start with work you’ve already done

Don’t sit down to write a skill from a blank page. You’ll describe the process as you imagine it, which is a tidier and less useful thing than how it actually goes.

Instead, wait until you’ve just finished working something out — a recap format that finally came out right, a way of structuring a client update that landed well. Then capture it while it’s fresh. The Turn This Thread Into a Skill prompt does exactly this: it audits the conversation you just had and pulls out the rules you arrived at, including the corrections you made along the way.

The corrections are the most valuable part. Every time you said “no, not like that, do it this way” is a rule that a from-scratch version would have missed.

What goes in the file

---
name: post-show-recap
description: Turn raw show-floor notes into a structured post-show recap...
---

# Post-show recap

## What this is for
...

## Inputs it needs
...

## Procedure
1. ...

Two parts: the frontmatter (between the --- lines) and the body.

The description decides everything

Claude reads the description to decide whether the skill is relevant to what you just asked. The body is only loaded after that decision is made. So a brilliant skill with a vague description never runs, and you’ll conclude that skills don’t work.

A good description does three things, in order:

1. What it does, plainly.
2. The literal phrases you’d say to trigger it. Not paraphrases — the actual words.
3. What it should NOT be used for, and what to use instead.

Write the description last, once the body has settled and you know what the skill actually does.

Make it portable

The single most common reason a shared skill breaks on a colleague’s machine:

• No paths from your computer. /Users/yourname/Documents/… doesn’t exist for anyone else.
• No tools the other person may not have connected. If the skill genuinely requires a connected calendar or document store, say so at the top so the failure is legible.
• No names that only mean something to you. Internal project codenames, a colleague’s initials, last quarter’s client.

Test it before you trust it

Three cases, every time: the obvious one it should handle cleanly, the awkward one, and the one it should refuse because it’s outside what the skill is for. That third case is the one nobody tests, and it’s the one that matters.