Status	Last updated	Parent	Read before this
complete	2026-04-30	none	none

Progressive Disclosure

Current state

Skill content loads in three levels, scaled to need.

Level 1: Metadata (~100 tokens per skill). Loaded at startup for all installed skills. Just the YAML frontmatter — name and description. Claude uses this to decide which skill matches the current task. Total cost across dozens of skills is negligible.

Level 2: SKILL.md (often a few hundred lines). Loaded only when a skill is invoked. Contains the procedure, decision points, and references to supporting files. Skills aim to stay under 500 lines; longer ones get split into procedures under a procedures/ subfolder.

Level 3: Supporting files (any size). Loaded only when explicitly referenced during execution. Lives in references/, examples/, scripts/, procedures/ subfolders of the skill. Pattern catalogues, example outputs, helper scripts, longer procedure documents — anything that's needed sometimes but not always.

The pattern extends to subagents and the Concept - Companion Skill Pattern. A subagent's instructions can themselves use progressive disclosure — the subagent's main prompt is short, with references to detailed pattern files loaded only when the subagent's work needs them.

Rationale

Without progressive disclosure, the system can't exist at this scale. Loading every skill's full SKILL.md at startup would consume tens of thousands of tokens before any work began — and devwork-skills has dozens of skills. The metadata-only startup keeps the orchestrator's context lean enough to actually do work.

The three-level split also makes skills easier to write. Authors don't have to choose between "comprehensive" and "lean" — they can be comprehensive in supporting files and lean in the SKILL.md, knowing the supporting files only load when needed. Pattern catalogues can grow to hundreds of lines without bloating the runtime cost.

The description field doing double duty — both telling Claude when to use the skill and serving as a lightweight index — is the trick that makes the metadata layer work. A precise description means the skill is discoverable without loading anything; a vague description means the skill is invisible until someone explicitly invokes it.

There's a tension worth naming: progressive disclosure relies on Claude's ability to read metadata and recognise the right skill. If the descriptions are unclear or overlapping, the system fails silently — Claude picks the wrong skill or no skill, and the work goes ahead without the procedure that should have guided it. Skill description quality is a load-bearing concern.

Open questions

None.