> ## Documentation Index
> Fetch the complete documentation index at: https://agentapplications.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tip>
  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.
</Tip>

## 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.

<Note>
  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.
</Note>

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.

<Warning>
  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.
</Warning>

## 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

<Tip>
  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.
</Tip>