Getting Started

Agent Apps turns markdown into software. You write skills — natural-language prompts with YAML frontmatter — and the framework runs them as programs. An AI agent interprets the prompt at runtime, using tools you provide. When you need speed and reliability, compile the skill to deterministic code. The prompt stays the source of truth; code is a derived artifact. Everything in the system — middleware, the agent, file I/O, configuration — is a skill with one interface, discoverable from the filesystem and overridable by placing a replacement earlier in the search path.

Install

Requirements

  • Node.js >= 22.0.0 — Check with node --version.
  • git — used to install the runtime and for hub operations.
  • AWS credentials with Bedrock access — only needed for AI-powered markdown skills. Code skills work without it.

Quick Setup

Install the CLI globally (one-time):

git clone --depth=1 --branch release ssh://git.amazon.com/pkg/AgentApps.git ~/.agent-apps/cli
bash ~/.agent-apps/cli/scripts/install.sh

This clones the release branch to ~/.agent-apps/cli and installs the agent-apps command globally. If the clone fails, make sure you are authenticated (e.g., with mwinit).

To update later:

agent-apps update

Once installed, create a project:

mkdir my-app && cd my-app
agent-apps init
agent-apps hello --name World
# → Hello, World!

init scaffolds a starter project — main.skill.md, a hello skill, README, and .gitignore — and installs the runtime as a local dependency via npm.

Usage Modes

Global CLI (recommended) — install once, use everywhere. Skills are files; the CLI is the interpreter. For markdown-only projects, you can skip agent-apps init and create skill files directly — no package.json required.

Local dependency — add agent-apps to a project's package.json for version pinning or if your code skills need import { ... } from 'agent-apps' (most code skills don't — ctx is passed as a function argument). Install with npm install git+ssh://git.amazon.com/pkg/AgentApps.git#release, then use agent-apps.

Both — global CLI for running skills, local install for TypeScript types and version pinning. The local install takes precedence when present.

Runtime Resolution

The CLI, Desktop editor, and VS Code extension all find the runtime using the same resolution order:

  1. AGENT_APPS_ROOT environment variable (points to the installation directory)
  2. Local project install (./node_modules/.bin/agent-apps)
  3. Global standard location (~/.agent-apps/cli)
  4. agent-apps on PATH

Write a Skill

Skills are the building blocks of an Agent Apps project. A skill is either a code file (.skill.js) or a markdown file (.skill.md) that the framework discovers and makes callable from the CLI.

Code Skills

Create skills/greet.skill.js:

export const frontmatter = {
  name: 'greet',
  description: 'Greet someone by name',
  metadata: {
    params: {
      type: 'object',
      properties: { name: { type: 'string' } },
      required: ['name'],
    },
  },
};

export default async function(_ctx, { name }) {
  return `Welcome, ${name}!`;
}

Run it:

agent-apps greet --name Alice
# → Welcome, Alice!

A code skill exports two things:

  • frontmatter — metadata: the skill's name, description, and a JSON Schema for its arguments.
  • default function — the handler. Receives a context object and the validated arguments.

Markdown Skills

Markdown skills are natural-language prompts that an AI agent executes. These require AWS credentials with Bedrock access — if you don't have that set up yet, skip to Run Skills and come back to this section after reading the AWS setup guide.

Create skills/summarize.skill.md:

---
name: summarize
description: Summarize text
metadata:
  params:
    type: object
    properties:
      text: { type: string }
    required: [text]
---

Summarize the following text in 2-3 sentences:

:arg[text]

Run it:

agent-apps summarize --text "Agent Apps is a framework for building applications..."

The agent reads the prompt, substitutes :arg[text] with the input, and returns a summary. This requires AWS credentials with Bedrock access.

Hybrid Skills

A single markdown file can carry both a prompt (for documentation and agent fallback) and inline code (for deterministic execution) using an inline:// ref:

---
name: word-count
description: Count words in text
metadata:
  params:
    type: object
    properties:
      text: { type: string }
    required: [text]
  delegate: "inline://code,export default async function(_ctx, { text }) { return { words: text.trim().split(/\\s+/).filter(Boolean).length }; }"
---

Count the words in the given text and return the count.

The delegate ref runs deterministically. The markdown body serves as documentation and as a fallback prompt if you remove the delegate. The inline://code,... scheme embeds JavaScript directly in the ref string — no separate file needed.

Run Skills

Every skill is a CLI command:

agent-apps hello --name World                  # By name (unknown flags become args)
agent-apps hello --arg name=World            # Explicit --arg form (equivalent)
agent-apps ./skills/hello.skill.js             # By path
agent-apps                                     # Run the main skill (main.skill.md)

Arguments are passed as --key value flags (unknown flags become args automatically) or explicitly as --arg key=value. See the CLI section of the specification for the full syntax including config overrides and runtime flags.

Inspect Your Project

agent-apps skill-list                          # List public skills (with params, not hidden)
agent-apps skill-list --query files            # Search by name or description
agent-apps skill-describe --ref hello          # Full details on a skill

skill-list returns JSON with every public skill's name, description, and params. skill-describe shows full details including source path, tags, and authority.

Agent Configuration

Code skills work without any AI configuration. For markdown skills, you need AWS credentials with Bedrock access and model configuration in your main.skill.md:

---
name: my-app
metadata:
  role: main
  paths:
    - ./skills
  model:
    id: us.anthropic.claude-sonnet-4-6
    region: us-east-1
---

If you omit the model block entirely, the framework uses us.anthropic.claude-sonnet-4-6 in us-east-1 by default. If you haven't set up AWS credentials yet, see AWS & Bedrock Setup.

Project Structure

After setup, your project looks like this:

my-app/
  main.skill.md                ← Main skill (project config + entry point)
  skills/
    hello.skill.js            ← Code skill (scaffolded by init)
  .agent-apps/                ← Created automatically by hub-add
    packages/                 ← Hub-installed skills (auto-discovered)
    lock.json                 ← Hub package lockfile
  workspace/                  ← Compiled skills and temp files (auto-generated)
  package.json

main.skill.md is both your project's configuration and its default entry point. The role: main declaration makes it the authority for all tools in the project, and the standard pipeline is inherited automatically.

Learn and Explore

Agent Apps ships with tools designed to help you learn the platform interactively.

Interactive REPL

The REPL is the fastest way to explore. Start an interactive session where you can ask questions, run skills, and experiment:

agent-apps repl

Ask it anything — "what skills are available?", "how do I add a web server?", "create a file called notes.txt". The agent has access to all your project's skills and the full framework. Press Ctrl-C to cancel a response, type /help for commands, /exit to quit.

You can also start with a task:

agent-apps repl --task "Explain how middleware works in Agent Apps"

Get Help on Any Skill

Every skill has built-in documentation. Use help to see usage, arguments, and examples:

agent-apps help --ref shell
agent-apps help --ref file-read
agent-apps help --ref skill-compile

Interactive Lessons

The tutor skill provides guided lessons with slides, quizzes, and animations — generated on demand and cached for replay:

agent-apps tutor

Ask for a lesson on any topic: middleware, the cascade, web serving, events. The tutor generates a custom lesson and walks you through it interactively.

Generate a Project from a Description

If you know what you want to build, skill-architect generates an entire project — main skill, route skills, configuration — from a natural-language description:

agent-apps skill-architect --description "A REST API for managing bookmarks with tags"

The agent designs the project structure, writes each skill, and validates them. Use --elicit true to review the plan before generation.

Use with AI Coding Agents

If you use an AI coding agent (Kiro, Claude Code, Cursor), Agent Apps ships with a contrib skill at contrib/agent-apps-developer/SKILL.md that teaches the agent how to build Agent Apps projects. Point your agent at this file — it contains the framework conventions, gotchas, and a validation checklist. The agent can also use the MCP server for live tool access:

agent-apps mcp-server   # Expose your project's skills to any MCP-compatible agent

Next Steps

Build something:

Connect to the world:

Reference:

AWS & Bedrock Setup

See the AWS & Bedrock Setup guide for credential configuration, model access, and CLI overrides.

Ask AI