Agent Definition Format
Agents are defined as Markdown files with YAML frontmatter. The frontmatter contains metadata—name, description, model, skills—while the Markdown body becomes the agent's system prompt.
Schema Reference
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| name | string |
Yes | — | Unique identifier (1–100 chars) |
| description | string |
Yes | — | Brief role description (1–500 chars) |
| model | "sonnet" | "opus" | "haiku" |
No | "sonnet" |
Claude model to use |
| maxTurns | number |
No | 25 |
Max tool-use turns (1–500) |
| maxDurationSeconds | number |
No | — | Max wall-clock time (10–3600) |
| skills | string[] |
No | [] |
Skill names to attach |
| reportsTo | string |
No | — | Parent agent name |
| memory | object |
No | — | Memory configuration |
Memory Sub-fields
| Field | Type | Description |
|---|---|---|
| episodic | boolean |
Enable episodic memory for the agent |
| maxEpisodes | number |
Maximum number of episodes to retain |
| briefingEnabled | boolean |
Enable pre-run briefings from memory |
| briefingTokenBudget | number |
Token budget for briefing content |
| learningRate | "conservative" | "moderate" | "aggressive" |
How quickly memory adapts to new patterns |
System Prompt
The Markdown body (everything below the closing --- of the YAML frontmatter) becomes the agent's system prompt. This is where you define the agent's personality, behavioral constraints, and domain expertise.
Example Agent File
--- name: engineering-lead description: Engineering team manager model: sonnet maxTurns: 30 skills: - github-operations memory: episodic: true maxEpisodes: 50 briefingEnabled: true --- You are a pragmatic engineering manager...
File Location
Agent definitions live in the agents/ directory with a .md extension. All agent files are auto-loaded when the engine starts up—no manual registration required.
Validation
Agent definitions are validated against a Zod schema at load time. If validation fails, the engine will log a descriptive error and skip the invalid agent.
Common Errors
Missing Fields
name and description are both required. Omitting either will cause a validation error.Invalid Model
The
model field must be one of "sonnet", "opus", or "haiku".maxTurns Out of Range
maxTurns must be between 1 and 500. Values outside this range are rejected.Duration Bounds
maxDurationSeconds must be between 10 and 3600 when specified.