Skip to main content
Agent Application packages work best when they describe a real application contract rather than a vague project folder. The goal is to make your package useful across runtimes while keeping it legible to humans.

​
Start from the actual CLI

Begin with the real command surface before writing any documentation. Identify:
  • what command launches the application
  • which subcommands agents may call
  • what JSON each command returns
  • which actions are destructive
  • where the application stores its source-of-truth state
The strongest packages come from a real executable interface, not a speculative manifest. Write APP.md to describe what the CLI already does.
For example, the Agentic To-Do APP.md frontmatter declares the entry command and every supported subcommand before the body explains anything: 
entry:
  command: node app/cli.js
commands:
  - add
  - list
  - get
  - update
  - complete
  - remove

​
Keep the package shape legible

A reader should be able to orient themselves quickly. Each canonical part has a clear role:
PathPurpose
APP.mdThe application contract
app/The runnable payload and owned state
skills/Local operating guidance
schemas/Optional output and entity shapes
If the package shape is hard to follow, activation will be hard to follow too. Avoid blurring responsibilities between directories.
Only include schemas/ when it adds clarity to the contract. It is optional in v1.

​
Document state and side effects clearly

Agents need to know what your application owns and how mutations work. In APP.md, document:
  • the primary state location or state model
  • whether commands mutate data
  • how IDs are assigned and reused
  • what confirmation steps destructive commands require
If a runtime has to guess what the application owns, the package contract is not clear enough yet. State ownership is one of the most important things APP.md communicates.
The Agentic To-Do example makes state ownership explicit: 
## State

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

​
Keep APP.md and skills separate

APP.md should describe the application boundary and command surface. Local SKILL.md files should describe reusable operating guidance.
  • If you find yourself copying command semantics into every skill, improve APP.md.
  • If you find yourself copying operating procedures into the body of APP.md, move that guidance into a local skill.
Blending these two concerns makes both harder to maintain. Runtimes that discover skills separately from the full application contract depend on this boundary being clear.

​
Prefer stable JSON and stable identifiers

Agents benefit from predictable output. Design your CLI so that:
  • successful commands return machine-readable JSON on stdout
  • failures return structured JSON errors when possible
  • entity IDs remain stable across runs
  • human-readable output is opt-in rather than the default
Stable outputs make packages easier to test and safer to automate. If your CLI changes output shape between runs for the same command, write evals to catch regressions early.
Here is an example of a well-structured success response: 
{
  "ok": true,
  "command": "list",
  "count": 1,
  "items": [
    {
      "id": "td_0001",
      "title": "Write docs",
      "status": "open",
      "dueAt": "2026-04-05"
    }
  ]
}
And a well-structured failure response: 
{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}

​
Write defaults, not menus

When several approaches are possible, choose a safe default and state the exception path briefly. That is more reliable than giving an agent an unranked list of options.
A single recommended path is more useful than an exhaustive list of alternatives with no guidance on when to use each one.

​
Validate with real runs

A package is ready to ship when:
  • the documented entry.command is callable
  • commands matches the actual runtime surface
  • state lives in the application rather than prompt memory
  • destructive commands enforce their confirmation rules
  • local skills improve operation without contradicting APP.md
Use the optimizing descriptions and evaluating packages guides to tighten the package over time.