When Anthropic introduced Agent Skills last October, they named the core design principle progressive disclosure. The community adopted it instantly. It's now in the official docs, the engineering blog, every tutorial, every breakdown. It has become the canonical term.
I want to suggest a better one: progressive discovery. Not to be contrarian, and not because the term is technically wrong but because discovery produces a clearer, more intuitive picture of what is actually happening. And when you have that picture clearly in mind, everything about working with Skills becomes more natural.
What is actually happening
At runtime, Claude Code scans the name and description of every installed Skill and reasons about whether any of them are relevant to the current task. If one looks promising, it reads the full SKILL.md body and reasons further. Only if the task demands more depth does it go looking for supplementary files — references, scripts, assets. It might stop at level one because that's all it needs.
The progression is not a fixed reveal sequence. It is Claude reasoning its way deeper, one conditional step at a time, each small act of discovery informing whether the next one is even necessary.
The key thing to hold onto is this: Claude is the one doing something. The Skill is not. The Skill is bytes on disk. It has no mechanism, no trigger, no awareness of context. It simply exists, waiting to be found and discovered. Claude is the active party. The Skill is a passive resource.
Why "disclosure" obscures this
Disclosure implies an active subject — something with intent, making a decision to reveal. In UX design, where the term originates, that's accurate. The interface is the active party — it reads state and decides what to reveal and when. Gmail discloses advanced settings when you're ready for them. The interface is doing something.
When people encounter "progressive disclosure" in the context of Skills, it's natural to absorb that same model. The Skill becomes the active party. It discloses what it needs to, when it needs to. That framing is subtle and mostly unconscious — and it quietly makes the whole thing slightly harder to picture accurately.
It also points your thinking as a Skill author in a slightly unhelpful direction. If the Skill is doing the disclosing, you might find yourself thinking about what it should surface and when, as though you are designing a reveal sequence. You might focus on the structure of the layers rather than on the question that actually matters.
What "discovery" clarifies
Swap the term and the picture sharpens immediately.
Claude is discovering. The Skill is being discovered.
That one shift makes the whole dynamic legible. Claude discovers the metadata and decides whether to go further. Claude discovers the SKILL.md body and decides whether to go further still. Claude discovers the supporting files only if it needs them. The progression belongs to Claude's reasoning — a chain of small, conditional decisions made by an active subject working its way through a passive resource.
And once you see it that way, what you should be optimising for as a Skill author becomes obvious. You are not designing a reveal sequence. You are making something to be discoverable.
The question you should be asking at every layer is not "what does this Skill disclose here?" but "can Claude find what it needs here, and does it have enough to decide whether to go deeper?" That is a more useful question, and it comes naturally from the right term.
Anthropic's own writing points the same way
Anthropic's own engineering blog, the post that introduced the term, describes what actually happens in entirely accurate language. Claude triggers. Claude determines. Claude loads. The explanation and the label are quietly in tension with each other.
The community has followed the same pattern. Writers instinctively reach for discovery language when describing Claude's behaviour, even in pieces that headline "progressive disclosure." One widely-read breakdown notes that Claude "should have no problem discovering what resources it needs." Another describes Skills as "dynamically discovered and loaded." The more intuitive framing keeps surfacing in the descriptions, even when the terminology says something slightly different.
The instinct is right. The label just hasn't caught up.
""Progressive disclosure" came from UX, where it belongs. As an analogy it helps with initial understanding — most developers already know the concept, and it gives you a quick way in. But it only takes you so far, and beyond that it can mislead.
Progressive discovery makes it clear. Claude is the subject, working its way incrementally through a passive resource — discovering a little, then a little more, then a little more, until it has what it needs. The Skill's job is to be found, at every layer, by a subject actively reasoning its way through.
That picture, once you have it, is hard to unsee. And it makes building good Skills feel considerably more intuitive.
