tmux-pilot-role-authoringlisted

Create or edit a tmux-pilot subagent role - the YAML role entry in tmux-pilot.config.yaml (models, thinking, provider, harness, lifecycle guards, worktree, widget style) plus the optional Markdown agent-definition document with YAML frontmatter that carries the role's instructions. Use when adding a new role, tuning an existing role's routing or guards, wiring a role to a non-pi harness (cmd, claude-code, codex, hermes), or writing or fixing an agent-definition .md that a spawn rejects. Triggers on tmux-pilot.config.yaml, subagent-roles, agent-definition, lifecycle-guards, or role authoring tasks.
r3b1s/pi-dev-skills · ★ 1 · AI & Automation · score 65

Install: claude install-skill r3b1s/pi-dev-skills

# tmux-pilot Role Authoring A role is two artifacts: 1. A **YAML entry** under `subagent-roles.<name>` in the entry config file — `$PI_CODING_AGENT_DIR/tmux-pilot.config.yaml`, falling back to `~/.pi/agent/tmux-pilot.config.yaml`. 2. An optional **agent-definition Markdown document** (YAML frontmatter + instruction body) referenced by the role's `agent-definition` key. Config is read at **spawn time** — edits apply to the next spawn, never to a running agent (widget-style is captured on the record at spawn; startup-scoped widget settings apply next session). Role names are matched **case-insensitively** at spawn. The canonical, exhaustively commented schema reference is `tmux-pilot.config.example.yaml` in the tmux-pilot repo. Templates: [resources/role-config-template.yaml](resources/role-config-template.yaml) and [resources/agent-definition-template.md](resources/agent-definition-template.md). ## Naming and schema rules (hard cutover — no legacy keys) Every tmux-pilot-owned key is **lower-kebab-case**; controlled enum values too (`overlay`, `above-editor`). External identifiers keep their spelling (model IDs, provider IDs like `opencode-go`, harness IDs, role names, tmux keys like `C-c`). Legacy camelCase keys (`agentDef`, `guards`, `new-worktree`, `config-dir`, `maxTurns`, `stopKeyCombo`, …) are **not recognized** — they warn and are ignored. Unknown keys at known scopes warn; role names, model IDs, harness IDs stay open and never warn. ## Part 1 — the YAML