Progressive disclosure for Agent Skills means loading context in stages: compact metadata for discovery, full instructions when a Skill is selected, and supporting files only when the active procedure needs them. The goal is not to hide information. It is to keep unrelated procedures out of the model’s working context until they become relevant.
An enterprise agent may have access to many specialised methods. Pasting every method and every reference into every request makes the context harder to inspect, more expensive to process, and more likely to contain competing instructions.
The three context layers
| Layer | What the model receives | Why it exists |
|---|---|---|
| Discovery | Name and concise description | Decide which Skill may apply |
| Instruction | The selected Skill’s main procedure | Perform the specialised task |
| Resources | Relevant references or assets from the bundle | Supply detail only when needed |
The open Agent Skills specification describes this directory-centred approach around SKILL.md. VDF AI implements the same practical separation while adding platform validation, agent binding, version snapshots, and activation telemetry.
Why a flat prompt library does not scale
Imagine an agent with eight procedures, each containing 1,500 tokens of instruction and examples. Loading the whole library would spend roughly 12,000 tokens before adding the user request, retrieved evidence, tool results, or response. More importantly, the model must decide which parts to ignore.
The problem is not only token count. Instructions for research, document review, data-quality assessment, and external writes can use similar language while imposing different evidence and approval rules. A crowded context increases the chance that a rule intended for one procedure influences another.
Progressive disclosure changes the question from “Which paragraphs in this large prompt matter?” to “Which named capability should be loaded?”
A worked VDF example
Consider a procurement assistant bound to three Skills:
- Web Research for current public evidence;
- Option Comparison for criteria-based trade-offs;
- File Deliverables for a finished decision brief.
For “What changed in this supplier’s security posture this quarter?”, discovery metadata may select Web Research. Its procedure is loaded, and the agent can use authorised search capabilities. Option Comparison and File Deliverables stay out of context.
For “Compare these three suppliers and produce a decision memo,” the workflow may activate all three in sequence. Each procedure becomes relevant at a different phase, and the final file-building step should receive the finished content rather than redoing the research.
That distinction is an original product design rule in VDF’s included Skills: content reasoning and deliverable generation are separate jobs. It makes tests clearer and prevents document formatting from silently changing the analysis.
Discovery is a classification surface
The description shown during discovery is small but consequential. It should state the task boundary precisely enough to distinguish eligible requests from nearby ones.
Test descriptions with four groups:
- Clear positive cases that should activate the Skill.
- Clear negative cases that should never activate it.
- Near-miss cases that share vocabulary but require another method.
- Ambiguous cases where the agent should ask a question or require explicit invocation.
A weak description can make an excellent procedure invisible. An over-broad description can make it compete with every other capability.
Explicit invocation is a control, not a fallback
VDF AI supports explicit slash-command invocation such as /web-research. This gives users and evaluators a deterministic path when they already know which procedure applies.
Explicit invocation is particularly useful for:
- repeatable evaluation suites;
- provider compatibility testing;
- regulated processes where the selected method must be visible;
- debugging automatic activation;
- expert users who want to choose the method directly.
Automatic discovery remains helpful, but it should not be treated as identical across model providers. The current implementation has provider-specific activation behaviour, so compatibility claims should be based on tests rather than assumed from the package format.
Supporting files should be observable
Bundled references and assets can hold domain detail without making the main procedure unreadable. Loading them on demand works only if operations teams can see what happened.
A useful trace records the Skill name and version, the activation route, the supporting files read, the tools called, and the resulting output. VDF AI exposes Skill activation and file-read telemetry, including inside model-driven Network nodes. This provides evidence for context selection without publishing the resource contents themselves.
Progressive disclosure is not a permission model
Loading less context does not grant or remove access. A Skill’s declared tool requirements are compatibility signals. The platform still decides whether the agent and current user may call each tool, and the connector applies its own scope.
Similarly, a bundled script is not evidence that the runtime will execute it. VDF AI currently imports and preserves supported Skill content but does not execute bundled scripts in the present runtime. Public documentation should say so directly.
A measurement model
Evaluate progressive disclosure with outcomes, not only context size:
- Selection precision: eligible activations divided by all activations.
- Selection recall: eligible requests that activated the Skill.
- Context overhead: Skill-related tokens loaded before task evidence.
- Resource efficiency: referenced files read per successful task.
- Interference rate: failures caused by unrelated instructions.
- Provider variance: differences across tested model runtimes.
Lower context use is valuable only if task quality and safety remain stable or improve.
Explore the eight procedures in the Agent Skills catalog, see the product-neutral explanation in What Are Agent Skills?, or learn how to bind, invoke, and test Skills.