Skip to main content
APP.md is the root manifest of an Agent Application package. It tells a runtime how to discover, activate, and operate the application. Every compliant package must have one. The file has two parts:
  • YAML frontmatter — machine-readable fields between --- delimiters at the top of the file.
  • Markdown body — human-readable documentation sections that follow the frontmatter.

​
Frontmatter field reference

​
Common fields

​
schema
string
The schema identifier for this manifest. Set to agentapplications/v1 to declare compliance with this specification. Optional — the filename already implies the kind — but recommended for tooling.
​
kind
string
The package kind. For APP.md files the value is app. Optional when the filename already makes the kind unambiguous.
​
slug
string
A stable, portable identifier for the package. Use kebab-case. Recommended — runtimes and catalogs use it to reference the package consistently across environments.
​
name
string
required
The human-readable name of the application. Displayed in catalogs and runtime UIs.
​
description
string
required
A short description used for discovery and cataloging. Keep it to one sentence.
​
version
string
required
The package version. Used by runtimes and catalogs to track releases and changes.
​
license
string
A license identifier or reference. Optional.
​
authors
array
Attribution metadata. Optional.
​
tags
array
Search and classification metadata. Optional. Runtimes MAY use tags for filtering or grouping packages.
​
metadata
object
Tool-specific extensions. Optional. Use this for any fields a specific runtime or host tool needs that are not covered by the standard fields.

​
Application-specific fields

​
entry.command
string
required
The callable CLI entrypoint for the application. The spec does not constrain whether it is a binary, shell command, script, wrapper, or other callable entry — as long as a compatible client can invoke it and receive structured JSON output.
entry:
  command: node app/cli.js
​
commands
array
required
A list of documented command names or command paths that the CLI exposes. In v1 this is a simple list, not a command-definition DSL.
commands:
  - add
  - list
  - get
  - update
  - complete
  - remove
​
skills
array
required
A list of local skill shortnames. By convention, a shortname like agentic-to-do-usage resolves to skills/agentic-to-do-usage/SKILL.md. A runtime loads these files when it activates the package.
skills:
  - agentic-to-do-usage
​
scheduling
string
Indicates whether the application exposes scheduling-related CLI commands. Allowed values are supported and notSupported. Optional — omit if scheduling is not relevant to your application.If you set this to supported, document the relevant scheduling commands in the body of APP.md.
​
confirmationRequired
array
A list of command names that require explicit user confirmation before execution. Use this for destructive operations such as remove or delete. Optional.
confirmationRequired:
  - remove

​
Recommended body sections

Write the body of APP.md in plain Markdown after the frontmatter. Include these sections in order:
  1. Purpose — what the application does and why it exists.
  2. CLI — the entrypoint, default output mode, and any environment variables that affect behavior.
  3. Commands — one subsection per command with signature, flags, and a brief description.
  4. Output — the JSON shape for success and failure responses.
  5. State — where and how the application stores data.
  6. Scheduling — which commands support scheduling and how to invoke them.
  7. Confirmations — which commands require --confirm or equivalent and why.
  8. Skills — which skill files to load and what each one covers.
These sections are recommendations, not requirements. A minimal APP.md body can be as short as needed — the frontmatter carries the machine-readable contract.

​
JSON output format

Every CLI command must return JSON by default. Success shape (exit code 0): 
{
  "ok": true,
  "command": "list",
  "count": 1,
  "items": [
    {
      "id": "td_0001",
      "title": "Write docs",
      "description": "",
      "status": "open",
      "dueAt": "2026-04-05",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-04-01T00:00:00.000Z",
      "completedAt": null
    }
  ]
}
Failure shape (non-zero exit code): 
{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}
The exact output shape is application-defined. The spec requires that successful commands write parseable JSON to stdout and that failing commands return a non-zero exit code. Structured JSON errors on failure are strongly recommended but not strictly required.

​
Full example: Agentic To-Do

The following is the complete APP.md from the Agentic To-Do reference application. 
---
schema: agentapplications/v1
kind: app
slug: agentic-to-do
name: Agentic To-Do
description: Self-contained persistent to-do list operated through a JSON-first CLI
version: 0.1.0
entry:
  command: node app/cli.js
commands:
  - add
  - list
  - get
  - update
  - complete
  - remove
skills:
  - agentic-to-do-usage
scheduling: supported
confirmationRequired:
  - remove
---

# Agentic To-Do

## Purpose

Agentic To-Do is a minimal Agent Applications v1 example that gives agents a stable CLI
for managing a persistent to-do list. The application owns its own JSON state under
`app/state/todos.json` and does not depend on chat history or prompt memory.

## CLI

- Entrypoint: `node app/cli.js`
- Default output: JSON on stdout for both success and failure cases
- State override for tests or isolated runs: `AGENTIC_TODO_STATE_FILE=/tmp/todos.json`

## Commands

### `add <title> [--description <text>] [--due-at <iso-date>]`
Create an open to-do item.

### `list [--status all|open|completed]`
List items filtered by status. Defaults to `all`.

### `get <id>`
Fetch a single to-do item.

### `update <id> [--title <text>] [--description <text>] [--due-at <iso-date>] [--clear-due-at]`
Update one or more mutable fields.

### `complete <id>`
Mark an item as completed.

### `remove <id> --confirm`
Delete an item. The `--confirm` flag is required because the operation is destructive.

## Output

Successful commands return structured JSON. Failures return structured JSON with a
non-zero exit code.

## State

The application stores data in `app/state/todos.json`. IDs are stable and increment
as `td_0001`, `td_0002`, and so on.

## Scheduling

Scheduling is supported through the optional `--due-at` field on `add` and `update`.

## Confirmations

`remove` requires explicit confirmation via `--confirm`.

## Skills

Load `skills/agentic-to-do-usage/SKILL.md` when an agent needs concise operating
guidance for the CLI.