Agent definitions
{"content":"An agent definition turns pack content into a registered Valdr agent. It gives the agent a stable handle, a readable name, a kind, a default role, and the prompts and capabilities that define how it should operate.\n\n## The `.agent.yaml` file\n\nEvery agent in a pack has an `.agent.yaml` file:\n\n```yaml\nschemaVersion: 1.0\nagent:\n handle: sigrid\n name: Sigrid Reviewer\n kind: bot\n defaultRole: reviewer\ncapabilities:\n - key: valdr.reviewer.sigrid.system\n role: core\n - key: valdr.reviewer.sigrid.workflow\n role: workflow\n hot-load: true\n - key: valdr.reviewer.sigrid.severity\n role: constraints\n hot-load: true\nprompts:\n - key: valdr-reviewer-guide\n role: guide\n hot-load: true\n```\n\nThis definition does not contain the full agent prompt. It binds the agent to capabilities and prompts that live in Markdown files elsewhere in the pack.\n\n## Fields that matter\n\n| Field | Purpose |\n|-------|---------|\n| `agent.handle` | Stable identifier users and tools use to launch or route to the agent |\n| `agent.name` | Human-readable name shown in the UI |\n| `agent.kind` | Whether the agent is a bot, CI integration, or human operator |\n| `agent.defaultRole` | The primary job the agent performs |\n| `capabilities` | Structured behavior the agent can use |\n| `prompts` | Reusable prompt material attached to the agent |\n| `hot-load` | Whether detailed material should be loaded on demand instead of always embedded up front |\n\n## Agent kinds\n\n| Kind | Use case |\n|------|----------|\n| `bot` | AI agents and automations |\n| `ci` | CI/CD pipeline integrations |\n| `human` | Human operators and reviewers |\n\nMost pack-authored agents are `bot` agents. Use the other kinds when the pack needs to represent a non-agent participant in the workflow.\n\n## How definitions become behavior\n\nThe `.agent.yaml` file is the wiring layer:\n\n1. The pack importer discovers the definition.\n2. Valdr registers the agent handle and metadata.\n3. Capability and prompt bindings are resolved by key.\n4. The agent starts with its core identity and can load deeper workflow, constraint, validation, or integration material when needed.\n\nThat separation keeps the agent definition compact. The behavior lives in versioned capabilities and prompts instead of being buried inside one giant system prompt.\n\n## Design guidance\n\nUse one agent definition per distinct operating role. A planner, reviewer, auditor, sprint orchestrator, and knowledge orchestrator should be separate agents because users route work to them for different reasons.\n\nGood agent definitions are specific:\n\n| Weak definition | Better definition |\n|-----------------|-------------------|\n| `assistant` | `sigrid` reviewer with review workflow, severity guidance, and verification gates |\n| `planner` with one large prompt | `freya` planner with core identity, planning workflow, research rules, and approval constraints |\n| `agent` with generic tools | `skadi` sprint orchestrator with readiness checks, staffing rules, and session launch behavior |\n\nThe goal is not to create more agents for its own sake. The goal is to make responsibilities clear enough that users know which agent to launch.\n\n## Next steps\n\nRead [Capabilities and prompts](../capabilities-and-prompts/) to see how bound behavior is represented in Markdown, or review the [Built-in orchestrators](../../what-comes-with-valdr/starter-packs/) and [Built-in workflow agents](../../what-comes-with-valdr/included-agents/) for concrete examples.","description":"How .agent.yaml files declare Valdr agent identity, roles, prompts, and capability bindings.","title":"Agent definitions"}
An agent definition turns pack content into a registered Valdr agent. It gives the agent a stable handle, a readable name, a kind, a default role, and the prompts and capabilities that define how it should operate.
The .agent.yaml file
Every agent in a pack has an .agent.yaml file:
schemaVersion: 1.0
agent:
handle: sigrid
name: Sigrid Reviewer
kind: bot
defaultRole: reviewer
capabilities:
- key: valdr.reviewer.sigrid.system
role: core
- key: valdr.reviewer.sigrid.workflow
role: workflow
hot-load: true
- key: valdr.reviewer.sigrid.severity
role: constraints
hot-load: true
prompts:
- key: valdr-reviewer-guide
role: guide
hot-load: trueThis definition does not contain the full agent prompt. It binds the agent to capabilities and prompts that live in Markdown files elsewhere in the pack.
Fields that matter
| Field | Purpose |
|---|---|
agent.handle | Stable identifier users and tools use to launch or route to the agent |
agent.name | Human-readable name shown in the UI |
agent.kind | Whether the agent is a bot, CI integration, or human operator |
agent.defaultRole | The primary job the agent performs |
capabilities | Structured behavior the agent can use |
prompts | Reusable prompt material attached to the agent |
hot-load | Whether detailed material should be loaded on demand instead of always embedded up front |
Agent kinds
| Kind | Use case |
|---|---|
bot | AI agents and automations |
ci | CI/CD pipeline integrations |
human | Human operators and reviewers |
Most pack-authored agents are bot agents. Use the other kinds when the pack needs to represent a non-agent participant in the workflow.
How definitions become behavior
The .agent.yaml file is the wiring layer:
- The pack importer discovers the definition.
- Valdr registers the agent handle and metadata.
- Capability and prompt bindings are resolved by key.
- The agent starts with its core identity and can load deeper workflow, constraint, validation, or integration material when needed.
That separation keeps the agent definition compact. The behavior lives in versioned capabilities and prompts instead of being buried inside one giant system prompt.
Design guidance
Use one agent definition per distinct operating role. A planner, reviewer, auditor, sprint orchestrator, and knowledge orchestrator should be separate agents because users route work to them for different reasons.
Good agent definitions are specific:
| Weak definition | Better definition |
|---|---|
assistant | sigrid reviewer with review workflow, severity guidance, and verification gates |
planner with one large prompt | freya planner with core identity, planning workflow, research rules, and approval constraints |
agent with generic tools | skadi sprint orchestrator with readiness checks, staffing rules, and session launch behavior |
The goal is not to create more agents for its own sake. The goal is to make responsibilities clear enough that users know which agent to launch.
Next steps
Read Capabilities and prompts to see how bound behavior is represented in Markdown, or review the Built-in orchestrators and Built-in workflow agents for concrete examples.