system-spawn-agent

name	system/spawn-agent
description	Spawn a persistent named tmuxllm agent (background supervisor + tmux pane + inbox/outbox). Wraps `tmuxllm spawn` with the conventional flags for installing a per-agent persona and a one-shot bootstrap task. Use when you want a long-running agent that holds shell state across tasks (calendar, email, monitor, code-review) — not for one-shot ad-hoc work, where `tmuxllm "<goal>"` is correct.
capabilities	["shell","agent-spawn","agent-send"]

system/spawn-agent

Create a persistent agent. Unlike tmuxllm "<goal>" which spawns a fresh ephemeral agent that exits at done(), a persistent agent has its own tmux pane that holds shell state (env vars, working directory, background processes, history) across many tasks.

When to apply

• The user wants a named long-running agent: "set up a calendar agent", "give me a monitor that watches X", "spawn a code-review agent for this repo"
• The user is building a multi-agent workflow where one or more agents need to outlive their first task

Don't apply for one-shot work — tmuxllm "<goal>" is the right surface for "do this one thing right now."

Inputs

Required:

• name — the agent's identity. Lowercase, alphanumerics + hyphens + underscores, must start with an alphanumeric character. Used as the agent's directory name and as the argument to tmuxllm send / wait / kill <name>.

Optional:

• profile — provider profile (openrouter-gemini-3.1-flash-lite, openrouter-sonnet, claude-opus, etc.). Defaults to whatever TMUXLLM_PROFILE is set to (system default otherwise).
• persona_file — path to a markdown file installed at <agent-dir>/AGENTS.md. The supervisor threads this as the agent's system-prompt persona on every per-task tmuxllm invocation. Use this to give the agent a role-shaped voice ("you are a calendar assistant with access to gcalcli, …").
• bootstrap_goal — first task to queue in the agent's inbox at spawn time. The agent processes it on supervisor startup before any external tmuxllm send call.

Procedure

1. Build the spawn command:

   tmuxllm spawn <name> \
       [--profile <profile>] \
       [--persona-file <persona_file>] \
       [--bootstrap "<bootstrap_goal>"]
   

2. Run it. Spawn refuses if <name> is already alive.
3. The output prints the agent name, supervisor pid, tmux pane id, tmux socket, and (if bootstrap given) the task id.

Verification

After spawn returns rc=0:

• tmuxllm list shows <name> with alive=yes
• tmuxllm send <name> "<probe>" returns a task id (sanity ping; not required for the spawn itself to succeed)

Failure modes

• Name collision — agent <name> is already running. Pick a different name or tmuxllm kill <name> first.
• Persona file missing — caller bug. The skill validates before spawning so you don't get a half-spawned agent.
• tmux not on PATH — failed to spawn tmux session: …. Install tmux >= 3.2.

Composition notes

This skill is a thin wrapper around tmuxllm spawn. It exists to make "spawn an agent" discoverable in tmuxllm-skill list and to crystallize the recursion pattern (skills create agents). For programmatic use, the underlying CLI verb is fine — tmuxllm spawn <name> ... works without going through the skill layer.

The skill becomes load-bearing when composed with system/spawn-archetype (future): that skill picks a known role template (calendar / email / code-review), composes a persona, and calls system/spawn-agent to do the actual spawn.