progressive-disclosure

Progressive Disclosure in Skill Content

A skill is consumed by a model with finite attention. Put the highest-signal content first, let depth come later. Length without structure is noise.

When to Use

• Writing a new SKILL.md body
• Refactoring a skill that's grown bloated
• Splitting a monster skill into focused ones
• Reviewing skills for publication quality

The Shape of a Good Skill

Target ≈ 150-300 lines. Order sections from most-essential to least:

1. ---frontmatter---
2. One-line bolded summary
3. When to Use (bullet list)
4. Core concept (≤ 5 sentences)
5. Minimal example
6. Deeper patterns / variations
7. Anti-patterns
8. Best Practices (numbered list)

The model reads top-down. Every section should earn its place.

Section-by-Section

The Opening

# Skill Title

**One sentence that captures the whole skill's value proposition.**

If the reader stops after this line, they still learned something.

"When to Use"

A bullet list of 3-6 situations. Concrete, not abstract:

## When to Use

- Your agent needs to remember user preferences across sessions
- You're replacing "stuff everything into system prompt" with structured state
- You're building coding agents that learn about a codebase over time

Bad:

• "For when you need memory." (abstract, unhelpful)

Core Concept

5 sentences. Maximum. Explain the mental model:

The Memory tool gives Claude a file system. Claude issues read/write ops;
your app executes them on real storage. Per-user roots isolate data.
Unlike RAG, the agent curates what's worth remembering. Unlike context-stuffing,
state persists without growing every message.

If you need 3 paragraphs, you probably have two concepts and should split.

Minimal Example

The fewest lines of code that demonstrate the thing:

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  tools: [{ type: "memory_20250818", name: "memory" }],
  messages: [...],
});