Specification

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/

Required:

APP.md
app/
skills/

Optional:

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

This v1 specification defines only the application package root.

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.

If you set 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

This lets a runtime expose an application package without paying the full context cost upfront.

Conformance

An application is compliant with v1 if it has:

APP.md
app/
skills/
A documented CLI entrypoint
JSON output by default

Get Started

Package Format

Package Authors

Runtime Implementers

Example App

Directory structure

Package kinds

Common frontmatter fields

`APP.md` fields

Minimal `APP.md` example

CLI contract

Rules

Illustrative usage

Illustrative output

Application-owned state

Rules

`app/` directory

Rules

Scheduling

Allowed values

`SKILL.md` compatibility

Optional `schemas/`

Progressive disclosure

Conformance

​Directory structure

​Package kinds

​Common frontmatter fields

​APP.md fields

​Minimal APP.md example

​CLI contract

​Rules

​Illustrative usage

​Illustrative output

​Application-owned state

​Rules

​app/ directory

​Rules

​Scheduling

​Allowed values

​SKILL.md compatibility

​Optional schemas/

​Progressive disclosure

​Conformance

Directory structure

Package kinds

Common frontmatter fields

`APP.md` fields

Minimal `APP.md` example

CLI contract

Rules

Illustrative usage

Illustrative output

Application-owned state

Rules

`app/` directory

Rules

Scheduling

Allowed values

`SKILL.md` compatibility

Optional `schemas/`

Progressive disclosure

Conformance