# How to Implement Agent Skills with the Progressive Disclosure Pattern

> Learn to implement Agent Skills using progressive disclosure. This pattern efficiently loads skills in layers, keeping prompts compact for complex, multi-step AI workflows.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-07-26

---

**The progressive disclosure pattern loads Agent Skills in three layers—metadata, core flow, and implementation details—only when needed, keeping system prompts compact while enabling complex multi-step workflows.**

The **bojieli/ai-agent-book** repository demonstrates a modular approach to extending LLM-driven Agents without overloading the context window. By implementing **Agent Skills with the progressive disclosure pattern**, you can provide domain-specific capabilities that load incrementally, ensuring optimal token usage while maintaining the ability to execute sophisticated tasks like generating PowerPoint presentations from research papers.

## What Are Agent Skills and Progressive Disclosure?

Agent Skills are modular capabilities that give an LLM-driven Agent domain-specific knowledge without permanently bloating the system prompt. The **progressive disclosure** pattern ensures the Agent only loads the full definition of a Skill when it determines the current task actually requires it.

This approach keeps the initial prompt compact by injecting only a thin Skill catalog containing names and descriptions at startup. When the Agent recognizes a need for specific expertise, it dynamically retrieves the complete workflow documentation and implementation scripts on demand.

## The Three-Layer Skill Architecture

The implementation follows a strict three-layer hierarchy that controls information exposure:

### Layer 1 – Metadata (Skill Catalog)

The first layer consists of **metadata** front-matter containing only the `name` and `description` of each Skill, consuming approximately a few hundred tokens. The function `scan_skill_catalog()` scans these entries and inserts them into the system prompt at initialization, as referenced in [`chapter2/agent-skills-ppt/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter2/agent-skills-ppt/README.md).

### Layer 2 – Core Flow (SKILL.md)

When the Agent decides a specific Skill is required, it invokes `read_skill("<skill>")` to retrieve the **core flow** document. This Layer 2 file, typically named [`SKILL.md`](https://github.com/bojieli/ai-agent-book/blob/main/SKILL.md), describes the workflow, sub-steps, and tool contracts. For example, [`skills/pptx/SKILL.md`](https://github.com/bojieli/ai-agent-book/blob/main/skills/pptx/SKILL.md) contains the procedural steps for PowerPoint generation.

### Layer 3 – Implementation Details and Scripts

For fine-grained execution, the Agent accesses **implementation details** through `read_skill_file("<skill>", "<path>")` or executes bundled code via `run_skill_script("<skill>", "<script>", payload)`. This layer includes files like [`reference.md`](https://github.com/bojieli/ai-agent-book/blob/main/reference.md) (covering layout, color schemes, and python-pptx notes) and executable scripts such as [`skills/pptx/scripts/generate_pptx.py`](https://github.com/bojieli/ai-agent-book/blob/main/skills/pptx/scripts/generate_pptx.py).

## How the Progressive Disclosure Flow Works

The runtime execution follows a controlled loading sequence:

1. **Startup Phase**: The Agent receives a thin Skill catalog containing only Layer 1 metadata. No heavy knowledge about PowerPoint construction resides in the context yet.

2. **Decision Phase**: During the reasoning loop, the Agent recognizes that the task requires the `pptx` Skill (e.g., "Create a slide deck from this paper"). It invokes `read_skill("pptx")`, which returns the complete [`SKILL.md`](https://github.com/bojieli/ai-agent-book/blob/main/SKILL.md) file and brings the core workflow into context.

3. **Execution Phase**: If the Agent requires specific implementation details, it calls `read_skill_file("pptx", "reference.md")` to load layout specifications, or executes `run_skill_script("pptx", "generate_pptx.py", payload)` to run the bundled generator. This produces a real `.pptx` file using the **python-pptx** library.

Because each layer fetches only when required, the overall token usage remains minimal, KV-Cache reuse is maximized, and the Agent expands its capabilities without risking prompt overflow.

## Implementation Walkthrough

The repository provides a complete working example in `chapter2/agent-skills-ppt/`. To run the demonstration:

```bash

# 1️⃣ Install dependencies

pip install -r requirements.txt

# 2️⃣ Run the demo (online mode – calls OpenAI)

python demo.py            # loads layers on demand, generates output/presentation.pptx

# 3️⃣ Run the demo in offline mode (no API key)

python demo.py --offline  # uses bundled outline and the same three-layer tool chain

```

You can also manually invoke individual Skill layers for testing:

```python
from tools import read_skill, read_skill_file, run_skill_script

# Load core flow

core = read_skill('pptx')
print('Core flow loaded, length:', len(core))

# Load implementation details

details = read_skill_file('pptx', 'reference.md')
print('Reference loaded, first line:', details.splitlines()[0])

# Execute the bundled script directly

run_skill_script('pptx', 'generate_pptx.py',
    payload='{"title":"Demo","subtitle":"","slides":[{"title":"Intro","bullets":["point1","point2"]}]}')

```

## Key Files and Their Roles

| File | Role |
|------|------|
| [`demo.py`](https://github.com/bojieli/ai-agent-book/blob/main/demo.py) | Main entry point that scans the thin catalog, runs the agentic loop, and orchestrates progressive disclosure |
| [`skills/pptx/SKILL.md`](https://github.com/bojieli/ai-agent-book/blob/main/skills/pptx/SKILL.md) | Layer 2 – Core flow definition for the `pptx` Skill (metadata + procedural steps) |
| [`skills/pptx/reference.md`](https://github.com/bojieli/ai-agent-book/blob/main/skills/pptx/reference.md) | Layer 3 – Detailed layout, color, and python-pptx implementation notes |
| [`skills/pptx/scripts/generate_pptx.py`](https://github.com/bojieli/ai-agent-book/blob/main/skills/pptx/scripts/generate_pptx.py) | Bundled script that turns a JSON slide outline into a real `.pptx` using **python-pptx** |
| [`papers/sample_paper.md`](https://github.com/bojieli/ai-agent-book/blob/main/papers/sample_paper.md) | Sample short paper used as input for the online demo |
| [`papers/sample_outline.json`](https://github.com/bojieli/ai-agent-book/blob/main/papers/sample_outline.json) | Offline-mode slide outline payload (used when no LLM calls are made) |

## Summary

- **Agent Skills** provide modular domain expertise without permanently bloating the system prompt.
- The **progressive disclosure pattern** implements a three-layer architecture: metadata (Layer 1), core workflow (Layer 2), and implementation details (Layer 3).
- Functions like `scan_skill_catalog()`, `read_skill()`, and `run_skill_script()` manage the incremental loading process.
- This approach minimizes token usage, maximizes KV-Cache efficiency, and enables complex multi-step workflows like PowerPoint generation through **python-pptx**.
- The **bojieli/ai-agent-book** repository provides a complete reference implementation with working examples in `chapter2/agent-skills-ppt/`.

## Frequently Asked Questions

### What is the main benefit of using progressive disclosure for Agent Skills?

The primary benefit is **token efficiency**. By loading only Skill metadata at startup and fetching full implementations on demand, the Agent maintains a compact context window. This reduces API costs, improves response latency, and prevents context overflow while still enabling access to complex, multi-file workflows when needed.

### How does the Agent decide when to load Layer 2 or Layer 3 content?

The Agent makes this determination during its reasoning loop based on the task requirements. When the LLM recognizes it needs specific expertise (e.g., creating a PowerPoint), it invokes `read_skill()` to load Layer 2. If the core documentation indicates that implementation details or scripts are required to complete the task, the Agent subsequently calls `read_skill_file()` or `run_skill_script()` to access Layer 3 assets.

### Can I add new Skills to this architecture?

Yes. To add a new Skill, create a directory under `skills/` containing a [`SKILL.md`](https://github.com/bojieli/ai-agent-book/blob/main/SKILL.md) file with Layer 2 workflow documentation. Optionally include a [`reference.md`](https://github.com/bojieli/ai-agent-book/blob/main/reference.md) for Layer 3 details and a `scripts/` directory for executable tools. The `scan_skill_catalog()` function will automatically detect the new Skill's metadata (Layer 1) provided it follows the standard front-matter format with `name` and `description` fields.

### Is the progressive disclosure pattern suitable for real-time applications?

Yes, the pattern is particularly well-suited for real-time applications because it optimizes **KV-Cache reuse** and minimizes initial prompt size. By deferring heavy content loading until absolutely necessary, the Agent can start processing quickly with a lightweight context, then dynamically expand its capabilities as the conversation complexity increases, rather than front-loading all potential knowledge.