Progressive Disclosure

How compatible runtimes load Agent Application packages in three tiers to keep context manageable.

Agent Applications uses a three-tier loading model called progressive disclosure. Rather than loading every file in a package into context at once, a compatible runtime loads only what the current task needs, in the order it needs it.

Why progressive disclosure matters

Loading an entire application package upfront — including its full APP.md body, all local SKILL.md files, the contents of app/, optional schemas, and any command output — has a direct cost in tokens and latency. For large or complex packages, that cost is paid even when the task only needs the application’s name and description.

Progressive disclosure lets you keep context lean at startup and pay only for what you actually use.

The three tiers

Tier	What to load	When to load it	What to expose
Catalog	APP.md frontmatter fields only	Startup or package scan	slug, name, description, version, kind, scheduling, declared commands, confirmationRequired, source, trust level
Activation	Full APP.md body + selected SKILL.md files	When a task needs the application	Complete contract text, local skill guidance
Resources	app/ files, schemas/, command output	Only when referenced or executed	Application payload, validation schemas, live state

Tier 1: Catalog

The catalog tier is the lightest. When your runtime starts or scans for packages, parse only the YAML frontmatter of each APP.md. Do not read the markdown body, do not open any SKILL.md files, and do not look inside app/ or schemas/.

From the frontmatter, surface:

• slug — stable portable identity
• name — human-readable display name
• description — short discovery description
• version — package version
• commands — declared command names
• scheduling — whether scheduling is supported
• confirmationRequired — commands that require user confirmation before execution
• Source or provenance of the package
• Trust level assigned by your runtime

The catalog tier is what lets you display a list of installed applications to users or agents without paying the full context cost of loading every package.

Tier 2: Activation

The activation tier loads the full contract for a specific package. Trigger activation when a task indicates it needs a particular application — for example, when the user or agent selects an application, or when the runtime determines a task matches an available package.

At activation time, load:

• The full APP.md markdown body (the text below the frontmatter)
• The SKILL.md files referenced in the skills list, resolved by convention to skills/<slug>/SKILL.md

Inject these into context as the canonical application contract and operating guidance for the current task.

Resolve local skill shortnames by convention. The shortname agentic-to-do-usage resolves to skills/agentic-to-do-usage/SKILL.md relative to the package root. Keep the package root available so these paths resolve correctly.

Do not activate all packages at once. Activate only the packages relevant to the current task.

Tier 3: Resources

The resources tier covers everything that should only load on demand:

• Files inside app/ — the application payload and implementation artifacts
• Files inside schemas/ — optional validation schemas for command output, entity shapes, or command metadata
• Command output — the JSON returned by executing a CLI command

Load resources only when the task explicitly references them or when a command execution produces output that needs to be consumed.

Do not eagerly scan or read app/ during discovery or activation. The internal structure of app/ is application-defined and may contain large files, binaries, or state that is not intended for direct context injection.

What not to eagerly load

To stay within the progressive disclosure model, avoid loading any of the following until explicitly needed:

• The APP.md markdown body during the catalog phase
• Any SKILL.md file during the catalog phase
• Any file inside app/
• Any file inside schemas/
• CLI command output before a command is actually invoked

If your runtime supports context compaction, keep the active package contract — the APP.md body and relevant SKILL.md content — stable during compaction. Dropping an active contract mid-task forces a re-activation that may lose important safety rules or command semantics.