Multi-agent coordination via the meridian CLI. Use this skill whenever you need to delegate work to another agent, run tasks in parallel, check on spawn progress, coordinate multiple agents, or inspect spawn outputs. Also use when you want to route work to a specific model or provider.
See meridian-cli for output mode discipline and JSON parsing expectations.
Spawns block until the spawn completes, then returns the result. The preferred pattern is to spawn these in the background so you get a completion notification later.
meridian spawn -a agent -p "task description" --desc "Implement step 1"
meridian spawn -a agent2 -p "task2 description" --desc "Review step 1"
# → blocks until done, returns terminal status with spawn_id
# you can then wait for them both to complete with (make sure to spawn all the spawns you want to wait for before calling this):
meridian spawn wait p107 p108
Two ways to spawn, depending on whether you want a reusable configuration or a one-off:
-a (agent profile) — use when a profile exists for the role. The profile encodes model, system prompt, skills, and permissions, so you don't repeat yourself across spawns:
meridian spawn -a reviewer -p "Review this change"
-m (direct model) — use for one-off tasks where no profile fits, or when you want a specific model without the rest of a profile's configuration:
meridian spawn -m MODEL -p "Implement the fix"
You can combine both to override a profile's default model, but you usually shouldn't — the profile author already chose the right model for the role:
meridian spawn -a reviewer -m sonnet -p "Quick review"
Long inline prompts hit shell-quoting bugs faster than you'd expect. Backticks, dollar signs, unbalanced quotes, zsh history expansion, and heredoc edge cases can silently corrupt the prompt. For anything multi-paragraph or containing code, pipe from stdin (cat prompt.md | meridian spawn ...) or pass --prompt-file. Both avoid shell parsing entirely, so the prompt bytes are read exactly as written. Reserve inline -p for short literal prompts.
Use the prompt input mode that matches prompt complexity:
# Short inline
meridian spawn -a reviewer -p 'review the auth diff'
# Stdin pipe (for long prompts assembled from files or scripts)
cat $MERIDIAN_WORK_DIR/prompt.md | meridian spawn -a coder
# Explicit file flag (for prompts that already exist on disk)
meridian spawn -a coder --prompt-file $MERIDIAN_WORK_DIR/plan/phase-2.md
# Prompt from file + multiple context files
meridian spawn -a coder --prompt-file $MERIDIAN_WORK_DIR/plan/phase-2.md \
-f src/auth/tokens.py \
-f src/auth/middleware.py \
-f tests/test_auth.py
Pass reference files with -f so the spawned agent starts with the context it needs instead of exploring from scratch:
meridian spawn -a agent -p "Implement fix" \
-f plans/step.md \
-f src/module.py
Run meridian models list to see available models with their strengths and cost tiers. Run meridian models -h for the full model management surface. Run meridian mars list to see available agent profiles and skills. Model and agent preferences belong in your project's agent profiles, meridian config, or project docs (CLAUDE.md, AGENTS.md) — hardcoding them into spawn commands makes them invisible to meridian config show, impossible to change project-wide, and silently divergent from profile defaults.
To create or edit agent profiles, load the agent-creator skill. To create or edit skill files, load the skill-creator skill.
Attach spawns to a work item so they're grouped on the dashboard and traceable later. Without a work item, spawns are orphaned IDs that are hard to find or make sense of after the fact.
# Spawns automatically inherit the active work item
meridian spawn -a agent --desc "Implement step 2" -p "..."
# Or attach explicitly (useful for automation or cross-cutting tasks)
meridian spawn -a reviewer --work auth-refactor --desc "Review step 1" -p "..."
Use --desc to give spawns a human-readable label — it shows up in meridian work and spawn list, so you're not staring at bare spawn IDs.
For work item lifecycle (creating, switching, updating, completing, and dashboard), see the /meridian-work-coordination skill.
Use your harness's native background execution to run multiple spawns concurrently. Each spawn runs in foreground (blocking), but your harness runs them in parallel:
# Launch these concurrently using your harness's background/parallel execution
meridian spawn -a agent -p "Step A" --desc "Step A"
meridian spawn -a agent -p "Step B" --desc "Step B"
# Each blocks until its spawn completes, then returns results.
Track spawns by their ID. For situational awareness, use the work dashboard — it shows active work items with their attached spawns:
meridian work
See meridian-cli for crash-only recovery behavior and reconciliation details.
To reattach to a spawn still running from a previous session, use meridian spawn wait <spawn_id>.
To see what a spawn spawned, use spawn children:
meridian spawn children p107 # list direct children of p107
spawn show also displays the parent ID when a spawn was created by another spawn.
If a spawn returns "status": "failed", read the report via spawn show SPAWN_ID — it usually contains the error or the agent's last output. For deeper investigation, see ../meridian-cli/resources/debugging.md for log inspection.
Spawns share filesystem directories for exchanging data without relying on conversation context (which does not survive across spawn boundaries). See meridian-cli for environment variable definitions.
See the /meridian-work-coordination skill for when to use which.
Use spawn files to stage exactly what a spawn changed — this avoids accidentally staging unrelated files that happened to be modified:
meridian spawn files p107 | xargs git add
meridian spawn files p107 -0 | xargs -0 git add # paths with spaces
Use {{KEY}} placeholders in prompts, replaced at launch time with --prompt-var. This keeps variable content visible in prompt logs and --dry-run output, where inline string interpolation would already be resolved:
meridian spawn -a coder \
-p "Implement {{TASK}} following {{CONSTRAINT}}" \
--prompt-var TASK=auth-refactor \
--prompt-var CONSTRAINT="no direct DB access"
For continue/fork, cancel, stats, permission tiers, reports, and dry-run, see resources/advanced-commands.md.
For troubleshooting strange behavior, see ../meridian-cli/resources/debugging.md.
For project defaults (model, agent, permissions, timeouts), see ../meridian-cli/resources/configuration.md.