Skill Planner
What this is. The worksheet you fill in before you write a single line of SKILL.md YAML. Skills fail in predictable ways when authors start by typing YAML and figure out the shape as they go; filling this page first forces the thinking to happen before the typing.
How to use. Print one copy per skill you are considering. Work top to bottom. When every section has a real answer (not a placeholder), you are ready to open Lesson 7.3’s RECIPE walkthrough and author the actual file.
The load-bearing insight of Lesson 7.3 — keep this in view while you plan.
The description field is the classifier. The agent reads it to decide whether to fire the skill. Every word in that sentence matters.
Section 1 — Name and one-sentence purpose
Skill name (kebab-case, folder-safe)
This becomes the folder name under ~/.claude/skills/ or <project>/.claude/skills/. Short, specific, and boring beats clever.
What this skill does, in one sentence
Plain English. Write the sentence you’d say to a roommate, not the description the agent will see. That comes later.
The repetition count
Lesson 7.1’s three-part threshold test: this prompt has been run at least three times, in the same shape, on the same kind of input. If the answer is “not yet,” stop — this should be a saved prompt, not a skill.
Run 1 date: ________________ Run 2 date: ________________ Run 3 date: ________________
If I could not fill in three real dates: I am not ready to build this skill. The prompt goes in my saved-prompts folder and I revisit in two weeks.
Section 2 — Description (the classifier)
First-draft description
Aim for two to four sentences. The first names what the skill does. The second names when the agent should fire it. The third (optional) names when not to fire it.
Three-failure-mode self-check
Before tuning. Read your draft aloud and tick whichever apply. A “yes” on any of them means rewrite before installing.
Vague
Could this description fire on workflows I did not build this skill for? If “yes,” narrow the when. □ Yes □ No
Overfit
Does the description name a specific sender, filename, date, or phrase that would make the skill miss near-identical work? If “yes,” broaden the what. □ Yes □ No
Triggerless
Does the description describe only what the skill does and never name when to fire it? If “yes,” add the trigger sentence. □ Yes □ No
Descriptive + inclusive + exclusive rewrite
Apply the Lesson 7.3 fix: descriptive (names what it does), inclusive (names the triggering shape positively), exclusive (names one or two things it is explicitly not for).
Section 3 — Inputs
What the skill reads to do its work
Name every required input, whether the agent infers it from the request, extracts it from a file, or asks the user. “Email thread” is an input. “User’s voice template” is an input if you load one. “Today’s date” is an input if the skill behaves differently on weekdays.
What the skill is not allowed to read
Write the fence. “The email triage skill does not read threads outside the agent-access label.” This sentence later becomes the scope line in the body.
Section 4 — Procedure (4–7 numbered steps)
The body of the skill, step by step
The procedure section of SKILL.md. Write it in imperative voice: “Read the thread. Identify the sender’s ask. Draft a three-paragraph reply.” Keep it under seven steps — if it needs more, the skill is doing too much.
Section 5 — Output contract
What the skill is required to produce
Name the shape. “A three-bullet summary, each bullet under 20 words.” “A draft reply in the user’s voice, saved to Drafts, never sent.” Future-you will audit the skill against this contract — make it checkable.
Where the output goes
File path, Drafts folder, return-in-chat, stdout — be specific. The delivery is part of the contract.
What the skill is not allowed to produce
The “drafts, not sends” carve-out lives here. Also: “no auto-commit,” “no auto-share,” “no auto-RSVP.”
Section 6 — Failure modes (at least three)
The failure modes section of the body. Write the three most likely ways this skill will misfire. For each, name what future-you should look for in the trace. A skill without an explicit failure-modes section is a skill that will fail silently.
Failure mode 1
Failure mode 2
Failure mode 3
Section 7 — Ready-to-author checklist
- □ Every section above has a real answer. No “TBD,” no placeholders.
- □ The three-failure-mode self-check on Section 2 came back clean (no “yes” boxes unaddressed).
- □ The description includes the descriptive + inclusive + exclusive triple.
- □ The procedure is seven steps or fewer.
- □ The output contract is checkable — I can look at a single output and say “that matches” or “it doesn’t.”
- □ At least three failure modes are named, each with a trace signal.
- □ The three-part threshold test passed (Section 1 — three real run dates, not guesses).
When all seven boxes are ticked, open Lesson 7.3’s RECIPE walkthrough and translate this page into SKILL.md.
Worked example (reference only — use your own values)
Skill name: email-thread-summarizer
One sentence: Produces a three-bullet summary of a work email
thread, each bullet under 20 words, for the user
to scan before replying.
Repetition threshold: Run 1: 2026-03-14 (bike-shop vendor thread)
Run 2: 2026-03-28 (sibling sign-off thread)
Run 3: 2026-04-05 (research-trip logistics thread)
→ three runs confirmed, skill is warranted.
Description (D+I+E): Summarizes a multi-message email thread into
three bullets under 20 words each. Use when the
user asks to “summarize,” “recap,” or “give
me the TL;DR of” an email thread. Do NOT use for
single messages, for non-email text (articles,
PDFs, notes), or for producing replies — there
is a separate skill for replies.
Inputs (required): 1. The email thread (all messages, in order)
2. The user’s named ask (“summarize,” etc.)
Inputs (fenced out): Threads outside the `agent-access` label.
Messages the user has tagged `private`.
Procedure: 1. Read the full thread top-to-bottom.
2. Identify the original ask and the latest state.
3. Name any open questions not yet resolved.
4. Produce three bullets, each under 20 words:
a. what the thread is about
b. where it currently stands
c. what is still open or needs a decision
Output contract: Exactly three bullets. Each under 20 words.
Delivered inline in chat.
Not allowed: Do not draft a reply. Do not mark the thread
read. Do not change the thread’s label.
Failure modes: 1. Produces four bullets when the thread is
complex. — Trace signal: bullet count.
2. Invents a resolution that is not in the
thread. — Trace signal: claim without
a message to cite.
3. Summarizes a forwarded newsletter as if it
were a conversation. — Trace signal:
“the thread discusses” with a single sender.
The planner is the thinking. The YAML is the typing. Do the thinking first.