> ## Documentation Index
> Fetch the complete documentation index at: https://agentapplications.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://github.com/davetist/agentapplications/tree/main/example/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 a folder for your package. Give it a name that matches the `slug` you'll use in `APP.md`.
```bash theme={null}
mkdir my-app
cd my-app
```
Create the required top-level directories:
```bash theme={null}
mkdir app
mkdir -p skills/my-app-usage
```
Your package root now looks like this:
```text theme={null}
my-app/
├── app/
└── skills/
└── my-app-usage/
```
Create `APP.md` at the package root. Start with the YAML frontmatter, then add the body sections that document your CLI contract.
```mdx APP.md theme={null}
---
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 ]`
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 |
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.
```javascript app/cli.js theme={null}
#!/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:
```bash theme={null}
node app/cli.js greet
node app/cli.js greet --name Alice
```
You should see JSON on stdout:
```json theme={null}
{
"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 `skills/my-app-usage/SKILL.md`. The skill shortname in `APP.md` — `my-app-usage` — resolves to this path by convention.
```mdx skills/my-app-usage/SKILL.md theme={null}
---
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 [...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](https://agentskills.io) format. Agent Applications does not redefine `SKILL.md` — it references the same format.
Check that your package meets all five v1 conformance requirements.
**1. Required files and directories exist:**
```bash theme={null}
ls APP.md app/ skills/
```
**2. The entry command runs and returns JSON:**
```bash theme={null}
node app/cli.js greet
```
Expected output:
```json theme={null}
{
"ok": true,
"command": "greet",
"message": "Hello, world!"
}
```
**3. The CLI exits non-zero on failure:**
```bash theme={null}
node app/cli.js unknown-command; echo "Exit code: $?"
```
Expected output:
```json theme={null}
{
"ok": false,
"error": {
"code": "UNKNOWN_COMMAND",
"message": "Unknown command: unknown-command"
}
}
Exit code: 1
```
**4. Your final package structure:**
```text theme={null}
my-app/
├── APP.md
├── app/
│ └── cli.js
└── skills/
└── my-app-usage/
└── SKILL.md
```
Your package is now v1-conformant.
## Next steps
Learn what each part of the package is responsible for.
See all supported frontmatter fields and body sections.
Write packages that stay portable, legible, and testable.
Explore the full agentic-to-do reference package.