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

# Adding Support

> A guide for implementing Agent Applications support in an agent runtime or host tool.

This guide walks you through implementing Agent Applications support in a runtime, host, or tool. It covers discovery, activation, CLI execution, confirmation handling, and context retention.

**Prerequisites:** familiarity with the [Agent Applications specification](/specification) and the [Agent Skills](https://agentskills.io) `SKILL.md` contract.

## The core principle: progressive disclosure

Every compatible runtime should use the same three-tier loading model. This keeps application context manageable while preserving a reliable execution contract.

| Tier       | What's loaded                                            | When                                |
| ---------- | -------------------------------------------------------- | ----------------------------------- |
| Catalog    | Package name, slug, description, and basic kind metadata | Startup or package scan             |
| Activation | Full `APP.md` body and selected local `SKILL.md` files   | When the task needs the application |
| Resources  | `app/` files, `schemas/`, and command output             | Only when referenced or executed    |

<Steps>
  <Step title="Discover packages">
    Discovery is implementation-defined. Common sources include:

    * A local folder or repository root
    * A checked-out example package
    * An installed application directory
    * A user-selected path or package library

    Treat project-local packages from untrusted repositories as lower trust until the user approves activation or execution.
  </Step>

  <Step title="Parse APP.md">
    For each discovered package:

    1. Parse the YAML frontmatter.
    2. Extract `schema`, `kind`, `slug`, `name`, `description`, and `version`.
    3. Record `entry.command`, `commands`, `skills`, `scheduling`, and `confirmationRequired`.
    4. Preserve the package root for relative path resolution.
    5. Retain the markdown body for later activation.

    Local `SKILL.md` files continue to use normal Agent Skills parsing rules. Treat them as package-local operating guidance referenced by `APP.md`.
  </Step>

  <Step title="Build a lightweight catalog">
    Expose a catalog to the model or UI with the following fields:

    * Package name
    * Description
    * Slug
    * Version
    * Source or provenance
    * Trust level
    * Declared commands
    * Whether scheduling is supported

    <Note>
      Do not eagerly load full `APP.md` bodies or implementation files at this stage. The catalog tier should be cheap to build at startup.
    </Note>
  </Step>

  <Step title="Activate the package contract">
    When a task needs more detail, inject the relevant `APP.md` body and selected `SKILL.md` content into context.

    Follow these rules:

    * Treat `APP.md` as the canonical application contract.
    * Resolve local skill shortnames by convention, usually `skills/<slug>/SKILL.md`.
    * Avoid eagerly loading all of `app/` or `schemas/`.
    * Preserve the package root so relative links and command paths resolve correctly.
  </Step>

  <Step title="Execute the CLI safely">
    The CLI is the executable contract of an Agent Application. When invoking it:

    * Invoke `entry.command` from the package root or a documented equivalent context.
    * Expect machine-readable JSON on stdout by default.
    * Treat non-zero exit codes as failures.
    * Surface stderr as diagnostics rather than the primary contract.
    * Keep command names and returned entity IDs stable when caching or scripting around results.

    Before executing destructive commands, inspect `confirmationRequired` and require an explicit user confirmation step. Do not invent a `schedule` command unless `APP.md` documents one.
  </Step>

  <Step title="Preserve active application context">
    Once an application package or local skill is active, avoid dropping that context during compaction. Keep the current package contract, relevant safety rules, and active local skills stable until the task completes or the active application changes.
  </Step>

  <Step title="Treat state as application-owned">
    The application, not the model transcript, is the source of truth for state. Prefer reading state through the documented CLI or through files the package explicitly describes.

    That means:

    * Do not rely on chat history to remember entities.
    * Treat cached summaries as hints, not source of truth.
    * Prefer re-reading current application state before risky mutations.
  </Step>
</Steps>

## Optional schemas and richer validation

If `schemas/` exists, use it as an optional validation layer for command metadata, JSON output shapes, or entity models. Runtimes that do not understand those schemas should still be able to use the base package contract.

## UI implications

If your product has a UI, keep these flows separate:

* Package discovery
* Contract inspection
* Command execution
* State inspection
* Confirmation flows

Separating them keeps desired package metadata distinct from live runtime state and makes destructive actions easier for users to review before they run.