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 and the Agent Skills 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

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

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

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

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

4. 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.
5. 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.

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

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

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.