Overview

Agent Apps is a framework for building applications from natural-language skills. A skill is a markdown prompt that an AI agent executes directly — or that compiles to deterministic code when you need speed and reliability. The prompt stays the source of truth; code is a derived artifact.

Under the hood, everything is a tool. A tool is a markdown file with YAML frontmatter, a code file that exports a default async function, or a remote capability bridged from an MCP server. Skills, middleware, the agent itself — all tools, all sharing one interface. The runtime resolves tools lazily from a configurable search path and makes them callable through a middleware pipeline.

A project is a directory with a main skill file that serves as both configuration and entry point. There is no separate config file — the main skill's frontmatter metadata IS the config.

The kernel is a tool runner built on the Koa-style middleware pattern. When a tool is invoked, the runner resolves the tool's metadata through a cascade (tool → authority → inherit chain), builds an ordered chain of middleware, executes it against a shared context object, and returns the result. Middleware is itself just tools — same interface, same discovery, same override mechanism. A single builtin — bootstrap — is hardcoded in-memory. Everything else is a tool resolved from the search path.

Naming Convention

The codebase uses a two-layer naming model:

External (user-facing): everything is a skill. Error messages, CLI output, tool descriptions, documentation, and generated content all use "skill." A code skill is a .skill.js file (or .skill.ts with a build step). A markdown skill is a .skill.md file.
Internal (code): everything is a tool. TypeScript types, interfaces, function names, variable names, and the programmatic API (ctx.run.tool, ToolDef, ToolRef, HistoryFrame.tool) all use "tool." The word "skill" appears in code at user-facing boundaries (file extension matching, registered command names like skill-list, error messages like Skill not found) and in helper function names (isSkillFile, isMainSkill, loadSkillsFromFile) where it refers to the file format rather than the runtime concept.

This includes the context API: ctx.run.tool, ctx.manager.invoke(), and HistoryFrame.tool all use "tool" because they are the programmatic interface to the framework, even though users interact with them.

Definitions

Term	Meaning
Tool	Any callable capability: a skill, a code skill, middleware, a builtin, or a bridged MCP tool. All tools share one interface.
Skill	A tool written in natural language. A markdown file (`SKILL.md`, `.skill.md`) with YAML frontmatter and a markdown body. May use `delegate` to forward execution to another tool.
Code Skill	A tool written in code. A `.skill.js`/`.skill.ts` file that exports a default async function. Optionally exports `frontmatter` for metadata.
Delegate	A metadata key (`metadata.delegate`) that redirects execution to another tool. Accepts any resolvable tool reference (bare name, path, URI) or inline code.
Middleware	A tool that participates in the processing pipeline. Middleware operates on `ctx.envelope.target` — the context it's serving — calling `target.manager.next()` to advance the served context's chain. All middleware are tools. All tools can be middleware.
Directive	Inline or block markup in a skill's markdown body using remark directive syntax. Inline: `:name[arg]{attrs}`. Block: `:::name{attrs}\nbody\n:::`. Each triggers a tool with the same name.
Context	Per-invocation object shared by all middleware in a chain. The sole communication channel.
Search Path	Ordered list of directories searched for tools. First match wins.
Tool Name	1–64 characters. Lowercase alphanumeric and hyphens (`a-z`, `0-9`, `-`). No leading, trailing, or consecutive hyphens.
Tool Reference (ToolRef)	A string that identifies a tool: a bare name, a file path, or a URI (`file://`, `mcp://`, `inline://`). Resolved via `findTool()`.
Authority	The main skill (`role: main`) that governs a tool's configuration. Found by walking up from the tool's file location.
Phase Sentinel	Virtual ordering anchor for `before`/`after` constraints in `$order`. Format: `$name` (the `$` prefix ensures it cannot clash with tool names). Built-in: `$pre-configure`, `$configure`, `$post-configure`, `$pre-execute`, `$execute`, `$post-execute`. Sentinels constrain ordering but do not execute.