Quick Start

This guide walks you through building a minimal Agent Application package from scratch. By the end, you’ll have a working package with a conformant APP.md, a CLI that returns JSON, and a local skill. The agentic-to-do example in the repository is a full reference implementation of these same patterns.

Conformance checklist

A v1-conformant package requires:

APP.md present
app/ directory present
skills/ directory present
A documented CLI entrypoint
JSON output by default

The steps below satisfy all five requirements.

Create the package directory

Create a folder for your package. Give it a name that matches the slug you’ll use in APP.md.

mkdir my-app
cd my-app

Create the required top-level directories:

mkdir app
mkdir -p skills/my-app-usage

Your package root now looks like this:

my-app/
├── app/
└── skills/
    └── my-app-usage/

Write the APP.md manifest

Create APP.md at the package root. Start with the YAML frontmatter, then add the body sections that document your CLI contract.

APP.md

---
schema: agentapplications/v1
kind: app
slug: my-app
name: My App
description: A minimal Agent Applications v1 package
version: 0.1.0
entry:
  command: node app/cli.js
commands:
  - greet
skills:
  - my-app-usage
scheduling: notSupported
---

# My App

## Purpose

My App is a minimal Agent Applications v1 example.

## CLI

- Entrypoint: `node app/cli.js`
- Default output: JSON on stdout

## Commands

### `greet [--name <text>]`

Returns a greeting. Defaults to `"world"` if no name is provided.

## Output

Successful commands return structured JSON:

\`\`\`json
{
  "ok": true,
  "command": "greet",
  "message": "Hello, world!"
}
\`\`\`

## State

This application is stateless.

## Skills

Load `skills/my-app-usage/SKILL.md` for concise operating guidance.

The entry.command value is whatever CLI command your runtime should invoke. It can be a binary, a shell command, or a script runner like node app/cli.js — as long as calling it produces JSON on stdout.

Key frontmatter fields:

Field	Required	Description
`entry.command`	Yes	The callable CLI entrypoint
`commands`	Yes	List of supported command names
`skills`	Yes	List of local skill shortnames
`scheduling`	No	`supported` or `notSupported`
`confirmationRequired`	No	Commands that need explicit user confirmation

Create the CLI inside app/

Add a CLI script at app/cli.js. The CLI must write JSON to stdout by default and exit with a non-zero code on failure.

app/cli.js

#!/usr/bin/env node

const [,, command, ...args] = process.argv;

function respond(data) {
  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
}

function fail(code, message) {
  respond({ ok: false, error: { code, message } });
  process.exit(1);
}

if (command === 'greet') {
  const nameFlag = args.indexOf('--name');
  const name = nameFlag !== -1 ? args[nameFlag + 1] : 'world';

  if (!name) {
    fail('MISSING_VALUE', '--name requires a value.');
  }

  respond({
    ok: true,
    command: 'greet',
    message: `Hello, ${name}!`
  });
} else {
  fail('UNKNOWN_COMMAND', `Unknown command: ${command}`);
}

Test it locally:

node app/cli.js greet
node app/cli.js greet --name Alice

You should see JSON on stdout:

{
  "ok": true,
  "command": "greet",
  "message": "Hello, world!"
}

Human-readable output is allowed but must be opt-in (for example, a --human flag). JSON must be the default.

Create a SKILL.md in skills/

Create skills/my-app-usage/SKILL.md. The skill shortname in APP.md — my-app-usage — resolves to this path by convention.

skills/my-app-usage/SKILL.md

---
name: my-app-usage
description: Operate my-app safely through its JSON-first CLI
---

# My App Usage

Use this skill when you need to interact with my-app through its CLI.

## Entry command

Run the app from the package root:

\`\`\`bash
node app/cli.js <command> [...args]
\`\`\`

## Safe operating rules

1. Expect JSON on stdout by default.
2. Treat non-zero exit codes as failures and read the structured `error` payload.

## Common commands

\`\`\`bash
node app/cli.js greet
node app/cli.js greet --name Alice
\`\`\`

SKILL.md files follow the Agent Skills format. Agent Applications does not redefine SKILL.md — it references the same format.

Verify conformance

Check that your package meets all five v1 conformance requirements.1. Required files and directories exist:

ls APP.md app/ skills/

2. The entry command runs and returns JSON:

node app/cli.js greet

Expected output:

{
  "ok": true,
  "command": "greet",
  "message": "Hello, world!"
}

3. The CLI exits non-zero on failure:

node app/cli.js unknown-command; echo "Exit code: $?"

Expected output:

{
  "ok": false,
  "error": {
    "code": "UNKNOWN_COMMAND",
    "message": "Unknown command: unknown-command"
  }
}
Exit code: 1

4. Your final package structure:

my-app/
├── APP.md
├── app/
│   └── cli.js
└── skills/
    └── my-app-usage/
        └── SKILL.md

Your package is now v1-conformant.

Next steps

Package structure

Learn what each part of the package is responsible for.

APP.md reference

See all supported frontmatter fields and body sections.

Authoring best practices

Write packages that stay portable, legible, and testable.

Example app

Explore the full agentic-to-do reference package.

Get Started

Package Format

Package Authors

Runtime Implementers

Example App

Conformance checklist

Next steps

Package structure

APP.md reference

Authoring best practices

Example app

​Conformance checklist

​Next steps

Package structure

APP.md reference

Authoring best practices

Example app

Conformance checklist

Next steps