Agent skill

Agent Teams

by tmustier in tmustier/pi-agent-teams

Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates.

MITAuto-check passedAgent Workflows

Install Agent Teams

skills CLI
$ npx skills add tmustier/pi-agent-teams --skill agent-teams -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install tmustier/pi-agent-teams agent-teams --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/tmustier/pi-agent-teams.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/agent-teams .claude/skills/agent-teams && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
agent-teams
GitHub stars
110
Token cost
~2.5k tokens
SKILL.md length
688 words
Files
1
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates.

  • The user asks to spawn workers
  • SKILL.md covers Core concepts, UI style (terminology + naming), Spawning teammates and Task management, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Work in parallel with agents

What it does

Agent Teams is an agent skill from tmustier/pi-agent-teams. Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates. Use when the user asks to spawn workers, delegate tasks, work in parallel with agents, or manage a team of workers.

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Agent Workflows, covering Task breakdown and Multi-agent orchestration. The repository describes itself as: Experimental agent swarm extension for Pi. Inspired by Claude agent teams. The licence is MIT.

When your agent uses it

  • The user asks to spawn workers
  • Work in parallel with agents
  • Manage a team of workers

Example prompts

  • “/agent-teams”

What it can do on your machine

Read from SKILL.md and the folder at commit 2c1776d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Agent Teams loads about 2.5k tokens when it runs. Until then it costs about 57 tokens; SKILL.md has 688 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from tmustier/pi-agent-teams at commit 2c1776d, republished under its MIT licence (© tmustier). 688 words, ~2,481 tokens.

Download SKILL.mdSave it as .claude/skills/agent-teams/SKILL.md (or your agent's skills folder).
name
agent-teams
description
Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates. Use when the user asks to spawn workers, delegate tasks, work in parallel with agents, or manage a team of workers.

Agent Teams

Spawn and coordinate teammate agents that work in parallel on shared task lists, communicating via file-based mailboxes. Modeled after Claude Code Agent Teams.

Core concepts

  • Leader (you): orchestrates, delegates, reviews. Runs the /team command and the teams LLM tool.
  • Teammates: child Pi processes that poll for tasks, execute them, and report back. Sessions are named pi agent teams - <role> <name> where <role> depends on the current style (e.g. teammate/comrade/matey).
  • Task list: file-per-task store with statuses (pending/in_progress/completed), owners, and dependency tracking.
  • Mailbox: file-based message queue. Two namespaces: team (DMs, notifications, shutdown) and taskListId (task assignments).

UI style (terminology + naming)

Built-in styles:

  • normal (default): Team leader + Teammate <name>
  • soviet: Chairman + Comrade <name>
  • pirate: Captain + Matey <name>

Configure via PI_TEAMS_STYLE=<name> or /team style <name> (see /team style list).

Custom styles can be added via JSON files under ~/.pi/agent/teams/_styles/<style>.json or bootstrapped with:

  • /team style init <name> [extends <base>]

Spawning teammates

Use the teams tool (LLM-callable) for delegation, task/messaging mutations, lifecycle, and governance:

ActionRequired fieldsNotes
delegatetasksSpawns as needed, creates and assigns tasks.
task_assigntaskId, assigneeAssign/reassign owner.
task_unassigntaskIdClear owner.
task_set_statustaskId, statuspending | in_progress | completed.
task_dep_add / task_dep_rmtaskId, depIdDependency graph edits.
task_dep_lstaskIdDependency/block inspection.
message_dmname, messageMailbox DM. urgent=true interrupts active turns.
message_broadcastmessageMailbox broadcast. urgent=true interrupts active turns.
message_steername, messageRPC steer for running teammate.
member_spawnnameSupports context/workspace/model/thinking/plan options.
member_shutdownname or all=trueGraceful mailbox shutdown request.
member_killnameForce-stop RPC teammate.
member_prune(none)Mark stale workers offline (all=true to force).
team_done(none)End team run: stop teammates, hide widget (all=true to force with in-progress tasks).
plan_approve / plan_rejectnameResolve pending plan approvals (feedback optional for reject).
hooks_policy_get(none)Read team hooks policy (configured + effective).
hooks_policy_setone or more: hookFailureAction, hookMaxReopensPerTask, hookFollowupOwnerUpdate team hooks policy at runtime (hooksPolicyReset=true clears team overrides first).
model_policy_get(none)Inspect teammate model policy and current leader inheritance behavior.
model_policy_checkoptional modelValidate a model override before spawn (<provider>/<modelId> or <modelId>).

Examples:

teams({ action: "delegate", tasks: [{ text: "Implement auth", assignee: "alice" }] })
teams({ action: "task_assign", taskId: "12", assignee: "alice" })
teams({ action: "task_dep_add", taskId: "12", depId: "7" })
teams({ action: "message_broadcast", message: "Sync: finishing this milestone" })
teams({ action: "message_dm", name: "alice", message: "Stop using lib X, use Y instead", urgent: true })
teams({ action: "member_kill", name: "alice" })
teams({ action: "plan_reject", name: "alice", feedback: "Include rollback strategy" })
teams({ action: "hooks_policy_get" })
teams({ action: "hooks_policy_set", hookFailureAction: "reopen_followup", hookMaxReopensPerTask: 2, hookFollowupOwner: "member" })
teams({ action: "model_policy_get" })
teams({ action: "model_policy_check", model: "openai-codex/gpt-5.1-codex-mini" })
teams({ action: "team_done" })

This covers most day-to-day orchestration without slash commands. For nuanced/manual control, use /team ... commands directly.

For more control, use /team spawn:

/team spawn alice              # default: fresh context, shared workspace
/team spawn bob branch shared  # clone leader session context
/team spawn carol fresh worktree  # git worktree isolation
/team spawn dave plan          # plan-required mode (read-only until approved)

Task management

/team task add <text...>                # create a task
/team task add alice: review the API    # create + assign (prefix with name:)
/team task assign <id> <agent>          # assign existing task
/team task unassign <id>                # unassign
/team task list                         # show all tasks with status + deps
/team task show <id>                    # full task details + result
/team task dep add <id> <depId>         # task depends on depId
/team task dep rm <id> <depId>          # remove dependency
/team task dep ls <id>                  # show dependency graph
/team task clear [completed|all]        # delete tasks
/team task use <taskListId>             # switch to a different task list

Teammates auto-claim unassigned, unblocked tasks by default.

Communication

/team dm <name> <msg...>              # direct message to one teammate
/team dm <name> --urgent <msg...>     # urgent DM — interrupts active turn via steering
/team broadcast <msg...>              # message all teammates
/team broadcast --urgent <msg...>     # urgent broadcast — interrupts all active turns
/team send <name> <msg...>            # RPC-based (immediate, for spawned teammates)

Urgent messages (--urgent or urgent=true in tool calls) interrupt a teammate's active turn via steering instead of waiting for idle. Use sparingly — only for time-sensitive coordination like "stop using library X, it's broken".

Teammates can also message each other directly via the team_message tool (with optional urgent flag), with the leader CC'd.

Governance modes

Show full SKILL.md (276 more words)Show less
Delegate mode

Restricts the leader to coordination-only (blocks bash/edit/write tools). Use when you want to force all implementation through teammates.

/team delegate on    # enable
/team delegate off   # disable
Plan approval

Spawning with plan restricts the teammate to read-only tools. After producing a plan, the teammate submits it for leader approval before proceeding.

/team spawn alice plan         # spawn in plan-required mode
/team plan approve alice       # approve plan, teammate gets full tools
/team plan reject alice <feedback...>  # reject, teammate revises

Lifecycle

/team panel                    # interactive overlay with teammate details
/team list                     # show teammates and their state
/team attach list              # discover existing teams under <teamsRoot>
/team attach <teamId> [--claim] # attach this session to an existing team workspace (force takeover with --claim)
/team detach                   # return to this session's own team workspace
/team shutdown                 # stop all teammates (RPC + best-effort manual) (leader session remains active)
/team shutdown <name>          # graceful shutdown (teammate can reject if busy)
/team prune [--all]            # hide stale manual teammates (mark offline in config)
/team kill <name>              # force-terminate one RPC teammate
/team done [--force]           # end run: stop teammates + hide widget
/team cleanup [--force]        # delete team directory, worktrees, and branches
/team gc [--dry-run] [--force] [--max-age-hours=N]  # garbage-collect stale team dirs

When all tasks complete and teammates are idle, the widget shows "All tasks done." with a /team done hint. Teammates reject shutdown requests when they have an active task. Use /team kill <name> to force.

Cleanup

Worktrees and branches are automatically cleaned up on session shutdown and session switch. For manual cleanup:

  • /team cleanup [--force] — removes the current team directory, including git worktrees and associated branches. Reports removal counts.
  • /team gc [--dry-run] [--force] [--max-age-hours=N] — garbage-collects stale team directories older than N hours (default: 24). Skips teams with online members or in-progress tasks. Use --dry-run to preview.

Other commands

/team id       # show team ID, task list ID, paths
/team env <n>  # print env vars for manually spawning a teammate named <n>

Shared task list across sessions

PI_TEAMS_TASK_LIST_ID is primarily worker-side (use it when you start a teammate manually).

The leader switches task lists via:

/team task use my-persistent-list

The chosen task list ID is persisted in config.json. Teammates spawned after the switch inherit the new task list ID; existing teammates need a restart to pick up changes.

Message protocol

Teammates and the leader communicate via JSON messages with a type field:

TypeDirectionPurpose
task_assignmentleader -> teammateNotify of assigned task
idle_notificationteammate -> leaderTeammate finished, no more work
shutdown_requestleader -> teammateAsk to shut down
shutdown_approvedteammate -> leaderWill shut down
shutdown_rejectedteammate -> leaderBusy, can't shut down now
plan_approval_requestteammate -> leaderPlan ready for review
plan_approvedleader -> teammateProceed with implementation
plan_rejectedleader -> teammateRevise plan (includes feedback)
peer_dm_sentteammate -> leaderCC notification of peer message

© tmustier, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/agent-teams of tmustier/pi-agent-teams.

Open the folder on GitHubat commit 2c1776d

Compare with similar skills

Agent Teams next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Agent Teams compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Agent Teams this skilltmustier/pi-agent-teams110—~2.5kAutomated safety check: PassMIT
MemPalace Task HandoffMemPalace/mempalace59k—~1.9kAutomated safety check: PassMIT
agtx One-Shot Project Runnerfynnfluegge/agtx1.7k—~3.8kAutomated safety check: PassApache-2.0
Agtx Task Sweepfynnfluegge/agtx1.7k—~1.7kAutomated safety check: PassApache-2.0
Orca Orchestrationstablyai/orca88k—~916Automated safety check: PassMIT
Cookrjcorwin/cook371—~1.5kAutomated safety check: PassNone

Similar skills

  • MemPalace Task Handoff

    MemPalace/mempalace

    Creates, hands off, claims, executes and closes agent tasks through the MemPalace logstream, with approval of the exact task before it is recorded.

    59k GitHub stars~1.9k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Runs a whole project unattended on an agtx kanban board, decomposing the goal, starting tasks, unblocking workers and merging each result.

    1.7k GitHub stars~3.8k tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed
  • Agtx Task Sweep

    fynnfluegge/agtx

    Breaks a conversation's results into feature-level tasks and pushes them to the agtx kanban board, where each task gets its own worktree and agent session.

    1.7k GitHub stars~1.7k tokensUpdated 7 days ago
    Agent WorkflowsAuto-check passed
  • Orca Orchestration

    stablyai/orca

    Coordinate supervised Orca workers: threaded messages, blocking ask/reply, task dispatch, worker_done/escalation waits, task DAGs, decision gates, coordinator…

    88k GitHub stars~916 tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Cook

    rjcorwin/cook

    Agent orchestration primitives — review loops, repeat passes, parallel races, and task-list progression.

    371 GitHub stars~1.5k tokensUpdated 5 mo ago
    Agent WorkflowsAuto-check passed
  • OMA Multi-Agent Orchestrator

    first-fluke/oh-my-agent

    Splits a complex feature into prioritized tasks, spawns specialist CLI subagents in parallel, tracks them through shared memory and verifies each result.

    1.3k GitHub stars~3.1k tokensUpdated today
    Agent WorkflowsAuto-check passed

Categories

Questions about Agent Teams

What does Agent Teams do?

Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates. Agent Teams is an agent skill from tmustier/pi-agent-teams. Coordinate multi-agent teamwork with shared task lists, mailbox messaging, and long-lived teammates.

When should I use Agent Teams?

Agent Teams fits situations like: the user asks to spawn workers; work in parallel with agents; manage a team of workers.

How do I install Agent Teams in Claude Code?

Run `npx skills add tmustier/pi-agent-teams --skill agent-teams -a claude-code`. Or copy the skill folder (skills/agent-teams in tmustier/pi-agent-teams) into .claude/skills/agent-teams in your project. Claude Code loads it when a task matches its description.

How do I install Agent Teams in Codex?

Run `npx skills add tmustier/pi-agent-teams --skill agent-teams -a codex`. Or copy the skill folder (skills/agent-teams in tmustier/pi-agent-teams) into .agents/skills/agent-teams in your project. Codex loads it when a task matches its description.

Can I use Agent Teams in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tmustier/pi-agent-teams --skill agent-teams -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/agent-teams, .gemini/skills/agent-teams, .github/skills/agent-teams and .opencode/skills/agent-teams in your project.

What does Agent Teams need to run?

SKILL.md names no scripts, command-line tools or credentials: Agent Teams is instructions for the agent only.

Does Agent Teams access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Agent Teams safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Agent Teams use?

Agent Teams is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Agent Teams use?

About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Agent Teams?

Skills that share tags, products or a category with Agent Teams: MemPalace Task Handoff (MemPalace/mempalace, 59k stars), agtx One-Shot Project Runner (fynnfluegge/agtx, 1.7k stars), Agtx Task Sweep (fynnfluegge/agtx, 1.7k stars) and Orca Orchestration (stablyai/orca, 88k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Agent Teams?

tmustier (a GitHub user) maintains it in tmustier/pi-agent-teams, which has 110 GitHub stars. The repository was last updated on June 20, 2026.

Source: tmustier/pi-agent-teams on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.