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

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.

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

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/.

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.

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:

skills:
  - agentic-to-do-usage

A compatible runtime resolves that shortname to:

skills/agentic-to-do-usage/SKILL.md

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.

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.

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

How a runtime loads the package

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

1. Catalog

   The runtime reads lightweight frontmatter metadata from APP.md (and any SKILL.md files it finds). No heavy content is loaded yet.

2. 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.

3. Resources

   Files inside app/, optional schemas/, and actual command outputs are loaded on demand — only when the agent needs them.

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