Write your first AI skill in 15 minutes

If you have a prompt you paste every week, you are most of the way to a skill already. This post walks through writing one from scratch, using a real example.

The shape of a skill

A skill is a folder containing a file called SKILL.md. The file has two parts:

A header with a name and a description, between two lines of three dashes.
The instructions, in plain text or Markdown, below the header.

Here is a complete, working skill:

---
name: invoice-chaser
description: Drafts polite payment reminder emails for overdue invoices. Use when the user asks to chase, follow up or remind someone about an unpaid invoice.
---

# Invoice chaser

Write a short reminder email for an overdue invoice.

1. Ask for the client name, invoice number, amount and due date if they are missing.
2. Match the tone to how late the payment is:
   - Under 14 days: friendly, assume it was missed.
   - 14 to 30 days: direct, ask for a payment date.
   - Over 30 days: firm, mention next steps.
3. Keep it under 100 words. One clear request.
4. End with the payment details line exactly as the user gave it.

That is the whole thing. Save it as invoice-chaser/SKILL.md, zip the folder, and it is ready to add.

Write the description first

The description is the most important line in the skill. It is what your assistant reads to decide whether the skill applies. A good description says:

What it does, in one sentence.
When to use it, including the words people actually say: "chase", "follow up", "remind".

If the skill is not being picked up, the description is almost always the reason.

Write instructions like a checklist for a new colleague

Imagine handing the job to someone smart on their first day. What would they need to know? Write that down as numbered steps. Be specific about:

What to ask for if it is missing.
The decisions they will face, and how to make them.
Length, format and tone.
What never to do.

The SOP writer prompt can turn a messy description of how you do a job into clean steps.

Add reference files if you need them

If your skill needs a word list, a template or examples, put them in extra files inside the folder and mention them in the instructions: "Use the template in templates/reminder.md." The meeting notes skill is a good model to copy.

Test it on three real cases

Add the skill, then try it on three real situations, including an awkward one. Each time it gets something wrong, fix the instructions, not the answer. Three rounds is usually enough.

Share it

If your skill would help other people, submit it. We test every skill on real tasks before it goes in the library.