> ## Documentation Index > Fetch the complete documentation index at: https://agentapplications.io/llms.txt > Use this file to discover all available pages before exploring further. # Specification > The complete v1 format contract for Agent Applications packages. 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: ```text theme={null} app-package/ ├── APP.md ├── app/ ├── skills/ │ └── /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 ```yaml theme={null} --- 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 ```bash theme={null} list add "Buy milk" --due 2026-04-01 complete td_123 ``` ### Illustrative output ```json theme={null} { "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//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