pi-multi-agent-skill

A minimal, lightweight multi-agent skill and CLI for pi. It needs no extension and adds no tools. Your agent starts other agents, runs them in parallel or in the background, and waits for, steers, stops or resumes them. Any harness or agent that has a shell can use it.

Features

• Small token cost. A subagent extension adds its tool definitions to every request, whether or not your agent delegates anything. With this skill, your agent's context holds only the skill's description, a few dozen tokens, until it decides to delegate. Then it loads SKILL.md, which is about 1.2K tokens and is all it needs for a fully working multi-agent setup. The details of each command stay in separate references that it reads only when needed.
• Everything a subagent tool does, without the tool. Your agent gets the same controls a dedicated extension would give it: start agents, wait for them, steer one with a correction, abort it and keep what it has so far, resume a finished job with a follow-up task, and see what each job is doing. You can run the same commands yourself from a terminal.
• Parallel and background agents. Run a quick question in the foreground, or start several jobs at once and collect their results later.
• Stops when you stop. A foreground agent ends when the command that started it ends: press Esc, cancel the tool call or close the session, and the agent and the commands it was running stop with it, at every level of nesting. Background jobs keep running until they finish or time out.
• Your full pi setup. Each agent loads the same extensions, MCP servers, skills and settings as an interactive pi, and uses your model unless its profile picks another.
• Profiles. They work as in other subagent tools: each one sets an agent's system prompt, model, thinking level and tools.
• Fork your conversation. --fork hands the agent everything you have discussed so far, for tasks that need that context.
• Works outside pi. Claude Code, Codex or any other agent with a shell can run the same commands to delegate work to pi agents.

Install

Install the skill as a pi package from npm:

pi install npm:pi-multi-agent-skill

Or install directly from GitHub:

pi install git:github.com/milanglacier/pi-multi-agent-skill

You can also install the skill with the open skills CLI:

npx skills install milanglacier/pi-multi-agent-skill --global --agent pi

The CLI copies the skill to ~/.agents/skills/multi-agent, which pi reads. You can also link it into pi's skills directory yourself:

ln -s "$PWD/skills/multi-agent" ~/.pi/agent/skills/multi-agent

Requirements: pi and Python 3.9 or later. Nothing else to install.

Usage

Your agent drives the skill on its own, but the commands also work by hand:

multi_agent.py run --profile Explore "Where is the retry policy defined?"
multi_agent.py run --background --name review "Review the error handling in src/server/"
multi_agent.py wait review --timeout 120
multi_agent.py steer review "Skip generated files"
multi_agent.py resume review "Now check the client side"
multi_agent.py list

See skills/multi-agent/references/ for every command and option, how jobs start and stop, the profile format, where state is kept and troubleshooting.

Tests

python3 -m unittest discover tests

The tests use an offline stand-in for pi, so they call no model.

Releases

Set the version in package.json, commit it, and push a matching tag such as v0.1.1. The GitHub workflow runs the tests and publishes to npm. Prerelease versions use the next npm tag; stable versions use latest. The npm trusted publisher is milanglacier/pi-multi-agent-skill with the workflow filename publish.yml and permission to publish directly.

License

MIT