Progressive Disclosure Architecture

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

A cloud-deploy skill supports AWS and Azure, but the current request specifies read-only AWS preparation. Its teaching directory contains SKILL.md, references/aws.md and references/azure.md. AWS material checks region and role; Azure material covers subscription and resource group. Loading both full branches is unnecessary for this selection.

Mechanism

Keep shared objectives, action boundaries and completion conditions in the entrypoint, then give each branch a precise read trigger. For known AWS, read its guide and prepare the required inputs. Resolve the provider only when unknown. Paths are relative to the skill root. Report a missing selected guide rather than substituting another provider’s instructions.

Bad example

For the AWS preparation request above, load every AWS and Azure document first, then choose plausible steps. Shared authorization rules may live only in one reference file.

Good example

Keep shared entrypoint rules: prepare only, do not submit; completion is a candidate configuration and missing-input list. The selected provider is AWS. Read references/aws.md relative to the skill root and inspect region/role requirements. Read references/azure.md only for Azure tasks. Resolve an unknown provider first. Report a missing selected guide without inventing platform steps.

Why the change matters

A clear trigger connects loading to the actual task and limits unrelated operational guidance. Shared boundaries remain visible regardless of branch. Reading is still an action: a pointer’s existence does not establish that the file was read.

Observable expectation

An illustrative trace shows AWS selected, aws.md read, region/role availability reported and a preparation plan delivered without submission; azure.md is not read because Azure was not selected.

Compare actual reads with branch selection and preserve missing-file states. Azure-only requirements in an AWS flow or completion without reading need inspection.

Limits

Loading still consumes context and depends on the host. Source word/line budgets or savings percentages are not measurements for this method, and context is not unlimited. Keep key references reachable from the entrypoint instead of hiding rules behind multiple unread layers.