Writing Your First Skill
A step-by-step method for turning a repeated task into a clean, reusable Skill that Claude applies consistently.
Start from a real repeated task
The best first Skill comes from work you already do often and want done the same way every time. Do not invent a task to practice on. Pick something concrete, such as drafting release notes, reviewing pull request descriptions, or triaging inbound messages, where you can point to good and bad examples from real history.
The five parts to write
Build the Skill in this order, because each part depends on the one before it.
- Name and trigger. Give the Skill a short, specific name and state plainly when Claude should use it. "Use this when drafting a customer-facing release note" is a usable trigger; "use for writing" is not.
- Procedure. Write the steps Claude should follow, in order. Be explicit about what to read first, what to produce, and what to check before finishing.
- Constraints. List the hard rules. Keep each one detectable and unambiguous, such as "never promise a delivery date" or "always include a rollback note."
- Examples. Include one or two complete examples of correct output, and ideally one bad example labeled with why it fails.
- Escalation. Say what Claude should do when it is unsure or hits a case the Skill does not cover: stop and ask rather than guess.
Keep it lean
A Skill is not a knowledge dump. Include only what changes Claude's behavior on this task. If a sentence would not alter the output, cut it. Long, padded Skills are harder for Claude to apply reliably and harder for you to maintain.
Test before you trust
Once written, run the Skill against three to five real cases, including at least one awkward one. Compare the output to what a good person would have produced. Where it falls short, the fix is almost always a missing constraint, a vague step, or an absent example, not a longer instruction. Adjust the Skill and run the same cases again.
What good looks like
Your first Skill is short enough to read in a minute, names its trigger clearly, and produces output on your real test cases that needs only light editing. A teammate could read it and predict how Claude will behave.
Common mistakes
- Writing the constraints as soft suggestions ("try to keep it brief") instead of firm, checkable rules.
- Skipping the test cases and assuming the Skill works because it reads well.
- Cramming a second, unrelated task into the same Skill, which blurs its trigger and weakens both.