Design Pattern

Progressive Disclosure Design Pattern

Source: ~/system/specs/agentic-os-pillar4-skills-audit-2026-05-04.md (§5)
MC: #99131 | #99176
Date: 2026-05-05

Derived from ~/.claude/skills/skill-creator/SKILL.md ("context window is a public good"). This section codifies what is implicit in the canonical reference — it does not invent a new framework.

Definition

Progressive disclosure for skills means that skill content is loaded in tiers based on actual need:

• Tier 1 (frontmatter — always-loaded): Every time a Claude session starts, all SKILL.md frontmatter description fields are loaded to determine which skills to activate. Frontmatter is the highest-cost content per byte because it loads regardless of usage.
• Tier 2 (SKILL.md body — loaded on trigger): After a skill matches its trigger condition, the full SKILL.md body loads. This is the decision-making and branching layer.
• Tier 3 (references/ — loaded on demand): Content in references/ is loaded explicitly via Read <path> only when the agent reaches a branch that needs it. Scripts in scripts/ are invoked without being loaded into context.

The principle: never load content that is not needed for the current branch of execution.

L0–L3 Rubric

This rubric is used for the progressive_disclosure_score column in the inventory CSV.

Distribution in current corpus:

• L0: 32 skills (40.5%) — monolithic, no references
• L1: 38 skills (48.1%) — body > 200 LOC or proactive refs
• L2: 2 skills (2.5%) — sentry-skill-scanner, task-splitter
• L3: 0 skills (0%) — no skill fully meets all L3 criteria

Note: skill-creator comes closest to L3 intent but is 362 LOC (exceeds the 60-line body target).

Reference Exemplar

The canonical reference for the L3 pattern is ~/.claude/skills/skill-creator/.

This skill demonstrates:

• references/output-patterns.md — loaded only when generating skill output
• references/workflows.md — loaded only for the workflow design step
• Clear "when to Read" callouts in the body
• Frontmatter description that covers all trigger cases without bloat

The canonical pattern from skill-creator states:

"Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them."

A true L3 implementation would reduce this further to ≤60-line skeleton with all procedural content in references/.

Anti-Pattern Catalog

All 9 anti-patterns documented (minimum 8 required per spec):

Three-Tier Load Model

The canonical Anthropic pattern (derived from skill-creator/SKILL.md):

Tier 1 — Always-Loaded (frontmatter only)

• Content: trigger condition + one-paragraph overview + when-to-use
• Location: YAML description: field
• Target: ≤ 60 lines total frontmatter / ≤ 1.5K tokens
• Cost: paid on every session, regardless of whether skill fires
• Rule: Never put procedural steps, code examples, or reference tables here

Tier 2 — Loaded on Trigger (SKILL.md body)

• Content: process steps, branching logic, tool whitelist, output contract
• Location: SKILL.md body (everything after frontmatter ---)
• Target: 60-200 lines / token budget ≤ 5K
• Cost: paid when skill trigger matches
• Rule: Include branch decision table; link to Tier 3 files explicitly

Tier 3 — On-Demand (references/ and scripts/)

• Content: detailed procedures, examples, anti-pattern tables, worked code samples, branch-specific rules
• Location: references/<branch>.md, scripts/<action>.sh
• Target: unbounded; each file should be independently useful
• Cost: paid only when the agent reads the file on a specific branch
• Rule: Agent must see the file reference in Tier 2 SKILL.md body with explicit "when to read" instruction

Canonical Skill Skeleton Template

---
name: <kebab-case-name>
description: Use when <concrete trigger>. Does <one-line outcome>.
argument-hint: <stdin-arg>
---

# <name>

## 1. Preconditions (<= 30 lines)
- Hard checks. Abort fast. Cite the hook that enforces if any.

## 2. Branch decision (<= 30 lines)
Pick the procedure, then load it:

| Condition | Procedure |
|---|---|
| <condition-A> | Read `./references/<branch-a>.md` |
| <condition-B> | Read `./references/<branch-b>.md` |

## 3. Sub-agent dispatch contract (<= 40 lines)
- Model tier (Haiku/Sonnet/Opus + rationale)
- Tool whitelist
- Brief path: `./references/<role>-brief.md`
- Output contract (path + format)

## 4. Closure (<= 30 lines)
- mc.js submission shape
- Memory write rule (cite owning skill; do NOT reimplement)

# Body MUST stay under 200 lines.
# Anything longer goes into references/<branch>.md.

This template will be promoted to ~/system/specs/skill-skeleton-canonical.md as a separate Skillforge step.

← Top-20 Priority | PoC Analysis →