Practice - write your first skill

The previous three lessons described the anatomy of a skill file. This session is where you write one. The task is not hypothetical — you are writing a skill for a real procedure you already do.

What this actually is

This is a constrained writing exercise. You will produce one .md file with three sections. The constraint is specificity: every step must name the exact command, the exact file, or the exact success criterion. Any step that could be interpreted two ways must be rewritten until it cannot.

Walk-through

Pick a task you do at least once a week. Good candidates:

• Deploying a site or service
• Reviewing a pull request (your standard checklist)
• Writing a weekly status update
• Onboarding a new team member to a repository
• Running a database backup and verifying it

Bad candidates: anything too large to complete in a single session, anything with steps that vary wildly each time, anything that requires human judgment at every step.

Once you have the task, open a blank file and write the frontmatter first:

---
name: your-task-name
description: One sentence, what this does and when
author: Your Name
version: 1.0.0
---

Then write the procedure from memory — do not look at existing docs yet. Write what you actually do, not what you think you should do. You will have extra steps. You will forget some steps. Both of those are data.

After writing from memory, do the task once while reading your own steps. Where you deviate from the steps, update the steps. Where you add an implicit action that is not written, add the step.

Then write the gotchas. For each step that can fail, write what failure looks like and what to do. Aim for at least three gotchas.

Testing the skill

Give the completed file to Claude with this prompt:

Read this skill file and tell me:
1. Any step where you would have to guess what to do
2. Any step where the success criterion is missing
3. Any error case in the gotchas section that is missing a recovery action

Claude's feedback is your first quality gate. Then run the skill: ask Claude to execute the procedure on a safe target (a staging environment, a test repository) and observe where it hesitates or asks for clarification. Every hesitation is a missing step or a missing gotcha.

If you get stuck

If you cannot identify a good candidate task: open your task manager or Slack and find the last three things you explained to a colleague. One of them is a skill waiting to be written.

If a step is genuinely variable (it changes every time based on context): that step should use a placeholder. Write {{BRANCH_NAME}} or {{TARGET_URL}} and document the substitution pattern at the top of the file.

If the skill file is growing past twenty steps: you have two skills. Find the natural boundary — usually a checkpoint where you could stop and the work would be in a stable state — and split there.

Deliverable

A .md skill file with frontmatter, a numbered procedure section, and a gotchas section with at least three entries. The success criterion: Claude can execute the procedure on a safe target without asking you a clarifying question.