Progressive disclosure for agents.

The problem with giving agents everything

The instinct when building for AI agents is to provide as much context as possible. Write a comprehensive instruction file. Load every reference. Explain every edge case upfront. I did this with the first version of agent-slides, and it failed in exactly the way the OpenAI Codex team later described: "When everything is 'important,' nothing is."

A 2000-line skill file that covers extraction, building, auditing, critique, and polish creates three problems. The agent spends tokens processing instructions it won't use. Unrelated instructions interfere with the current task. And when something goes wrong, the relevant guidance is buried in noise.

The fix isn't better instructions. It's less information, delivered at the right time.

Four layers of disclosure

agent-slides reveals information in four layers. Each layer is self-contained: the agent can do useful work with just the current layer, and drills deeper only when the task demands it.

Layer 1: The skill file. This is the map. A skill file is 100-200 lines of workflow knowledge: what steps to follow, what to check, what mistakes to avoid. It doesn't contain operation syntax or layout dimensions. It tells the agent where to look for those things. The build skill, for example, says "read the resolved manifest for available archetypes" rather than listing all archetypes inline.

Layer 2: Reference files. Each skill has reference files that load conditionally. The build skill has eight references (storytelling, layout patterns, chart best practices, common mistakes, etc.), but only four load every time. The rest load based on what the plan contains. If the deck has no charts, chart-patterns.md stays out of context. This is lazy loading for agent instructions.

Layer 3: Runtime schema introspection. The CLI itself is queryable. slides docs dumps the full operation schema: every operation type, every parameter, every valid value. The agent doesn't need this pre-loaded; it calls the command when it needs to look something up. The CLI is the documentation, and the documentation is always current.

Layer 4: File-based contracts. The deepest layer is the extraction artifacts: resolved_manifest.json, template_layout.json, archetypes.json. These contain the specific dimensions, color zones, and constraints for the template being used. The agent reads these when it needs precise geometry for a specific layout, not before.

Progressive disclosure in the CLI

The CLI applies the same principle to its own interface. An agent building a deck needs render and validate. It doesn't need to know about transform or repair until something goes wrong.

Error responses are disclosure events. When an operation fails, the CLI returns a structured error with a suggested_fix field. The agent doesn't need to know every validation rule in advance. It tries something, the CLI tells it exactly what's wrong and how to fix it, and it adjusts. This is cheaper and more reliable than front-loading every constraint into the prompt.

The --compact flag is another disclosure mechanism. By default, the CLI returns verbose output useful for debugging. With --compact, it returns only what the agent needs for the next step. The agent starts compact and escalates to verbose only when troubleshooting.

Field masks work the same way. slides inspect can return everything about a deck, or just the fields the agent asks for. When checking whether a fix worked, the agent doesn't need the full slide tree. It needs the one property it just changed.

Why flat context fails

I tried the flat approach. One big skill file, all references pre-loaded, full operation reference in context. The agent had everything it could possibly need. It produced worse output.

The failure mode is subtle. The agent doesn't ignore the extra context; it pattern-matches against it. With chart patterns in context while building a text-only slide, the agent would sometimes add unnecessary data visualizations. With audit rules in context during the build phase, it would second-guess its own layout choices before even rendering. More context created more interference, not more capability.

Progressive disclosure solves this by making information available without making it present. The agent knows it can call slides docs to look up an operation. It knows the manifest has layout dimensions. But that knowledge doesn't compete with the current task until the agent actively retrieves it.

A map, not a manual

The pattern is: start small, point to more, let the agent pull what it needs. Skills are the table of contents. Reference files are the chapters. The CLI schema is the appendix. Contracts are the raw data. Each layer exists, each is accessible, and none is forced into context prematurely.

This mirrors how good onboarding works for humans. You don't hand a new hire a 500-page wiki on day one. You give them a short orientation and tell them where to find things. The wiki exists. They read it when they need it.

The difference is that for agents, this isn't just a preference. It's a hard constraint. Every token of unnecessary context is a token unavailable for reasoning about the actual task. Progressive disclosure isn't a nice-to-have; it's how you preserve the agent's ability to think clearly.