Authoring workflow

The fastest way to build a Valdr pack is to let an orchestrator do the wiring for you. Nikol is the registry orchestrator built for exactly this: describe the agent behavior you want, and Nikol inspects your existing registry, picks the right boundaries, and drafts the manifest, agents, capabilities, and prompts as real pack files. You stay in control — Nikol scaffolds, you review and import.

This page covers both paths:

• Author with Nikol — recommended. Minimal manual work; you describe the behavior and review the result.
• Build a pack by hand — the underlying spec format, useful for understanding what Nikol generates or hand-tuning a single file.

Local-first: Valdr runs entirely on your machine. Packs, agents, capabilities, prompts, and history live in your local workspace and remain until you delete them. Pack files are plain YAML and Markdown, so you can version them and share them with the teams you work with.

Author with Nikol (recommended)

Instead of hand-writing YAML and Markdown, hand the job to Nikol and review what it produces. Nikol turns “we need an agent that behaves like this” into validated, pack-backed files — usually in a single session — so you skip the boilerplate and get to a working pack fast.

/valdr-orchestrator
Use nikol to scaffold a new "my-team" pack with a reviewer agent that enforces our PR conventions.

Want to see exactly what those files look like, or hand-tune one? The rest of this page is the underlying format Nikol writes to.

Build a pack by hand

You don’t have to author packs manually — Nikol handles the steps below for you. Reach for the manual path when you want to understand the format, tune a single file, or work without an orchestrator.

The specs

Three specification documents define the pack format. Reference these when authoring:

0) Choose the source directory

Store the unpacked source pack in one of the locations Nikol checks by default:

• ~/.valdr/valdr-packs/<pack-name> for a user-wide pack library
• ./.valdr/valdr-packs/<pack-name> for a pack that belongs to the current repo

Examples:

mkdir -p "$HOME/.valdr/valdr-packs/my-team"
mkdir -p "$PWD/.valdr/valdr-packs/my-team"

Use one of those directories as the pack root in the remaining steps.

1) Create the pack manifest

Start with a pack.yaml at your pack 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
  - path: shared
    description: Shared capabilities and prompts

The includes field tells tooling which directories to scan. Only included paths are discovered — nothing else in the pack root is imported automatically.

2) Define agents

Create an .agent.yaml for each agent:

schemaVersion: 1.0
agent:
  handle: my-reviewer
  name: My Team Reviewer
  kind: bot
  defaultRole: reviewer
capabilities:
  - key: myteam.reviewer.system
    role: core
  - key: myteam.reviewer.workflow
    role: workflow
    hot-load: true
prompts:
  - key: myteam-review-guide
    role: guide
    hot-load: true

Rules:

• Exactly one capability with role: core is required
• handle must be unique across your workspace
• kind must be bot, ci, or human
• hot-load: true capabilities are loaded on demand, keeping initial context small

3) Author capabilities and prompts

Write Markdown files with HTML comment annotations:

Capability:

<!--<capability id="myteam.reviewer.system" pack="my-team" role="core">-->
# My Team Reviewer

You are a code reviewer for the My Team codebase. You follow our
team conventions and review standards.

## Responsibilities
- Review code changes against acceptance criteria
- Flag violations of team conventions
- Score work quality

## Tools
- `pm_task` — Fetch task details
- `pm_review` — Submit review feedback
<!--</capability>-->

Prompt:

<!--<prompt key="myteam-review-guide" pack="my-team" role="guide" tags="review,quality,conventions">-->
# Review Guidelines

## Code style
- Follow ESLint config in repo root
- Prefer composition over inheritance
- All public functions need JSDoc

## Testing requirements
- Unit tests for business logic
- Integration tests for API endpoints
<!--</prompt>-->

Naming conventions:

{pack}.{domain}.{agent}.{capability-name}

Examples:

• myteam.reviewer.system — Core identity
• myteam.reviewer.workflow — Review execution flow
• myteam.core.tools.pm-task — Tool documentation

4) Organize the directory

my-team-pack/
├── pack.yaml
├── agents/
│   └── reviewer/
│       ├── my-reviewer.agent.yaml
│       ├── myteam.reviewer.system.md
│       └── myteam.reviewer.workflow.md
└── shared/
    └── prompts/
        └── myteam-review-guide.md

Place agent YAML and capability Markdown in the same directory. Shared prompts go in a common location.

5) Validate the source pack

Run validation against the source pack directory before you build the archive:

valdr validate-pack "$HOME/.valdr/valdr-packs/my-team"

Or, for a repo-local pack:

valdr validate-pack "$PWD/.valdr/valdr-packs/my-team"

Validation checks that:

• pack.yaml has schemaVersion: 1.0 and valid includes
• Every agent has exactly one role: core capability
• Capability IDs referenced in .agent.yaml match actual <!--<capability>--> annotations
• Prompt keys referenced in .agent.yaml match actual <!--<prompt>--> annotations
• Tags are lowercase, comma-separated, and deduplicated
• No obvious manifest wiring errors exist before import

6) Generate the archive

Build the importable archive from the same source directory:

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

Or, for a repo-local pack:

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

The generated .valdr-pack.tar.gz archive is the file you import through the UI.

7) Import via UI

Import your pack through Settings > Packs in the Valdr UI:

1. Validate the source pack directory
2. Generate the .valdr-pack.tar.gz archive
3. Upload the archive in the Import dialog
4. Review the preflight action plan — every entity shows its status (create, overwrite, unchanged, skip)
5. Resolve conflicts if entities already exist — choose to overwrite or skip per entity
6. Commit the import

The import is atomic — either everything succeeds or nothing changes.

8) Verify

After import, confirm your entities are visible:

• Agents — Check the Agents page in the UI or run pm_agent list
• Capabilities — Check Capabilities page or run pm_capability list
• Prompts — Check Prompts page or run pm_prompt list

Updating an existing pack

When you need to update agents or capabilities:

1. Edit the source Markdown and YAML files in ~/.valdr/valdr-packs/<pack-name> or ./.valdr/valdr-packs/<pack-name>
2. Re-run valdr validate-pack <pack-dir>
3. Re-run valdr generate-valdr-pack <pack-dir> --output <archive>
4. Re-import the archive

The preflight plan shows which entities changed — overwrite only what’s updated.

The content hash comparison means unchanged entities are automatically skipped.

Tips

• Prefer the default source directories — Nikol already knows to look in ~/.valdr/valdr-packs and ./.valdr/valdr-packs
• Keep capabilities focused — one capability per domain, not one giant file
• Use hot-loading — mark non-core capabilities as hot-load: true to keep context lean
• Version your pack — update the version field in pack.yaml when making changes
• Validate before generating — catch wiring issues before you build and import the archive
• Reuse shared prompts — extract common patterns into shared prompts that multiple agents reference
• Let Nikol do the repetitive parts — even on the manual path, Nikol can scaffold the manifest, draft a capability, or validate wiring on demand

Next steps

• Author your first pack the fast way — start a Nikol session and have it scaffold the manifest, agents, and capabilities for you.
• Understand what Nikol writes — see how Valdr composes capabilities into predictable system prompts in Prompt ordering.