| name | system/spawn-archetype |
| description | Spawn a persistent named agent from a known role archetype (calendar, email, code-review, monitor, scheduler). Reads the archetype's markdown template, asks the user the domain questions it names, composes a role-shaped persona, then calls `system/spawn-agent` to spawn with that persona installed. Use when the user says "set up a calendar agent", "give me an email assistant", "spawn a code-review bot", etc. |
| capabilities | ["shell","skill-invoke","agent-spawn"] |
system/spawn-archetype
Compose a persistent agent from a role template. This skill is the LLM-
mediated layer over system/spawn-agent: it picks the right archetype,
gathers personalization (which calendar account, which repo, what to
monitor), writes the composed persona to disk, and invokes the lower-
level skill to do the actual spawn.
The work happens in five steps. Substrate-pure throughout — every
mechanic is cat, write a file, run a command.
When to apply
User says any variant of "set up a <role> agent" where <role>
matches an archetype on disk. Bundled archetypes (ls $TMUXLLM_SKILL_DIR/archetypes/):
- calendar — calendar assistant (gcalcli for Google Calendar)
- email — email assistant (mutt / himalaya / gmail-cli)
- code-review — code review assistant (gh + git + rg)
- monitor — log/metric watcher (tail / grep / kubectl / datadog-ci)
- scheduler — task scheduler (at / crontab / launchd / systemd-timer)
If the user's intent matches none of these, this is the wrong skill —
fall back to system/spawn-agent with a hand-composed persona.
Procedure
Step 1 — Pick the archetype
ls $TMUXLLM_SKILL_DIR/archetypes/
Match the user's intent to one of the listed archetype files. If
ambiguous, ask the user which fits. Don't invent an archetype that
doesn't exist as a file.
Step 2 — Read the template
cat $TMUXLLM_SKILL_DIR/archetypes/<choice>.md
The template names: role description, recommended profile, CLIs the
agent should know, domain questions to ask the user, and a persona
template with <PLACEHOLDER> slots.
Step 3 — Gather personalization
Ask the user the domain questions the template names — only those
questions, kept short. Examples: "which Google account?", "which repo?",
"what should I watch?".
Don't ask questions the template doesn't name. The archetype is the
authority on what's needed; over-asking is the most common failure mode
on smaller models.
Step 4 — Compose and save the persona
Substitute the user's answers into the template's persona section.
Save the composed persona to a temp path:
PERSONA="$(mktemp -t spawn-archetype.XXXXXX).md"
cat > "$PERSONA" <<'PERSONA_EOF'
<composed persona text — keep concise, ~30 lines max>
PERSONA_EOF
Use the helper-script pattern for any long content (see CLAUDE.md /
AGENTS.md pane-discipline notes — never cat large bodies directly
into the pane).
Step 5 — Spawn
tmuxllm-skill run system/spawn-agent <agent-name> \
--profile <recommended-profile-from-archetype> \
--persona-file "$PERSONA"
If the user specified a bootstrap task, append --bootstrap "<goal>".
Verify with tmuxllm list showing the agent alive, then call
done(success) with a one-line summary that names the agent and the
archetype it was spawned from. The user can then tmuxllm send <name> "<task>" themselves.
Failure modes
- Archetype not found — match the user's intent to an existing
archetype file. Don't fabricate a
<choice>.md that's missing.
- Underspecified personalization — if the user can't answer a
template's domain question, that's a sign they want a different
archetype OR they want hand-composition via
system/spawn-agent.
- Spawn refuses (name collision) —
tmuxllm kill <name> first or
pick a fresh name. Ask the user; don't decide.
