Agent Applications is a vendor-neutral, markdown-first packaging format for applications that an agent can operate through a CLI. It complements Agent Skills without replacing them. The application owns its data and behavior. The agent operates the application through a documented CLI control surface and uses skills for safe, context-aware interaction.
Directory structure
An application package is markdown-first and usually contains one or more of these canonical parts:
app-package/
├── APP.md
├── app/
├── skills/
│ └── <skill>/SKILL.md
└── schemas/
SKILL.md remains an Agent Skills file. APP.md is defined by the Agent Applications specification.
Package kinds
Agent Applications recognizes these package roots:
| File | Kind | Purpose |
|---|
APP.md | app | Root application manifest and human-readable contract |
SKILL.md | skill | Agent Skills capability package |
Common frontmatter fields
Most APP.md manifests share this set of frontmatter fields. Tools MAY read frontmatter for discovery and cataloging.
| Field | Required | Notes |
|---|
schema | No | Usually agentapplications/v1 |
kind | No | Optional when the filename already makes the kind obvious |
slug | Recommended | Stable portable identity |
name | Yes | Human-readable name |
description | Yes | Short discovery description |
version | Yes | Package version |
license | No | License identifier or reference |
authors | No | Attribution metadata |
tags | No | Search and classification metadata |
metadata | No | Tool-specific extensions |
APP.md fields
These fields are specific to the application manifest and control how a runtime discovers and operates your package.
| Field | Required | Notes |
|---|
entry.command | Yes | The callable CLI entrypoint. The spec does not constrain whether it is a binary, shell command, wrapper, or other callable entry — as long as a compatible client can invoke it and receive structured JSON output. |
commands | Yes | A list of documented command names or command paths. In v1 this is a simple list, not a command-definition DSL. |
skills | Yes | A list of local skill shortnames. By convention, todo-usage resolves to skills/todo-usage/SKILL.md. |
scheduling | No | supported or notSupported. Indicates whether the application exposes scheduling-related CLI commands. |
confirmationRequired | No | A list of commands that require explicit user confirmation before execution. |
Minimal APP.md example
---
schema: agentapplications/v1
kind: app
slug: todo
name: To-do
description: Persistent to-do list operated by an agent through a CLI
version: 0.1.0
entry:
command: todo
commands:
- add
- list
- get
- update
- complete
- remove
scheduling: supported
skills:
- todo-usage
confirmationRequired:
- remove
---
CLI contract
The CLI is the executable contract of the application.
Rules
- The application MUST expose a CLI entrypoint.
- The CLI MUST return machine-readable JSON by default.
- Successful commands MUST write parseable JSON to stdout.
- Failing commands SHOULD write structured JSON errors when possible.
- Failing commands MUST return a non-zero exit code.
- Diagnostics MAY be written to stderr.
- The CLI SHOULD use stable commands and stable entity identifiers.
- Human-readable output, if supported, MUST be opt-in.
- Output shape is application-defined, but it SHOULD be documented in
APP.md and SHOULD remain stable for a given application version.
The spec does not constrain the implementation language, runtime, or packaging mechanism of the CLI. Any callable entry that satisfies the JSON output and exit code rules is compliant.
Illustrative usage
<entry.command> list
<entry.command> add "Buy milk" --due 2026-04-01
<entry.command> complete td_123
Illustrative output
{
"items": [
{
"id": "td_123",
"title": "Buy milk",
"status": "open",
"due_at": "2026-04-01"
}
]
}
Application-owned state
The application owns its state.
Rules
- The 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, including owning their own data and core behavior whenever possible.
This specification does not define how the application stores data internally. State layout inside app/ is entirely application-defined.
app/ directory
app/ contains the application payload.
Rules
app/ MUST contain the application code, executable payload, or equivalent implementation artifacts needed to operate the application.- The internal structure of
app/ is application-defined.
- This specification does not define build, install, or runtime layout inside
app/.
Scheduling
Scheduling is optional in v1.
Allowed values
| Value | Meaning |
|---|
supported | The application exposes scheduling-related CLI commands. |
notSupported | The application does not expose scheduling-related CLI commands. |
scheduling: supported, APP.md SHOULD document the relevant CLI commands.
This specification does not define what runtime invokes those commands. It only defines the application surface that an agent or host can use.
SKILL.md compatibility
This is the core compatibility rule: Agent Applications must not redefine SKILL.md.
An Agent Applications-compatible client should:
- Preserve normal Agent Skills semantics.
- Resolve local skill shortnames by convention, usually
skills/<slug>/SKILL.md.
- Keep runtime-specific details out of the base
SKILL.md contract unless clearly marked as implementation-specific.
Optional schemas/
Application packages may include schemas/, but it is optional in v1.
If present, schemas/ MAY define:
- Command metadata
- Output shapes
- Entity shapes
Larger applications may benefit from it, but it is not required for a minimal compliant package.
Progressive disclosure
Agent Applications uses a three-tier context-management model:
| Tier | Contents | When loaded |
|---|
| Catalog | Lightweight package and skill metadata | Always — low cost |
| Activation | Full APP.md body and selected SKILL.md files | When a runtime activates the package |
| Resources | app/ files, optional schemas/, and command outputs | On demand |
APP.mdapp/skills/- A documented CLI entrypoint
- JSON output by default