# Authoring workflow
The fastest way to build a Valdr pack is to let an orchestrator do the wiring for you. **[Nikol](/valdr/docs/valdr-packs/what-comes-with-valdr/starter-packs/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](#author-with-nikol-recommended)** — recommended. Minimal manual work; you describe the behavior and review the result.
- **[Build a pack by hand](#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.

{{% steps %}}

### Open Nikol

Open the [Orchestrator UI](/valdr/docs/ui/orchestrator/) and choose **Nikol**, or launch an agent session with the handle `nikol`. From Claude Code or Codex CLI, use the [`valdr-orchestrator`](/valdr/docs/skills/valdr-orchestrator/) skill and name the handle:

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

### Describe the behavior, not the files

Tell Nikol what the agent or capability should help users accomplish, the boundaries it must respect, and the mistakes it must avoid. Nikol first inspects your existing agents, prompts, and capabilities so it reuses what you already have instead of creating duplicates.

### Let Nikol draft the pack

Nikol chooses the right shape — agent identity, hot-loaded workflow, shared capability, prompt, or manifest change — then writes `pack.yaml`, the `.agent.yaml` definitions, and the annotated Markdown into one of the default source directories (`~/.valdr/valdr-packs/<pack>` or `./.valdr/valdr-packs/<pack>`).

### Review, validate, import

Nikol validates the manifest, prompt resolution, and capability links before anything is imported. Review the drafted files, then import through **Settings > Packs**. Everything Nikol produces is a plain file you can read, edit, version, and re-run — no black box.

{{% /steps %}}

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:

| Spec | Defines | Key rules |
|------|---------|-----------|
| **PACK-SPEC** | `pack.yaml` manifest format | `schemaVersion`, `includes`, discovery rules |
| **AGENT-SPEC** | `.agent.yaml` agent definitions | Handle, kind, capabilities, prompts, roles |
| **PROMPT-SPEC** | Markdown annotation format | `<!--<capability>-->` and `<!--<prompt>-->` tags |

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

```bash
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:

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

```yaml
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:**
```markdown
<!--<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:**
```markdown
<!--<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:

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

Or, for a repo-local pack:

```bash
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:

```bash
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:

```bash
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](/valdr/docs/valdr-packs/what-comes-with-valdr/starter-packs/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](/valdr/docs/valdr-packs/building-your-own/prompt-ordering/).