An Agent Application is a folder-based package that gives an agent a stable, inspectable contract for operating a real application through a CLI. The package lives on disk, describes itself in APP.md, and owns its own state — independent of chat history or prompt memory.
Package structure
Every Agent Application package follows this layout:
my-app/
├── APP.md
├── app/
├── skills/
│ └── <skill-name>/SKILL.md
└── schemas/
| Path | Required | Role |
|---|
APP.md | Yes | Root manifest and human-readable contract |
app/ | Yes | Runnable payload, code, and application-owned state |
skills/ | Yes | Package-local SKILL.md files for agent operating guidance |
schemas/ | No | Optional command, output, and entity shape definitions |
APP.md is the entrypoint an agent or runtime reads first. It declares the CLI command, the supported operations, scheduling behavior, and which destructive commands require explicit confirmation before running.
How agents use an application package
Agent Applications uses the same progressive disclosure model as Agent Skills. Instead of loading everything upfront, a runtime loads only what it needs at each stage:
- Catalog — read lightweight metadata from
APP.md frontmatter: name, description, slug, version. No code runs yet.
- Activation — load the full
APP.md body and any referenced SKILL.md files. The agent now understands the CLI contract and how to operate the app safely.
- Resources — inspect
app/, optional schemas/, and command output only when a task requires it.
This keeps context small while giving the runtime a complete, stable application contract.
A runtime is any host tool or agent environment that loads and operates Agent Application packages. The format does not require a specific runtime — any compatible host can use it.
Why application-owned state matters
In a typical agent workflow, state lives in the chat transcript. That means if the conversation ends or context is truncated, the state is gone. Agent Applications solves this differently: the application owns its data.
The reference agentic-to-do example stores its source-of-truth data in app/state/todos.json. The agent reads and writes that state through the documented CLI — not through prompt memory. The application remains the source of truth regardless of conversation history.
Application-owned state rules from the spec:
- Application state must not depend on prompt memory or chat history.
- The application, not the model context, is the source of truth.
- Applications should be as self-contained as practical, owning their own data and core behavior.
How it complements Agent Skills
Agent Applications builds on Agent Skills without redefining it. The two formats have distinct, complementary roles:
| APP.md | SKILL.md |
|---|
| Defined by | Agent Applications spec | Agent Skills spec |
| Role | Application boundary, CLI contract, commands, output rules | Agent operating guidance and context-aware instructions |
| Scope | Package-level manifest | Per-skill capability file |
| Required in a package | Yes | Yes (at least one, inside skills/) |
APP.md defines what the application does and how to invoke it. Local SKILL.md files define how an agent should operate it safely. Both live in the same package, and neither replaces the other.
Vendor-neutral by design
The base package format works with any compatible runtime. It does not require a registry, a hosted control plane, or a specific adapter architecture. The package is a directory with documented files — any tool that can read a folder and invoke a CLI can use it.
If a runtime needs richer metadata, it can layer that on top without changing the base APP.md and SKILL.md contracts.
What Agent Applications does not define
The v1 spec intentionally excludes:
- HTTP APIs
- Event buses or background workers
- Runtime adapters
- Multi-agent orchestration
These can be added in future revisions without breaking the base format.