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

# Package Structure

> The directory layout of an Agent Application package and the role of each part.

Every Agent Application package follows a canonical directory layout. Understanding each part helps you write packages that any compatible runtime can discover, activate, and operate correctly.

## Directory tree

```text theme={null}
app-package/
├── APP.md
├── app/
├── skills/
│   └── <skill-slug>/
│       └── SKILL.md
└── schemas/          # optional
```

## Parts at a glance

| Part       | Required | Role                                                                                                       |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `APP.md`   | Yes      | Root manifest. Declares the CLI entrypoint, commands, skills, scheduling behavior, and confirmation rules. |
| `app/`     | Yes      | Application payload. Contains the code or executables the CLI entrypoint runs.                             |
| `skills/`  | Yes      | Local Agent Skills. Each subdirectory holds a `SKILL.md` that a runtime loads when activating the package. |
| `schemas/` | No       | Optional metadata for commands, output shapes, and entity shapes.                                          |

## `APP.md`

`APP.md` is the root entrypoint for the package. It has two parts:

1. **YAML frontmatter** — machine-readable fields that a runtime uses for discovery, activation, and command routing.
2. **Markdown body** — human-readable contract sections (Purpose, CLI, Commands, Output, State, Scheduling, Confirmations, Skills).

The frontmatter declares everything a runtime needs before executing a single command: which CLI entrypoint to call, which commands exist, which skills to load, whether scheduling is supported, and which commands require explicit confirmation.

<Note>
  `APP.md` is the only file this specification requires you to put at the package root. The runtime reads it first.
</Note>

## `app/`

`app/` contains the application payload — the code, executables, or other implementation artifacts that back the CLI entrypoint declared in `APP.md`.

### Rules

* `app/` MUST contain everything needed to operate the application.
* The internal structure of `app/` is entirely application-defined. You choose the layout, language, and tooling.
* This specification does not define build steps, install conventions, or runtime layout inside `app/`.

<Warning>
  The application state MUST NOT depend on prompt memory or chat history. Whatever you store inside `app/` — a JSON file, a local database, or anything else — is the source of truth, not the model context.
</Warning>

## `skills/`

`skills/` holds local Agent Skills that give a runtime context-aware operating guidance for the application. Each skill lives in its own subdirectory and contains a `SKILL.md` file.

### How skill shortnames resolve

When you list a skill in `APP.md` frontmatter, you use a shortname:

```yaml theme={null}
skills:
  - agentic-to-do-usage
```

A compatible runtime resolves that shortname to:

```text theme={null}
skills/agentic-to-do-usage/SKILL.md
```

<Note>
  `SKILL.md` follows Agent Skills semantics. Agent Applications does not redefine it — your `SKILL.md` files remain normal Agent Skills files that happen to live inside an application package.
</Note>

## `schemas/` (optional)

`schemas/` is optional in v1. If you include it, it MAY define:

* Command metadata
* Output shapes
* Entity shapes

Smaller packages usually omit `schemas/` entirely. Larger applications with many commands or complex output contracts may find it useful for keeping `APP.md` readable and for giving runtimes structured output documentation.

<Tip>
  If your `APP.md` body section is already clearly documenting output shapes with inline JSON examples, you probably do not need `schemas/` yet.
</Tip>

## How a runtime loads the package

A compatible runtime uses progressive disclosure to manage context cost. It loads the package in three tiers:

<Steps>
  <Step title="Catalog">
    The runtime reads lightweight frontmatter metadata from `APP.md` (and any `SKILL.md` files it finds). No heavy content is loaded yet.
  </Step>

  <Step title="Activation">
    When the package is activated, the runtime loads the full `APP.md` body and the `SKILL.md` files listed in the `skills` frontmatter field.
  </Step>

  <Step title="Resources">
    Files inside `app/`, optional `schemas/`, and actual command outputs are loaded on demand — only when the agent needs them.
  </Step>
</Steps>

This model means you can ship a complete package without worrying that a runtime will load all of `app/` into context on every request.