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

> Discover the progressive disclosure system architecture in Claude Skills. A two-tier design reduces token usage by 40-50% while preserving access to deep knowledge.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: architecture
- Published: 2026-02-16

---

**The progressive disclosure system architecture uses a lightweight Tier 1 [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) (lines 91-106) and [`CONTRIBUTING.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) frontmatter.
2. **Routing Table Lookup** – The system scans the markdown table inside [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) contains a routing table like this:

```markdown

## 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`](https://github.com/Jeffallan/claude-skills/blob/main/skills/code-documenter/references/python-docstrings.md), which contains detailed examples:

```python
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:

```python

# 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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) and [`CONTRIBUTING.md`](https://github.com/Jeffallan/claude-skills/blob/main/CONTRIBUTING.md).
- **Tier 1** ([`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) (lines 91-106), with implementation guidelines in [`CONTRIBUTING.md`](https://github.com/Jeffallan/claude-skills/blob/main/CONTRIBUTING.md) (lines 82-108). The **Code Documenter** skill at [`skills/code-documenter/SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/skills/code-documenter/SKILL.md) serves as the reference implementation showing the routing table structure and corresponding reference files.