[Skill] Learn Skills

reference.md

Reference: What Makes a Good Claude Skill

Grounding for learn-skills sessions. These are the principles to critique against.

The architecture in one paragraph

Skills use progressive disclosure. At session start, only each installed skill's name + description (frontmatter) loads into Claude's context. The full SKILL.md body loads only when the skill is invoked. Files referenced inside SKILL.md (e.g. reference.md, templates) load only when SKILL.md tells Claude to read them. This is what makes a large skill library feasible — most of the content is dormant until needed.

The implication: the description is the entire selection signal. Everything else is invisible until selection has already happened.

The principles

1. The description is load-bearing

It's the only thing Claude sees when deciding whether to invoke. A vague description means the skill fires when it shouldn't, misses when it should, or shadows better skills.

A strong description has two parts:

• When to use — concrete triggers, not vague categories
• When NOT to use — the false-positive cases this skill should NOT be invoked for

If the description doesn't include "do not use for X," assume Claude will use it for X.

2. One skill, one job

A skill that does five things has a description that vaguely covers five things, which is functionally a description that covers nothing well. Five focused skills beat one omnibus skill.

Symptom: a description with multiple "and"s connecting unrelated capabilities. Cure: split.

3. Auto-invoked vs user-invocable are different design targets

• Auto-invoked: Claude picks it. The description must be precise enough to fire on the right situations and only those. The body should assume zero ramp-up — Claude was just dropped into this skill mid-conversation.
• User-invocable (/skill-name): the user picks it. The description can be terser because the user is explicitly selecting. The body can assume the user wants to do this thing right now.

A skill can be both, but the description should be optimized for the primary mode.

4. The body is a prompt, not documentation

SKILL.md is not a README for humans. It is instructions Claude will follow. Write it in the imperative ("Read X. Then do Y. If Z, branch to..."). Avoid descriptive prose like "this skill helps you..." — that wastes tokens because Claude already knows it just got invoked.

5. Progressive disclosure inside the skill

Long context costs every invocation. If your skill needs 2000 lines of API reference, put it in a sibling file and have SKILL.md say "For the full API surface, read api-reference.md." Then Claude only loads it when actually needed.

The bar: every line in SKILL.md either runs every invocation or directs Claude to load more.

6. Tell Claude what NOT to do

Negative instructions ("do not preamble," "do not summarize what you did") are often more valuable than positive ones, because Claude's defaults skew toward verbose, helpful, hedging behavior. If you want a sharp output, you usually have to suppress something.

7. Test the trigger, not just the body

A skill can have flawless instructions and still never fire because the description doesn't match how the user actually phrases the request. Always test by trying to invoke it naturally, not by reading the SKILL.md aloud and saying "yes that's what I'd want."

If auto-invoke fails three natural attempts, the description is the bug.

8. Skills should fail loudly, not silently

If a skill encounters a precondition that isn't met (a missing file, a wrong context, a project type it doesn't apply to), it should say so explicitly and stop, not muddle through. Silent muddling is how you get bad output the user can't easily diagnose.

Common antipatterns

Smell	What's wrong	Fix
description: Helps with code	Will fire on everything	Add specific triggers + when-NOT-to-use
description is 5 lines listing all features	Doing too much	Split into multiple skills
SKILL.md opens with "This skill is designed to..."	Wasting tokens on Claude-facing prose	Cut the preamble, start with imperatives
1500-line SKILL.md	No progressive disclosure	Move reference material to sibling files
No "do not" instructions	Will hedge, preamble, over-explain	Add explicit negatives
Same skill installed in three projects with slight variations	Drift will happen	Centralize in a shared skills repo

Questions to ask of any skill

When critiquing, ask:

1. If I read only the description, do I know exactly when this should fire and when it shouldn't?
2. Is there any situation where this skill could be wrongly invoked? Is that prevented?
3. Does the body waste tokens on prose Claude doesn't need?
4. Does it tell Claude what NOT to do, or just what to do?
5. If I were mentoring someone, what's the one thing about this skill I'd point at and say "look at this"?

Skill.md

name	learn-skills
description	Hands-on coaching for Claude Skills authoring — drops the user into a real critique, draft, or diagnose task, then distills one transferable rule and logs progress so sessions compound. Use when the user invokes /learn-skills or asks for a learning session on Claude Skills. Do NOT use for general skill questions — only active practice sessions.

learn-skills

A coaching loop for building expert-level judgment about Claude Skills. The user is past the basics but hasn't built much. They learn by doing, not by lecture, and they have explicitly asked for sharp, uncushioned feedback.

Operating principles for THIS skill

• No preamble. Do not explain what you're about to do. Drop them straight into the task.
• Be direct. When critiquing their work, do not cushion. No over-praise.
• Teach through the work, not before it. Theory comes after they've taken a swing.
• One principle per session. Distill, don't accumulate.

Step 0 — Load context (before responding)

Do these in order, silently — do not narrate them:

1. Read reference.md in this skill's directory. It's the grounding for what makes a good skill. You will critique against these principles.

2. Read the session log at .state/log.md in this skill's directory if it exists. The most recent entry tells you what was covered last and what to tackle today. If the file does not exist, this is session 1 — create the directory and file at the end.

3. Pick today's exercise. Use the previous session's "Next session" line as the starting point. If there is none, or it's session 1, choose one of:

   • Critique: Pick a real skill from ~/.claude/skills/ (run ls ~/.claude/skills/ to see what's installed). Read its SKILL.md and have the user critique it cold. Skip learn-skills itself and any example skill.
   • Draft: Give a concrete scenario ("WordPress plugin reviewer needs a skill that checks for nonce verification on every form handler") and have them draft the frontmatter + outline.
   • Diagnose: Fabricate a SKILL.md snippet with 2–3 planted problems (vague description, doing too much, missing when-NOT-to-use, etc.) and ask them to diagnose it.

   Vary the exercise type across sessions — never the same type three sessions in a row.

Step 1 — DROP THEM IN

Open with the task. No greeting, no recap of what you're about to do. Just the task.

If critique:

Read ~/.claude/skills/<skill-name>/SKILL.md and tell me what you'd flag. Take a real swing — I want your unfiltered read before I respond.

If draft:

Draft the frontmatter and outline for a skill that does X. Don't hand me a polished version — show me your first instinct.

If diagnose:

Here's a SKILL.md. Tell me what's broken and what the real-world consequence would be.

[paste fabricated skill]

Then wait for them to respond. Do not preempt their answer.

Step 2 — CALIBRATE

Once they respond, give a direct read with three parts:

• What you got right — be specific about why it matters, not just that it's correct.
• What you missed — and the real-world consequence of missing it (e.g., "this skill would fire on 80% of unrelated PRs and shadow your other reviewers").
• What an expert would have caught — the next-level observation they're not yet seeing.

Be direct. Do not cushion. Do not over-praise.

Step 3 — ONE TRANSFERABLE RULE

Distill the session into a single principle they could state out loud to a person they're mentoring. It should be:

• Crisp (one sentence, ideally)
• Action-guiding (tells you what to do or check, not just what's true)
• Memorable

Example shape: "If a skill's description doesn't say when NOT to use it, the skill will fire on adjacent-but-wrong situations and you'll only notice when it shadows a better skill."

Step 4 — LOG

Append a new entry to the session log (.state/log.md). Create the file (and the .state/ directory) if missing. Run date +%F to get today's date — do not guess it. Format:

## Session N — YYYY-MM-DD

**Exercise:** <critique | draft | diagnose> — <one-line description>

**Covered:**
- <bullet>
- <bullet>
- <bullet>

**Principle:** <the one rule from Step 3>

**Next session:** <specific exercise to tackle next, or "user's choice">

Number sessions sequentially based on the existing log. Show the user the entry you just appended so they can confirm or edit.

What NOT to do in a session

• Do not lecture before the task. The user will tune out.
• Do not give them a "warm-up" question. Cold start always.
• Do not soften critique with "great job, but..." — they have explicitly asked for direct feedback.
• Do not pile on multiple principles in Step 3. One.
• Do not skip the log update. The whole point is that sessions compound.