> ## Documentation Index
> Fetch the complete documentation index at: https://agentapplications.io/llms.txt
> Use this file to discover all available pages before exploring further.

# What are Agent Applications?

> Agent Applications is a vendor-neutral, markdown-first package format for applications that AI agents can inspect and operate through a documented CLI.

An Agent Application is a folder-based package that gives an agent a stable, inspectable contract for operating a real application through a CLI. The package lives on disk, describes itself in `APP.md`, and owns its own state — independent of chat history or prompt memory.

## Package structure

Every Agent Application package follows this layout:

```text theme={null}
my-app/
├── APP.md
├── app/
├── skills/
│   └── <skill-name>/SKILL.md
└── schemas/
```

| Path       | Required | Role                                                        |
| ---------- | -------- | ----------------------------------------------------------- |
| `APP.md`   | Yes      | Root manifest and human-readable contract                   |
| `app/`     | Yes      | Runnable payload, code, and application-owned state         |
| `skills/`  | Yes      | Package-local `SKILL.md` files for agent operating guidance |
| `schemas/` | No       | Optional command, output, and entity shape definitions      |

`APP.md` is the entrypoint an agent or runtime reads first. It declares the CLI command, the supported operations, scheduling behavior, and which destructive commands require explicit confirmation before running.

## How agents use an application package

Agent Applications uses the same progressive disclosure model as Agent Skills. Instead of loading everything upfront, a runtime loads only what it needs at each stage:

1. **Catalog** — read lightweight metadata from `APP.md` frontmatter: `name`, `description`, `slug`, `version`. No code runs yet.
2. **Activation** — load the full `APP.md` body and any referenced `SKILL.md` files. The agent now understands the CLI contract and how to operate the app safely.
3. **Resources** — inspect `app/`, optional `schemas/`, and command output only when a task requires it.

This keeps context small while giving the runtime a complete, stable application contract.

<Note>
  A runtime is any host tool or agent environment that loads and operates Agent Application packages. The format does not require a specific runtime — any compatible host can use it.
</Note>

## Why application-owned state matters

In a typical agent workflow, state lives in the chat transcript. That means if the conversation ends or context is truncated, the state is gone. Agent Applications solves this differently: the application owns its data.

The reference [`agentic-to-do`](https://github.com/davetist/agentapplications/tree/main/example/agentic-to-do) example stores its source-of-truth data in `app/state/todos.json`. The agent reads and writes that state through the documented CLI — not through prompt memory. The application remains the source of truth regardless of conversation history.

**Application-owned state rules from the spec:**

* 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, owning their own data and core behavior.

## How it complements Agent Skills

Agent Applications builds on Agent Skills without redefining it. The two formats have distinct, complementary roles:

|                           | `APP.md`                                                   | `SKILL.md`                                              |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
| **Defined by**            | Agent Applications spec                                    | Agent Skills spec                                       |
| **Role**                  | Application boundary, CLI contract, commands, output rules | Agent operating guidance and context-aware instructions |
| **Scope**                 | Package-level manifest                                     | Per-skill capability file                               |
| **Required in a package** | Yes                                                        | Yes (at least one, inside `skills/`)                    |

`APP.md` defines *what* the application does and how to invoke it. Local `SKILL.md` files define *how* an agent should operate it safely. Both live in the same package, and neither replaces the other.

## Vendor-neutral by design

The base package format works with any compatible runtime. It does not require a registry, a hosted control plane, or a specific adapter architecture. The package is a directory with documented files — any tool that can read a folder and invoke a CLI can use it.

If a runtime needs richer metadata, it can layer that on top without changing the base `APP.md` and `SKILL.md` contracts.

## What Agent Applications does not define

The v1 spec intentionally excludes:

* HTTP APIs
* Event buses or background workers
* Runtime adapters
* Multi-agent orchestration

These can be added in future revisions without breaking the base format.