How to Implement Agent Skills with the Progressive Disclosure Pattern

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.

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, describes the workflow, sub-steps, and tool contracts. For example, 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 (covering layout, color schemes, and python-pptx notes) and executable scripts such as 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 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:

# 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:

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	Main entry point that scans the thin catalog, runs the agentic loop, and orchestrates progressive disclosure
skills/pptx/SKILL.md	Layer 2 – Core flow definition for the pptx Skill (metadata + procedural steps)
skills/pptx/reference.md	Layer 3 – Detailed layout, color, and python-pptx implementation notes
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	Sample short paper used as input for the online demo
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 file with Layer 2 workflow documentation. Optionally include a 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.

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