# 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:

```yaml
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: true
```

This 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:

1. The pack importer discovers the definition.
2. Valdr registers the agent handle and metadata.
3. Capability and prompt bindings are resolved by key.
4. 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](../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.