# Pack structure
Valdr pack source is just files: YAML manifests, Markdown capabilities, Markdown prompts, and optional platform-specific outputs. The structure matters because Valdr tooling can discover, validate, package, and import the pack without hand-registering every entity.

## Source directory

Keep the unpacked source directory in one of the locations Valdr tooling already knows how to search:

- `~/.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.

## Manifest

Every pack has a `pack.yaml` manifest at the 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 and role-specific capabilities
  - path: shared
    description: Shared prompts and reusable capability fragments
```

The manifest describes the pack and tells tooling which directories to scan. You do not enumerate every agent, prompt, or capability in `pack.yaml`; discovery happens from the included directories.

## What gets discovered

| Layer | Format | Discovery |
|-------|--------|-----------|
| Pack manifest | `pack.yaml` | Root of each pack |
| Agent definitions | `.agent.yaml` | Inside included directories |
| Capabilities | Annotated Markdown | `<!--<capability>-->` tags |
| Prompts | Annotated Markdown | `<!--<prompt>-->` tags |

This is what makes packs self-describing. The archive can be inspected before import, and Valdr can build a preflight plan without guessing what the pack contains.

## Source, archive, import

Pack source is the editable truth. The generated archive is the distribution artifact. The UI import is the workspace update.

```text
source directory
  -> validate
  -> generate .valdr-pack.tar.gz
  -> import through Settings > Packs
  -> review preflight
  -> commit changes
```

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

## Validate and generate

Use the Valdr CLI to validate the source directory and build the archive:

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

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

## Import preflight

Packs are imported through **Settings > Packs** in the Valdr UI.

{{< thumbcard src="/images/ui/valdr-packs/pack-import.png" alt="Import Valdr Pack dialog showing preflight action plan" caption="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 does not exist yet
- **Overwrite** - Existing entity that will be updated
- **Unchanged** - Entity already matches, no action needed
- **Skip** - Conflict resolution chose to skip

The important part is that import is inspectable. You see what will change before the workspace changes.

## Multi-platform output

Some packs also generate platform-specific files from canonical source:

| Platform | Output format | Directory |
|----------|---------------|-----------|
| Claude Code | Markdown commands | `claude/commands/` |
| Codex CLI | Prompt files | `codex/prompts/` |
| Gemini CLI | TOML commands | `gemini/commands/` |
| Cursor | Markdown commands | `cursor/commands/` |

Those outputs are useful for tool compatibility, but the pack source remains the canonical place to maintain the behavior.

## Next steps

Read [Agent definitions](../agent-definitions/) next to understand how `.agent.yaml` files connect pack source to runnable agents, or use [Authoring workflow](../../building-your-own/workflow/) when you are ready to build and import a pack.