Write Your First Skill, Step by Step

Start from a real task you do well. Do it once while writing down every decision you make. Those notes are the raw material for the skill.

The people, companies and numbers in this lesson are made up. Check any figure against your own situation before you rely on it.

From Notes to Instructions

Maya does one month-end summary by hand and writes: 'Group by category. Anything over 500 gets a mention. If it moved 25 percent against last month I flag it. I never name the client in the summary. If I can't tell what an item is, I ask the client instead of guessing.' Those five notes became rules in the skill from the ten-minute lesson.

A Structure That Works

• Purpose: one sentence on what the skill is for.
• Inputs: what the user will give it, and what to ask for if missing.
• Steps: numbered, each one a single action.
• Rules: what to do and never do, including what to do when unsure.
• Output format: exactly how the result should look.
• Quality checks: a short list to run before handing back.

Write the Description Last

The description is what the agent reads to decide whether to load the skill. Say what the skill does and when to use it, in the third person. 'Turns a month of exported transactions into a short client summary. Use when the user pastes or attaches a month of transactions for a small business client.' A vague description means the skill never loads.

No-Code and Developer Versions

• No-code: write SKILL.md in a text editor and load it through your product's skill or custom instruction settings.
• Developer: keep the skill in a folder under version control, add a script for any step that must be exact (such as totals), and run your test table from a script.

Common Mistakes

• A vague description, so the agent never loads the skill or loads it at the wrong time. Fix: say what it does and when to use it.
• Too much in one skill. Fix: if it does two jobs, split it.
• No instruction for missing information. Fix: add a rule that says ask, or reply NEEDS REVIEW.
• Rules that conflict. Fix: read the rules aloud and delete the weaker one.

Exercise

• Write the full SKILL.md for the task you chose.
• Run it on at least ten rows or examples of synthetic or redacted material and compare the output to what you would have produced.
• Write down the three biggest differences. They become your next edits.
• Pass condition: a SKILL.md with name, description, numbered steps, a missing-information rule and an output format, and a one-line note for each difference.