Progressive Disclosure System Architecture in Claude Skills: A Two-Tier Design

The progressive disclosure system architecture uses a lightweight Tier 1 SKILL.md file combined with on-demand Tier 2 reference files to reduce token consumption by 40-50% while maintaining access to deep technical knowledge.

The Jeffallan/claude-skills repository implements a progressive disclosure system architecture that solves the token limit problem faced by LLM-based coding assistants. This design pattern keeps initial prompts small and efficient, loading heavy technical documentation only when specific topics are triggered by user intent.

Core Components of the Progressive Disclosure Architecture

The architecture is explicitly defined in CLAUDE.md (lines 91-106) and CONTRIBUTING.md (lines 82-108) as a strict two-tier system that separates routing logic from detailed content.

Tier 1: SKILL.md (The Routing Layer)

Every skill begins with a concise SKILL.md file stored at skills/<skill-name>/SKILL.md. This file typically contains 80-100 lines and includes:

• The skill's role definition and trigger conditions
• A 5-step workflow for execution
• Constraints and limitations
• A routing table that maps topics to reference files

The routing table uses a markdown table format with three columns: Topic, Reference, and Load When. This table determines which Tier 2 files get injected into the context based on keyword matching.

Tier 2: Reference Files (The Knowledge Layer)

Detailed technical content lives in the skills/<skill-name>/references/ directory. Each file contains 100-600 lines of:

• Full code examples and implementation patterns
• Edge-case discussions and anti-patterns
• Style guides (Google, NumPy, Sphinx docstrings, etc.)
• Framework-specific documentation

These files remain unloaded until the routing table detects a match in the user's request, significantly reducing the initial token payload.

How the Progressive Disclosure System Works

According to the source code in CLAUDE.md, the system follows a five-step execution flow:

1. Skill Activation – The user's request triggers a skill based on trigger-only descriptions in the SKILL.md frontmatter.
2. Routing Table Lookup – The system scans the markdown table inside SKILL.md to identify relevant topics.
3. Context-Aware Loading – When keywords match the "Load When" conditions, the associated reference file is pulled into the prompt.
4. Execution – The LLM processes the 5-step workflow using the newly available detailed guidance.
5. Result Delivery – The user receives a concise answer backed by comprehensive documentation that wasn't present in the initial context.

The validation logic in scripts/validate-skills.py enforces this pattern by checking for the presence of references/ folders, valid routing tables, and adherence to size limits for Tier 1 files.

Implementation Example: Code Documenter Skill

The Code Documenter skill demonstrates this architecture in practice. Its SKILL.md contains a routing table like this:

## Reference Guide

| Topic               | Reference                         | Load When                              |
|---------------------|-----------------------------------|----------------------------------------|
| Python Docstrings   | `references/python-docstrings.md`| Google, NumPy, Sphinx styles           |
| TypeScript JSDoc    | `references/typescript-jsdoc.md`  | JSDoc patterns, TypeScript             |
| FastAPI API Docs    | `references/api-docs-fastapi.md` | Python API documentation               |

When a user mentions "Google style docstrings," the system loads skills/code-documenter/references/python-docstrings.md, which contains detailed examples:

def fetch_data(url: str) -> dict:
    """Fetches JSON data from a URL.

    Args:
        url: The URL to request.

    Returns:
        A dictionary representing the parsed JSON response.

    Raises:
        requests.HTTPError: If the request fails.
    """
    ...

The runtime pseudocode in the repository shows how this loading occurs:

# Executed by the Claude plugin context-injection logic

if "docstring" in user_intent and "google style" in user_intent:
    reference = load_file("skills/code-documenter/references/python-docstrings.md")
    answer = generate_docstring(code_snippet, style="google", reference=reference)

Benefits of the Two-Tier Architecture

Token Efficiency – Only the lean SKILL.md (~80-100 lines) remains in the permanent context. Heavy reference files (100-600 lines each) are excluded until explicitly needed, cutting token usage by roughly half.

Modular Maintainability – Topic-specific knowledge is isolated in individual files. Updating Python docstring conventions requires editing only references/python-docstrings.md without touching the core skill logic.

Scalable Knowledge Base – Adding new capabilities involves creating a markdown file in references/ and adding one row to the routing table. The scripts/validate-skills.py automation ensures new skills comply with these architectural constraints.

Summary

• The progressive disclosure system architecture uses a two-tier design defined in CLAUDE.md and CONTRIBUTING.md.
• Tier 1 (SKILL.md) provides routing tables and workflows in ~80-100 lines.
• Tier 2 (references/ files) contains detailed technical content loaded on demand.
• This approach reduces token consumption by 40-50% compared to monolithic prompt designs.
• The system is enforced by scripts/validate-skills.py, ensuring all skills follow the routing table pattern.

Frequently Asked Questions

How does the routing table determine which reference files to load?

The routing table in SKILL.md contains a "Load When" column that specifies keywords or contextual triggers. When the Claude plugin detects these terms in the user intent, it executes the loading logic to pull the associated file from skills/<skill-name>/references/ into the active context.

What is the typical file size difference between Tier 1 and Tier 2?

According to the architecture specification, Tier 1 SKILL.md files are strictly kept to 80-100 lines, while Tier 2 reference files range from 100-600 lines each. This size differential ensures that the initial prompt remains lightweight while allowing for extensive technical depth when needed.

Can a skill function without reference files?

Yes, but it would violate the progressive disclosure pattern enforced by scripts/validate-skills.py. The validation script checks that each skill has a references/ folder and a valid routing table. Skills without reference files lose the token efficiency benefits and modular maintenance advantages of the architecture.

Where is the progressive disclosure architecture documented?

The canonical specification lives in CLAUDE.md (lines 91-106), with implementation guidelines in CONTRIBUTING.md (lines 82-108). The Code Documenter skill at skills/code-documenter/SKILL.md serves as the reference implementation showing the routing table structure and corresponding reference files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}