Overview

What is a Valdr pack?

A Valdr pack is a portable, self-describing bundle of agents, prompts, and capabilities. Packs use structured YAML manifests and annotated Markdown so that everything — agent identities, capability bindings, prompt content — can be discovered, validated, and imported automatically.

Packs are the distribution unit for agent workflows. Import one and you get a complete roster of agents with their capabilities, prompts, and orchestration wiring — ready to work.

Recommended source directories

When you author or customize a pack, keep the unpacked source directory in one of these locations:

• ~/.valdr/valdr-packs/<pack-name> for user-wide packs you want available across machines or workspaces
• ./.valdr/valdr-packs/<pack-name> for repo-local packs that should travel with the current codebase

Nikol defaults to checking those locations when helping you find, validate, and generate packs, so putting source packs there avoids extra path wrangling.

Pack structure

A pack is a directory with a pack.yaml manifest at the root:

schemaVersion: 1.0
pack: my-team
name: My Team Pack
version: 0.1.0
description: Team-specific agents and capabilities
includes:
  - path: agents
    description: Team agents and role-specific capabilities
  - path: shared
    description: Shared prompts and reusable capability fragments

The includes field tells tooling which directories to scan for agents, prompts, and capabilities. Discovery is automatic — you don’t enumerate every entity in the manifest.

What’s inside

Agent definitions

Every agent in a pack has an .agent.yaml file that declares its identity, role, and capability bindings:

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

Agent kinds

Capability roles

Prompt and capability format

Prompts and capabilities are Markdown files with HTML comment annotations for machine-readable metadata:

Capability:

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

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

Prompt:

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

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

Annotations include:

• id / key — Canonical identifier (lowercase, dashed)
• pack — Logical pack grouping
• role — Purpose classification
• tags — Comma-separated metadata (canonicalized to lowercase, unique, sorted)

Hot-loading

Agents start with a compact system prompt (their core capability), then load detailed capabilities on demand:

pm_capability { action: "prompt", key: "valdr.reviewer.sigrid.workflow" }
→ Returns full workflow capability content

This keeps initial context small while preserving access to complete documentation. The hot-load: true flag in .agent.yaml signals that a capability should be loaded this way.

Validate and generate archives

Treat the source pack directory as the canonical authoring location, then use the Valdr CLI to validate it and build the archive you import:

valdr validate-pack "$HOME/.valdr/valdr-packs/my-team"
valdr generate-valdr-pack "$HOME/.valdr/valdr-packs/my-team" \
  --output "$PWD/dist/packages/my-team.valdr-pack.tar.gz"

For repo-local packs, use the workspace path instead:

valdr validate-pack "$PWD/.valdr/valdr-packs/my-team"
valdr generate-valdr-pack "$PWD/.valdr/valdr-packs/my-team" \
  --output "$PWD/dist/packages/my-team.valdr-pack.tar.gz"

Validation checks the source directory structure, manifests, and capability references before you generate the archive. Generation produces the .valdr-pack.tar.gz bundle that the UI imports.

Importing packs

Packs are imported through the Valdr UI via Settings > Packs:

1. Validate the source pack directory
2. Generate a .valdr-pack.tar.gz archive from that source directory
3. Upload the archive in the Import Valdr Pack dialog
4. Review the preflight action plan — see which entities will be created, overwritten, or skipped
5. Commit the import

The import dialog shows a preflight action plan before committing changes to your workspace.

The preflight plan shows every entity in the pack with its status:

• Create — New entity that doesn’t exist yet
• Overwrite — Existing entity that will be updated
• Unchanged — Entity already matches, no action needed
• Skip — Conflict resolution chose to skip

No surprises. You see exactly what will change before it happens.

What changes when you use packs

Multi-platform support

Packs are authored once and deployed across platforms:

Build targets generate platform-specific output from the canonical source files in commands/ and skills/.

The cost of not using packs

Packs short-circuit this trajectory. You inherit battle-tested structure from day one.