Capabilities and prompts

Capabilities and prompts are where pack behavior becomes readable. They are Markdown files with machine-readable annotations, so humans can review the instructions and Valdr can discover, bind, order, score, and load them.

Capabilities

A capability is reusable operating behavior. It can define identity, workflow steps, constraints, validation rules, integrations, or contextual knowledge.

<!--<capability id="valdr.reviewer.sigrid.system" pack="valdr" role="core">-->
# Sigrid Code Reviewer

You are Sigrid, a structured code review specialist...
<!--</capability>-->

The annotation gives Valdr a stable identity for the content. The Markdown gives humans something reviewable in source control.

Prompts

A prompt is reusable instruction material that can be attached to one or more agents:

<!--<prompt key="valdr-reviewer-guide" pack="valdr" role="guide" tags="review,quality">-->
# Code Review Guidelines

When reviewing code, evaluate...
<!--</prompt>-->

Annotations include:

id or key - Canonical identifier
pack - Logical pack grouping
role - Purpose classification
tags - Comma-separated metadata for scoring, ordering, and targeting

Capability roles

Roles explain why a capability exists and help Valdr compose agent context predictably.

Role	Purpose	Loading
`core`	Foundational agent identity; exactly one required	Always loaded
`workflow`	Execution patterns and procedures	Often hot-loaded
`constraints`	Guardrails and limitations	Often hot-loaded
`context`	Background information	Often hot-loaded
`validation`	Quality checks and gates	Often hot-loaded
`integration`	External system connections	Often hot-loaded

The core capability should be compact and identity-focused. Put detailed procedures, edge cases, examples, and validation rules into separate hot-loadable capabilities.

Hot-loading

Agents start with a compact system prompt, then load detailed capabilities when the work requires them:

pm_capability { action: "prompt", key: "valdr.reviewer.sigrid.workflow" }
-> returns full workflow capability content

The hot-load: true flag in .agent.yaml signals that a capability or prompt should be loaded this way. This keeps initial context smaller while preserving access to the complete operating manual.

Why this matters

Without capabilities, teams tend to paste everything into one giant prompt. That makes behavior hard to review, hard to reuse, and hard to change safely.

Capabilities let you separate concerns:

Concern	Better as
Who the agent is	`core` capability
How the agent works	`workflow` capability
What the agent must not do	`constraints` capability
What counts as good output	`validation` capability
What systems the agent talks to	`integration` capability
Shared instructions across agents	Reusable prompt or shared capability

This is how packs turn prompts into maintainable agent infrastructure.

Ordering and tags

Valdr composes agent prompts deterministically. If you need exact composition behavior, read Prompt ordering. If you need scoring, model targeting, or canonical prompt metadata, read the Tag system.

Agent definitions