Skip to content

7.3 Writing Your First Skill

Sketch in hand, anatomy understood — build time. This lesson walks the full craft cycle: draft, test against reality, diagnose the gaps, iterate. Plus the meta-move that makes all of it faster: having the agent help write the Skill that will instruct it.

What you will learn

  • Draft a complete Skill from your sketch — with the agent as co-author.
  • Test a Skill the right way: fresh sessions, realistic tasks, verify activation.
  • Iterate using the correction ratchet until the Skill is trustworthy.

Builder principle

A Skill is done when a fresh session, given a natural request, produces your standard of work without you steering. Test exactly that, nothing easier.

Step 1 — Draft with the agent

The meta-move first: agents are excellent at drafting Skills, because Skill-writing is just structured instruction-writing — and because this conversation contains you explaining the process, which is exactly the raw material. In your project:

I want to package a process as a Claude Code skill called
[your-skill-name]. Here's the know-how, unstructured:

[Brain-dump everything: the steps as you actually do them, your
standards, what good looks like, mistakes you've seen, hard limits.
Messy is fine — that's the point.]

Draft the skill folder: SKILL.md with frontmatter (description must
say what AND when), process steps that read before they write,
rules with their reasons, hard boundaries. Propose reference files
for anything bulky, and flag any step that should be a script
instead of an instruction.

Review the draft like you'd review any diff (4.3): does the process match how you actually work? Did your reasons survive, or did they get flattened into bare rules? Is the description's "when" specific enough to match real requests?

Fix what's wrong in conversation — "step 3 is out of order; I check continuity before drafting, not after" — then have it write the files into .claude/skills/.

Step 2 — Test like it's real

Here's where most first-time Skill authors fumble: they test in the same session that wrote the Skill. That session has the entire discussion in context — of course it performs well. That's not the Skill working; that's the conversation working.

The honest protocol:

  1. /clear. Fresh window. Amnesia stranger, as designed for.
  2. Natural request, not the Skill's name: say time to prep this week's newsletter — not /newsletter-prep or "use the newsletter skill." You're testing the matching (that description sentence) as much as the instructions.
  3. Confirm activation. Watch the session: did it load the Skill? If unsure, ask — what skill(s) are you drawing on right now?
  4. Grade the output against your standard — the standard IN the Skill, not the one in your head. Divergence between those two is finding #1.

Step 3 — Diagnose and ratchet

Three failure modes, three different fixes — diagnose before editing:

Symptom Diagnosis Fix
Skill never activated Description's "when" doesn't match natural phrasing Rewrite description with the words you actually used in the request
Activated, wrong output Instructions unclear, or your standard never made it in The correction ratchet (below)
Activated, right-ish but drifts on details Standards stated without examples Add/improve reference examples — show, don't tell (6.4)

The correction ratchet is 5.2's CLAUDE.md habit, aimed at Skills:

The draft opened with "In today's newsletter" — that's explicitly
against the voice rules. Why did that happen, and update the skill
so it can't: strengthen the rule, add a counter-example, or
restructure the step. Your call — explain it.

Making the agent diagnose why its own instructions failed produces better fixes than you patching blind — it knows which phrasing it under-weighted. Two or three ratchet cycles is normal. A Skill that survives three fresh-session tests is trustworthy.

Step 4 — The finishing touches

  • Commit it. .claude/skills/ ships with the repo, like commands and CLAUDE.md — it's project infrastructure now.
  • Log it. One line in docs/decisions.md: what this Skill owns, as of when. (Your future self, auditing "why does the agent do it this way," will find the receipt.)
  • Schedule the re-look. Skills encode today's process; processes drift. When you notice yourself correcting the same Skill twice — that's the ratchet asking to run again, not evidence Skills don't work.

Full arc, zero code — notice that nothing above required any. Your brain-dump was the hard part, and you've been rehearsing it since the 6.5 narration exercise. One caution: resist perfecting the Skill before testing it. Draft rough, test honest, ratchet real gaps. Skills are grown, not born.

Treat the test protocol as what it is — an eval. The natural next step for Skills that matter: keep 2–3 canonical test requests with expected-output criteria in the Skill's folder (test-cases.md), and re-run them after any edit. You're versioning behavior, so regression-test behavior. This habit scales straight into Chapter 9's validation harnesses and 10's multi-agent QA.

Try it now

The whole cycle, today:

  1. Draft your starred Skill with the co-author prompt — real brain-dump, messy encouraged.
  2. Review, fix in conversation, write files.
  3. Honest protocol: /clear, natural request, confirm activation, grade output.
  4. Run at least two ratchet cycles on real gaps.
  5. Commit, log, and journal the before/after: what did the fresh session do on test 3 that it didn't on test 1?

Check your understanding

  • Why is testing in the authoring session a false positive, mechanically? (Chapter 2 terms.)
  • What are you testing with a natural phrasing request rather than the Skill's name?
  • Match the three failure modes to their fixes from memory.
  • Why does the ratchet ask the agent to diagnose before fixing?