Progressive Disclosure: Giving an Agent Just Enough Context

A WordPress plugin repo can easily have hundreds of files. Pasting or letting an agent read all of them before every task doesn’t make it smarter, it makes the genuinely relevant three files harder to find in a haystack of context the model has to weigh against everything else it’s holding. Progressive disclosure is the discipline of giving an agent exactly what the current task needs, and nothing more, until it asks for more.

Step 1: why dumping your whole codebase backfires

Every file an agent reads becomes part of its context window for the rest of the session. A context window isn’t infinite, and even before it’s technically full, a model’s attention over a long context is not uniform, content buried in the middle of a huge dump gets weighed differently than content near the start or end of what it’s holding. Ask an agent to “look at the whole plugin and add a settings field” and you’re asking it to hold fifteen unrelated files in mind while trying to focus on the one that actually needs the change.

The fix isn’t a trick, it’s the same instinct a senior developer already has when onboarding a junior teammate to a task: you don’t email them the entire repository, you point them at the three files that matter and the one convention they need to follow.

Step 2: Claude Code’s skill system already works this way

You don’t have to build progressive disclosure from scratch, Claude Code’s skill architecture from Lesson 4 is built around it. A skill’s description field stays in context at all times, cheaply, so Claude knows the skill exists. The full body of SKILL.md, and any supporting reference files it points to, only loads when the skill is actually invoked. A skill can reference a large wpcs-reference.md or an escaping-examples.md file without paying the context cost of that file on every single turn, only on the turn where it’s relevant.

.claude/skills/wp-secure-code/
├── SKILL.md              # loaded when the skill is invoked
├── escaping-examples.md  # loaded only if SKILL.md tells Claude to read it
└── query-patterns.md     # same, loaded on demand, not automatically

Structure your own skills and reference material the same way: a short, always-cheap top-level file, with detail split into separate files Claude reads only when the task in front of it actually needs that detail.

Step 3: write task-scoped prompts, not codebase-scoped ones

The same principle applies to the plain prompts you type, not just skill files. Compare:

Vague, codebase-scoped:
"Add a setting for the plugin that lets admins choose a default post status."

Task-scoped:
"In includes/class-settings-page.php, add a new field to the settings form
registered in register_settings(), following the same add_settings_field()
pattern already used for the 'excerpt_length' field in that file. The new
field should store to the same option array used by get_option( 'my_plugin_options' ),
read in includes/class-post-handler.php around line 40."

The second version tells the agent exactly which file, which existing pattern to mirror, and which other file consumes the result, so it doesn’t need to search the whole repo to guess at conventions it can instead be told directly. That’s less work for the agent and a smaller, more relevant context for the model to reason over.

Step 4: delegate broad exploration instead of doing it inline

Sometimes you genuinely don’t know which files are relevant yet, that’s a real search problem, not something you should skip. The progressive-disclosure move here is delegating that search to a subagent or a scoped exploration step, so the search itself, all the files it opened and discarded along the way, doesn’t become part of your main working context. Only the answer does.

Search this plugin's codebase for every place get_option( 'my_plugin_options' )
is read or written, and report back the file paths and line numbers. Don't
make any changes, just report what you find.

Run that as its own focused turn (or, in Claude Code, as its own subagent task), get back a short list of file paths, then start your actual editing task referencing just those files. You paid the exploration cost once, in an isolated context, and kept your main session focused on the change itself.

Test it

Take a real task you’d normally describe vaguely (“update the checkout flow to support a new field”) and rewrite it as a task-scoped prompt: name the specific file, the specific function, and the specific existing pattern to follow. Compare how much faster and more targeted the agent’s first response is against a vague version of the same request.

Recap

Context is a finite, competitive resource inside an AI coding agent’s session, not a free input that only helps the more of it you provide. Claude Code’s skill system already applies progressive disclosure structurally, cheap descriptions always loaded, full detail loaded on demand, and you can apply the same discipline to your own prompts by naming specific files and patterns instead of describing a whole codebase, and by delegating broad exploration to its own scoped step rather than letting it bloat your main working context.

Resources & further reading

• Extend Claude with skills, code.claude.com
• Claude Code best practices, code.claude.com
• Sub-agents, code.claude.com