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:

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

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.

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:

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"

Import preflight

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

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:

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

Next steps

Read Agent definitions next to understand how .agent.yaml files connect pack source to runnable agents, or use Authoring workflow when you are ready to build and import a pack.