/skill-progressive-disclosure-design

name: skill-progressive-disclosure-design
description: Decide how to split skill content between SKILL.md and reference files for context efficiency and reliable triggering. Use this whenever creating a new Claude skill, refactoring an existing one, or when a SKILL.md is growing past 300-400 lines. Also trigger when the user mentions "progressive disclosure", "reference files", "splitting skills", "skill bundling", "context window for skills", "SKILL.md too long", "what goes in references/", "skill structure", or expresses any uncertainty about where to put content within a skill. Use this even if the user phrases the question as a triggering problem ("how do I make my skill trigger better"), because that question is often confused with the splitting question and needs to be disentangled first.
user-invocable: true
license: MIT
compatibility: Designed for Claude or similar AI agents.
metadata:
  author: samber
  version: "1.0.1"
  openclaw:
    emoji: "👷"
    homepage: https://github.com/samber/cc-skills
allowed-tools: Read Edit Write Glob Grep Agent AskUserQuestion

Skill Progressive Disclosure Design

Each section that recommends a direction includes explicit pros and cons. The decisions in this skill are trade-offs, not rules. The model using this skill should reason from the trade-offs to the user's specific situation rather than apply rules blindly.

Triggering vs. disclosure: separate these first

Two problems get conflated and need separating before any splitting decision.

**Triggering** is whether Claude invokes the skill at all. Driven entirely by the YAML `description`. File splitting does not affect triggering. If the question is "my skill doesn't trigger reliably", do not split files, fix the description (use `run_loop.py` from the `skill-creator` skill).

**Progressive disclosure** is what loads after the skill activates. SKILL.md body always loads. `references/*` only loads when SKILL.md tells the model to read a specific file. `scripts/*` executes without loading into context at all. This is where context protection happens.

If the user is asking about splitting because of triggering issues, surface the confusion first and redirect.

Default: do not split

A monolithic SKILL.md beats a split one until proven otherwise.

Split only when at least one is true:

• SKILL.md exceeds ~400 lines and content has natural branches.
• Empirical evidence (eval transcripts) shows the model wasting context on irrelevant sections.
• Specific content is large and only needed in narrow conditions.

**Pros of staying monolithic:**

• Single context load, no router prose to maintain.
• No tool-call overhead from reading references.
• No risk of the model loading the wrong reference or skipping a needed one.
• Easier to maintain: one file, one source of truth.
• Better for highly interconnected content where context is global.
• Easier for human reviewers to read end-to-end.

**Cons of staying monolithic:**

• Every invocation pays the full token cost, even when only 10% of the content is relevant.
• Does not scale past ~500 lines without degrading the model's ability to find what matters.
• No mechanism to gate rare or niche content.
• All content must justify its always-loaded status.
• Maintenance gets harder as the file grows.

Three split axes that work

1. Variant branch

User intent selects exactly one path. SKILL.md holds the decision logic and shared workflow. Each `references/<variant>.md` holds path-specific detail.

my-skill/
├── SKILL.md               # decision tree + shared steps
└── references/
    ├── variant-a.md
    ├── variant-b.md
    └── variant-c.md

Examples of clean variants: cloud provider, database engine, framework choice, output format, language.

**Pros:**

• Each invocation loads only the matching variant; large savings when variants are big.
• Variants evolve independently, simplifying maintenance.
• Adding a new variant does not bloat existing content.
• Mental model is easy: select one path based on input.
• Maps cleanly to user intent that already mentions the variant.

**Cons:**

• Requires routing logic in SKILL.md, eating back some of the line savings.
• Cross-cutting changes touch every variant file, multiplying effort.
• Risk of treatments diverging across variants over time.
• If user intent is ambiguous, the model may load multiple variants and lose the savings.
• If variants share more than ~60% of their content, the abstraction breaks down.

2. Workflow vs. reference data

SKILL.md holds the procedure (verbs, sequence, decisions). `references/` holds lookup material queried by key.

Good reference content: schemas, error code tables, API surface listings, example galleries, configuration option matrices, design tokens.

**Pros:**

• Highest leverage of all splits: lookups are narrow, the model reads one entry.
• Natural conceptual boundary (procedure vs. data).
• Reference can grow large without affecting per-invocation cost.
• Adding new reference entries does not touch the workflow.
• Reference data can often be machine-generated and regenerated.

**Cons:**

• The model must know what to look up before reading. Pointer must encode lookup keys explicitly.
• Fails when the workflow needs to weave reference data inline rather than at discrete points.
• Splits content that is conceptually unified, harder for human readers.
• The model may miss broader context that lives only in the reference.
• Lookup data that is small (under ~50 lines total) is rarely worth splitting.

3. Depth tier (common path vs. edge cases)

SKILL.md covers the 80% case. `references/edge-cases.md` covers the rest.

The pointer must read like:

> If you see X, Y, or Z, stop and read `references/edge-cases.md` before continuing.

**Pros:**

• Common path stays minimal, fast, cheap.
• Edge cases can be exhaustive without polluting every invocation.
• Easy to extend edge-case coverage without touching the common path.
• Mirrors how experts wo