Progressive Disclosure

I have about thirty skills installed. My AI is not reading thirty files before it answers me. It reads thirty one-line descriptions, finds the one that matches what I asked, and opens that file only. Progressive disclosure is the reason that works.

Progressive disclosure means showing the smallest useful version of something first and keeping the depth one step behind it, there for whoever wants it.

The everyday picture is a luggage tag on a packed trunk. The tag tells you what is inside in about six words. You read the tag, and the trunk stays shut until you need what is in it. Line up twenty trunks and you can still find the one you want in seconds, because you are reading twenty tags instead of unpacking twenty trunks.

For AI tools that is arithmetic, not decoration. The context window is finite, and every word you load into it spends part of a fixed token budget. Thirty skill files loaded up front would eat a serious chunk of that window before the real work started. Thirty tags cost almost nothing, and the one trunk that matters still gets opened all the way. A well-written CLAUDE.md works the same way, pointing at the detail instead of reciting it.

You have been using the human version of this for years:

• The "Advanced settings" button. Most people never open it, and the ones who need it know where to look. Putting all of it on the first screen would slow everyone down to serve almost nobody.
• Onboarding that asks three questions instead of thirty. You get moving in a minute, and the rest surfaces later, once you know enough to care about the answers.

The catch is that progressive disclosure only works if the tag is honest. A tag that undersells what is inside means the trunk never gets opened, so you may as well not have packed it. The worse version reads like a summary but is really a bluff, with the thing someone actually needs buried two clicks down where they will never think to look.

So the question to ask of anything you make, for a person or for an AI, is what the smallest honest version looks like, and whether the rest is genuinely one step away. Progressive disclosure is showing the short version first and keeping the long version within reach. Write the tag well enough that someone can decide without opening the trunk.