What Is Progressive Disclosure, and Why Does Your AI Need It?

Things started strong.

You uploaded the document that explained your business. Asked for a post. And there it was: your point of view, a recognizable version of your voice, an argument you might actually publish.

So you kept going. Brand guidelines. Sales calls. Your best campaigns. The positioning work you spent weeks getting right.

Then, somewhere along the way, getting a usable draft became a project again.

The wait got longer. The token bill got less amusing. Your voice became whatever voice AI uses when it wants to sound like a thought leader. You corrected something you were fairly sure you had corrected yesterday.

And then it told you it didn’t have the information.

You knew it did. You put it there.

You pointed that out. It apologized with the kind of cheerful confidence that makes a person consider whether a laptop can survive a trip out the window.

Now you’re writing another paragraph of instructions about something your team should already be able to rely on. The campaign is still waiting. The tool that was supposed to give you capacity has given you another draft to supervise.

If that feels familiar, I would look at how your AI reaches your knowledge before giving it more.

You can’t make its judgment clearer simply by making its library bigger.

In Marketing OS, one of the ways we address that is progressive disclosure. Let me show you what that means inside the files, so you can recognize whether your own setup actually does it.

What is progressive disclosure in AI?

Progressive disclosure means giving an AI agent the essential instructions first, then directing it to more detailed information when the task calls for it.

A short starting file explains the business and where to go next. A product question sends the agent to product guidance. That guidance can send it to the relevant product’s detailed reference. A writing task sends it to voice guidance before drafting.

Each step adds information the work needs. The rest stays available without being included in every request.

In a file-based system, you can build this with Markdown files, clear links, folder indexes and tools or scripts that read and maintain them. The Markdown format isn’t the magic. The useful part is the instruction connecting a need to the right next source.

Why does AI struggle when you give it more information?

The files your AI can access and the information it is using right now are different things.

Your repository is the collection of files. The model’s context is the information included while it works: instructions, your conversation, retrieved documents and tool results. That working context is finite. Filling it with more material can make relevant detail harder to use reliably. [1]

So a growing library creates two possible problems. Your setup may load far more than the task needs. Or it may leave the useful file on disk without giving the agent a good route to it.

Both can end with you staring at a draft wondering how it missed something so obvious.

A bigger repository alone doesn’t prove why an answer got worse. Model changes, retrieval failures and unclear instructions can also matter. But checking what was actually read gives you somewhere concrete to start.

This is the distinction I want leaders to catch: you can keep the knowledge without making every task carry all of it.

Progressive disclosure in practice: follow one Marketing OS reading path

Take a job your marketing team might actually assign: write an article explaining what Marketing OS does for a marketing leader.

Here is a walkthrough of the instructions in our repository. It shows the intended route, not a claim that every agent follows it perfectly.

The agent starts with AGENTS.md, which carries a brief business description and points to our main knowledge guide. That guide defines a reading order for messaging work: positioning, audience, product, differentiation, proof, then voice immediately before drafting.

Within that order, the product step opens another door. The product overview says to read the Marketing OS reference when describing Marketing OS. That reference adds the detail the overview deliberately leaves out: buyer problems mapped to capabilities, examples of work the system supports, and limits on what we can promise.

The following diagram zooms into that product branch. The other required messaging reads still apply.

Notice what the deeper file contributes. “Structured brand knowledge” becomes an explanation of how scattered documents, interviews and product material become concise core knowledge linked to references. That gives the writer something more useful to say than “our AI knows your brand.”

The detailed Conversion OS and Sales OS catalogs needn’t come along unless the article also needs those products explained. The overview has already supplied enough context to place Marketing OS within the business.

Later, the instruction to read brand voice immediately before drafting triggers a different read. Product knowledge answers what can we say? Voice guidance answers how should this sound? The agent follows a new route because the stage of work changed.

That is progressive disclosure: a need, a direction, a useful next layer. You can inspect all three.

What should stay in your starting Markdown file?

The temptation is to put everything important at the top. Positioning matters. Voice matters. Every lesson from the last bad draft feels important too.

Eventually the starting file is a record of every time AI annoyed you.

I’d give that file a narrower job: establish essential business direction, preserve rules that must always apply, and tell the agent where to find the rest. Detailed creative methods, product catalogs and channel examples belong behind relevant routes. OpenAI describes a similar approach: a short agent instruction file acts as a map into deeper documentation. [2]

Here is an illustrative rewrite of a starting file for a marketing workspace. These are example filenames, so your team would substitute its real paths.

A link by itself is easy to overlook. “See the library” leaves the next decision vague. “When writing a LinkedIn post, read channels/linkedin.md” explains what to open and when.

And check how your tool loads files. A reference that automatically imports the full destination at startup hasn’t deferred that information. A route that the agent follows only when needed has.

How long should Markdown instruction files be in 2026?

There isn’t a universal line count that makes an AI instruction file good.

Our own architecture uses targets of under 200 lines for combined entry guidance and its positioning router, and under 120 lines for each deeper core file. Those are Synapsa’s maintenance targets, not model limits or proof that a shorter file will produce a better answer.

They force a useful editorial decision: does this belong in the brief everyone starts with, or in a reference opened for a particular job?

For your team, I would use the size check this way:

• Starting instructions: retain essential direction and routes. Split when the file starts explaining several different jobs in full.
• Core guidance: keep a distilled account of one subject. Move supporting examples and source detail into linked references when they obscure that account.
• Deep references: organize for selective reading. A long reference may be justified; give it useful headings, an index or a way to retrieve the relevant section.

Count tokens as well as lines. A paragraph squeezed onto one line isn’t leaner. And a short instruction that omits a necessary distinction is just incomplete.

The useful test is whether the agent gets enough information to do the work, without loading unrelated material by default. Progressive disclosure can add retrieval steps, so it doesn’t guarantee a faster response on every task. [1]

How do indexes keep useful knowledge discoverable?

Direct links work well for stable guidance. But your library keeps growing. New product notes. New research. New examples worth keeping.

An index gives the agent a small description of those files before it decides which to open. Think of the entry as a reason to read, not just a filename.

Compare marketing-os.md: product information with this:

Path: library/product/marketing-os.md
Read when: describing Marketing OS capabilities or limits.
Contains: buyer problems mapped to capabilities, production
examples, and boundaries on savings and performance claims.

The second entry helps the agent choose. It also helps it avoid opening the file for a job that doesn’t need it.

In Marketing OS, library documents carry structured labels, including an abstract and the core topics they support. A script rebuilds the library index and focused views from that metadata. The product view can point to product material without asking the agent to read the entire library first.

This is one of my favorite parts of Marketing OS. The structure has a maintenance process. New material can be described as it’s created, and the catalog can be regenerated instead of relying on someone to remember every index entry.

The distinction matters: AI can draft the description; deterministic software can place it in the right indexes. Neither step makes a misleading description accurate. That still needs a check.

Start with an index at the library entrance. Add focused folder or topic indexes when they help the agent narrow its choice. An index that repeats the whole library has simply moved the overload up a level.

Not all knowledge should carry the same weight

There is another reason to be deliberate about those routes: not all knowledge is created equal.

Your current positioning is strategic direction. A buyer call is evidence of what that buyer said. A successful campaign is an example, not permission to reuse every claim it contains.

The starting guidance should make those roles clear. Otherwise, the agent can reach a relevant document and still use it for the wrong purpose.

The same call may send marketing toward an explanation buyers need and sales toward a question to ask on the next call. The source stays the same; the job determines what the agent does with it.

This supports progressive disclosure. It doesn’t replace it. You still need to show how the agent gets from the current job to that source in the first place.

What should a CMO or CRO ask the team to show?

Pick one recurring task that keeps coming back for correction. Ask the person maintaining your AI workspace to show you the files the agent actually read, the instruction that led to each one, and the resulting draft.

Use the Marketing OS example as your test. If the draft describes capabilities vaguely, did the agent reach the detailed product reference? If it didn’t, fix the missing or ambiguous route. Repeating “be more specific” in the prompt doesn’t repair a route that never reaches the specifics.

If it did read the right reference, inspect what it did with the information. The problem may be the writing method or the review standard. Another file won’t automatically solve that either.

You can give your team this inspection brief:

Use a recent task and its actual read log. Show what loaded at the start, what opened later, and why. Identify one missing necessary read or one unnecessary read. Change the route or index entry that caused it, then rerun the same task. Compare the read logs and the outputs. Check the exact issue we were correcting, and whether the change introduced a new omission.

Your team will still have to choose what belongs in the core, maintain descriptions and judge the finished work. You are making that judgment reusable instead of expressing it again in every frustrated follow-up.

That is the point for me. The business should be able to accumulate knowledge without making good work depend on an ever-longer opening prompt.

Before adding another rule, look at the first file. Then look at where it sends the AI. And the next place after that.

Frequently asked questions

Is progressive disclosure the same as organizing files into folders?

No. Folders arrange the material. Progressive disclosure controls when the agent receives it. A useful setup connects a task or stage of work to the next source, with enough description to choose correctly.

Does an index automatically make AI read a file?

No. The agent needs access to the file, a reason or instruction to consult the index, and useful entries. Test actual reads; a neat folder tree doesn’t establish that the route works.

Does progressive disclosure reduce token use?

It can reduce unnecessary context when it replaces indiscriminate loading. But retrieval and repeated reads also cost tokens and time. Compare representative runs and output quality before claiming savings.

Can I do this without Marketing OS?

Yes. The pattern can work in an agent workspace that supports file access and task instructions. Marketing OS applies it to maintained brand knowledge and the methods your marketing team uses to produce work. If you want to see that broader system, explore Marketing OS.

References

[1] Anthropic, Effective context engineering for AI agents. Guidance on finite context, selective retrieval and the trade-offs of retrieving information while working.

[2] OpenAI, Harness engineering. A short agent instruction file serving as a map into maintained documentation.