# Valdr Agent Packs
### Ship agent workflows you can trust — in days, not weeks

Ad-hoc prompts crumble once you have more than a couple agents — reviews conflict, permissions drift, and no one remembers why decisions were made. Valdr packs give you a **portable, governed unit** of agents — prompts, capabilities, and context — so you can reuse, share, and evolve workflows without starting over.

> [!TIP]
> Repeatable + auditable: treat agents like productized infrastructure, not improvisation.

> [!NOTE]
> Recommended source locations for pack authoring are `~/.valdr/valdr-packs/<pack-name>` for user-wide packs or `./.valdr/valdr-packs/<pack-name>` for repo-local packs. Nikol defaults to checking those directories when helping you discover, validate, or generate packs.

Valdr packs are portable bundles defined by YAML manifests and annotated Markdown. A `pack.yaml` declares the pack, `.agent.yaml` files define each agent, and `<!--<capability>-->` annotations make prompts machine-discoverable. Import a pack through the UI and get a complete agent roster — orchestrators, reviewers, planners, executors, and auditors — ready to work.

### What's inside a pack

| Layer | Format | Purpose |
|-------|--------|---------|
| **Pack manifest** | `pack.yaml` | Pack identity, version, included directories |
| **Agent definitions** | `.agent.yaml` | Agent identity, kind, capability bindings |
| **Capabilities** | Annotated Markdown | Structured agent behavior with role-based loading |
| **Prompts** | Annotated Markdown | Reusable instructions with tags and metadata |

### Why not "just prompts"?

| Just prompts | Valdr packs |
|--------------|-------------|
| Hard to reuse | YAML specs make packs portable and importable |
| No governance | Capabilities and permissions are explicit |
| Drift over time | Content-hash comparison detects changes |
| People-dependent | System-enforced structure |
| "Trust me, it worked" | Multi-dimensional scoring with evidence |
| Fine for demos | Built for real systems |

### Who this is for

- **Engineering leads** tired of agents that work in dev but break in prod
- **Platform teams** distributing governed AI capabilities across the org
- **Compliance-conscious orgs** that need auditable decision trails
- **Teams scaling past 3 agents** who've felt the pain of prompt sprawl

If you're experimenting with a single agent, you may not need packs yet. But once you've said "we need this to work the same way every time" — you're ready.

### The Valdr core pack

The Valdr core pack ships with **26 agents**, **156 capabilities**, and **168 prompts** — including named orchestrators (Gunnar, Nikol, Skadi), specialists (Sigrid, Freya, Tyr), and task executors for TypeScript, Go, Java, Python, Rust, and more. See [Included agents](./starter-packs/) for the full roster.

Use this section to:

- Understand pack structure and YAML specs
- Learn the tag system for scoring, versioning, and model targeting
- Build team-specific capabilities that encode your institutional knowledge
- Validate and generate archives from the source pack directories Nikol already knows how to find
- Author or adapt packs with the authoring workflow
- Import packs through the Valdr UI

{{< cards >}}
  {{< card link="./overview/" title="Overview" subtitle="Pack structure, YAML specs, authoring directories, and import/export" icon="eye" >}}
  {{< card link="./workflow/" title="Authoring workflow" subtitle="Build, validate, generate, and import packs" icon="adjustments" >}}
  {{< card link="./prompt-ordering/" title="Prompt ordering" subtitle="How system prompts are composed from capabilities" icon="clipboard-list" >}}
  {{< card link="./starter-packs/" title="Included agents" subtitle="Orchestrators, reviewers, planners, and executors" icon="sparkles" >}}
  {{< card link="./team-capabilities/" title="Team capabilities" subtitle="Encode your codebase conventions and tribal knowledge" icon="user-group" >}}
  {{< card link="./tag-system/" title="Tag system" subtitle="Scoring, versioning, and model targeting" icon="tag" >}}
{{< /cards >}}

## Product view

For the platform-level story behind packs and capabilities, read [Team Capabilities for AI Agents](/valdr/docs/features/team-capabilities/). It explains how packs turn repeated team instructions into reusable operational behavior for agents.