Quick Start

Create a minimal Agent Applications package from scratch and verify it conforms to the v1 spec.

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.

---

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

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

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

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