APP.md Reference

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

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.

string

The package kind. For APP.md files the value is app. Optional when the filename already makes the kind unambiguous.

string

A stable, portable identifier for the package. Use kebab-case. Recommended — runtimes and catalogs use it to reference the package consistently across environments.

string

required

The human-readable name of the application. Displayed in catalogs and runtime UIs.

string

required

A short description used for discovery and cataloging. Keep it to one sentence.

string

required

The package version. Used by runtimes and catalogs to track releases and changes.

string

A license identifier or reference. Optional.

array

Attribution metadata. Optional.

array

Search and classification metadata. Optional. Runtimes MAY use tags for filtering or grouping packages.

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

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

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

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

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.

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:

Purpose — what the application does and why it exists.
CLI — the entrypoint, default output mode, and any environment variables that affect behavior.
Commands — one subsection per command with signature, flags, and a brief description.
Output — the JSON shape for success and failure responses.
State — where and how the application stores data.
Scheduling — which commands support scheduling and how to invoke them.
Confirmations — which commands require --confirm or equivalent and why.
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.

Get Started

Package Format

Package Authors

Runtime Implementers

Example App

Frontmatter field reference

Common fields

Application-specific fields

Recommended body sections

JSON output format

Full example: Agentic To-Do

​Frontmatter field reference

​Common fields

​Application-specific fields

​Recommended body sections

​JSON output format

​Full example: Agentic To-Do

Frontmatter field reference

Common fields

Application-specific fields

Recommended body sections

JSON output format

Full example: Agentic To-Do