How to Write Skills That Hit Like Adderall

The Three-Layer Loading Model

Skills load progressively to stay efficient:

1. Layer 1 — Metadata (~100 words): The name + description from YAML frontmatter. Always in Claude's context. This is what triggers the skill.
2. Layer 2 — SKILL.md body (<500 lines ideal): Loaded when the skill triggers. This is the main instruction set.
3. Layer 3 — Bundled resources (unlimited): Scripts, references, assets. Loaded on-demand when the SKILL.md says to load them.

The implication: your SKILL.md needs to be dense, precise, and under 500 lines. If you're going longer, push detail into references/ files and point to them.

Phase 1: Capture the Intent

Before writing a single line of markdown, answer these questions.

The Four Questions

1. What does this skill enable Claude to do? Be specific.
2. When should it trigger? List the user phrases, keywords, and contexts.
3. What's the expected output? File type? Format? Structure? Length? Quality bar?
4. What are the failure modes? What does a bad output look like?

The Edge Case Interview

• What inputs could break this?
• What ambiguous requests could lead the skill astray?
• What does "done" look like for different complexity levels?
• Are there dependencies?
• What does the user probably not know to ask for, but would love to have?

Phase 2: Write the Description (Most Important Part)

The description field is the sole mechanism that determines whether Claude uses your skill. If the description is weak, your brilliant instructions never get read.

Description Anatomy

1. What it does (1 sentence): Clear, concrete capability statement.
2. When to trigger (2-4 sentences): Specific phrases, keywords, contexts. Be pushy.
3. When NOT to trigger (1 sentence, optional): Disambiguate from similar skills.

The Pushy Principle

Claude errs on the side of not using skills. Include:

• Obvious triggers ("make a chart")
• Synonyms and casual language ("graph this", "visualize", "show me")
• Implicit triggers ("uploaded a CSV and wants insights")
• Edge cases you want captured

Phase 3: Write the SKILL.md Body

The 10 Commandments

1. Lead with WHY, not MUST. The model generalizes from understanding, not blind rules.
2. Be opinionated, not wishy-washy. Skills exist to provide expertise.
3. Use the imperative mood. Talk like a senior colleague briefing a task.
4. Show, don't just tell. Every abstract instruction needs a concrete example inline.
5. Anticipate failure modes. Preempt Claude's first-attempt mistakes.
6. Keep it under 500 lines. Push detail into references/.
7. Include decision trees for branching logic. Make branching explicit.
8. Bundle scripts for deterministic work. Let Claude focus on creative/analytical work.
9. Define what "done" looks like. Clear finish line and completion checklist.
10. Write for a million runs, not one. General principles with specific illustrations.

Phase 4: Quality Multipliers

The "Theory of Mind" Pattern

Help Claude understand the user's mental model, not just the task.

The "Anti-Slop" Pattern

Name and shame generic, low-effort patterns. Surprisingly effective.

The "Escape Hatch" Pattern

Give Claude permission to deviate when appropriate. Rigid skills produce brittle outputs.

The "Progressive Enhancement" Pattern

1. Get core content right (accuracy > aesthetics)
2. Structure for readability
3. Polish language
4. Add delightful details

Phase 5: Validate & Iterate

Write 2-3 realistic test prompts. Check:

1. Did the skill trigger?
2. Did the output match the quality bar?
3. Did Claude follow the workflow?
4. Did it handle ambiguity well?

Common Mistakes