agent-team
Use when working in a team of AI agents run by a human director - as the manager, a builder or a reviewer - in separate sessions, threads or machines, with Claude Code and Codex together and a shared work board (WORKBOARD.md). Use when briefing, assigning, building, reviewing, assessing review findings, merging, escalating a decision, or handing off work between agents, and when a board's first line names the agent-team skill.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zegrt--agent-team)HTML
<a href="/listings/zegrt--agent-team"><img src="/api/listings/zegrt--agent-team/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Clone it once per machine and link it into each tool's skill folder.
**Mac** (Linux should work the same way, but is untested)
git clone https://github.com/zegrt/agent-team.git ~/agent-team mkdir -p ~/.claude/skills ~/.agents/skills ln -s ~/agent-team ~/.claude/skills/agent-team # Claude Code ln -s ~/agent-team ~/.agents/skills/agent-team # Codex
**Windows** (PowerShell; not tested yet)
$clone = "C:\path\to\agent-team" git clone https://github.com/zegrt/agent-team.git $clone New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills", "$HOME\.agents\skills" | Out-Null New-Item -ItemType Junction -Path "$HOME\.claude\skills\agent-team" -Target $clone New-Item -ItemType Junction -Path "$HOME\.agents\skills\agent-team" -Target $clone
A junction needs a local drive. If the clone is on a network share, use `-ItemType SymbolicLink` instead (needs Developer Mode or an admin shell).
> [!NOTE] > For Codex, use `~/.agents/skills`, not `~/.codex/skills`. Only the first is documented, and a skill in both > folders can show up twice.
Use it in a project
1. Copy [`templates/BOARD.md`](templates/BOARD.md) into the project as `WORKBOARD.md`. Its first line points every agent to this skill. 2. Add one line to the project's `CLAUDE.md` or `AGENTS.md`: `Read WORKBOARD.md first.`
That's it. Agents load the skill on their own when they do team work. To force it, type `/agent-team` in Claude Code, or say "use the agent-team skill" in Codex.
Optional: the reminder after a summary
When a long conversation is summarised, an agent can lose the rules. The hook tells it to re-read the skill and trust the board over its memory.
- **Claude Code** (tested): merge [`hooks/claude-settings.json`](hooks/claude-settings.json) into `~/.claude/settings.json`. - **Codex** (not tested yet; Codex 0.129 or later): merge [`hooks/codex-hooks.json`](hooks/codex-hooks.json) into `~/.codex/hooks.json` and set `[features] hooks = true` in `~/.codex/config.toml`. Check it fires before relying on it.
The hook script needs bash, so on Windows it needs Git Bash.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 109 lines
- ---
- name: agent-team
- description: Use when working in a team of AI agents run by a human director - as the manager, a builder or a reviewer - in separate sessions, threads or machines, with Claude Code and Codex together and a shared work board (WORKBOARD.md). Use when briefing, assigning, building, reviewing, assessing review findings, merging, escalating a decision, or handing off work between agents, and when a board's first line names the agent-team skill.
- ---
- # Agent team
- One director, one manager, builders and reviewers, each in its own session; one team per board. The board is the record; messages only
- point to it. The checks live in forms (`templates/`); the judgment calls live in cards (`RULES.md`). This file is the
- start; read the form or card it points to when you reach that step. `<skill>` below is this skill's folder.
- ## Every session, first
- 1. `git pull --ff-only` in this skill's folder, then pull the project. If you can't (no network, a sandbox), say so
- to the manager and go on with what you have.
- 2. Read the board, your own handoff if you have one (`git show origin/worker-<you>:workers/<you>.md`) and the
- director's profile, if the board names one.
- 3. Check your folder is clean and on the branch your task names. If the folder is shared and your task has its own
- branch, make your own worktree for it (see Builder); if you can't, ask the manager. If it is dirty or on a branch
- you can't explain, stop and ask the manager. Never switch branches in a folder someone else works in (`team.worktree`).
- 4. After a summary or a resume you are a new session: trust the board and `git log` over your memory, and re-read this
- file.
- Precedence: a live instruction from the director, then the board, then the director's profile, then this skill. The
- manager writes any live instruction onto the board straight away. If a live instruction goes against a rule here (for
- example "one more quick fix" after two failed rounds), don't follow it yet: put it on the board as "pending: breaks
- <rule>, asked director", tell the director plainly which rule it breaks and why the rule exists, give your
- recommendation, and act on the answer. Nobody acts on a pending line.
- ## Size first
- Every task has a size, stated in plain words on its row, so the director can overrule it. If it grows, stop, say so,
- and step up a size. Judge by three facts: gaps in what the director asked for; anything irreversible or
- outward-facing; how much it touches.
- - **Small** (pointers, typos, board edits): the manager does it and says so. No brief and no independent review, but
- any approval the board requires still applies.
- - **Content:** brief, builder, one independent review, the director's approval.
- - **Design** (structure, a new approach): a written plan to the director first. Don't assign, queue or start the build
- until the director approves the plan; then build it as Content.
- ## Your role
- **Manager.** Only you edit the board.
- - Write every task, decision and correction on the board first, commit and push, then message in a shape from
- `templates/MESSAGES.md`, never with the correction in it (`board.one-source`).
- - A building task's brief is frozen: a change holds and restarts it, or becomes a new task; a hold is the only
- message a building task gets. Files an open task lists are its own: change them through it or after it
- (`task.change`).
- - Live work first: a correction from live work goes ahead of improvement work (`team.live-first`).
- - Keep about 3 agents active; add one only while the director keeps up with reviewing (`team.size`).
- - Brief Content and Design tasks with `templates/BRIEF.md`, saved as `briefs/<id>.md`. Assign nothing whose Files
- overlap an open task. Builder and reviewer are never the same agent.
- - When a review lands, route every finding before any fix (`review.assess`). After fixes, the reviewer re-checks.
- - Two failed rounds on the same thing: stop and rewrite the brief (`review.restart`).
- - Before asking for approval: `python3 <skill>/scripts/team.py rehearse <id> -- <check command>` (latest main merged
- into a throwaway copy, never the builder's branch). After the director approves, one task at a time:
- `team.py merge <id>` (merges the task and its review, moves `approved`, deletes both branches), then set the row
- to merged. If the script can't run, `team.py steps` lists the same steps by hand (`team.manager`).
- - Status and questions to the director use the forms in `templates/MESSAGES.md`; `team.py status` gives each task's
- state and hash (`decide.escalate`).
- - A quiet worker is not a dead one: ask the director to wake it; never reassign its task (`team.unreachable`).
- **Builder.**
- - One task per run. Do only the brief; anything else you notice goes in your report under Noticed. When it is done,
- report, push, send the manager `report in` and end the run. A second task, even "while you're at it", waits until the manager puts it on the
- board for you: decline it plainly and say how it can still get done (`task.change`).
- - Work in your own worktree on the task's branch: if your folder is shared, make it yourself and say where it is
- (`git worktree add ../<project>-<id> -b <branch>` for a new branch, without `-b` if the branch exists). Check the
- branch before every commit.
- - Never edit or remove a test or check to make it pass.
- - Done means the brief's checks were run and their output is in your report. Write it with `templates/REPORT.md` as
- `reports/<id>.md` on the task branch; the status is one of four (done, done with concerns, needs info, blocked), and
- silence is not a status.
- - Check your own work before reporting, always: run the brief's checks and look at the result. That check is not the
- review. The independent review is never yours, even if asked: a builder's own review counts for nothing.
- **Reviewer.** Start clean: read the brief and the work, not the builder's report (`reports/<id>.md`). Write the review
- with `templates/REVIEW.md` as `reviews/<id>.md`, and commit it only to your own branch, `review-<id>`, made from main
- so it holds nothing but your review. Read the work with `git diff origin/main...origin/<branch>`; to run checks, use a
- detached worktree (`git worktree add --detach ../<project>-check-<id> origin/<branch>`). Ask what is missing. Change
- nothing else; never commit to the task branch or main.
- **Everyone.** Push only to your own branches, as the board's "Where files go" table says; only the manager commits to
- main. A builder's or reviewer's run ends with one line to the manager, `report in: <id>, <status>, <where the report
- is>` (`templates/MESSAGES.md`). Reports go to the manager, never to the director, even when the director asks in your
- session; tell the director it went to the manager. No one reads your own thread: a question goes to the manager as
- `report in` with status needs info, and the run's last message is that line, not a summary. Update and push your handoff (`templates/HANDOFF.md`) at the end of each day's work. Stop and ask before anything irreversible or outward-facing (seen outside the
- team: publishing, sending, deleting others' work; pushing your own branch is neither).
- ## Red flags
- What agents said in the tests, and what to do instead:
- | They said | Instead |
- |---|---|
- | "The message is what gets the work moving" | The board line takes a minute. Board first, then "board updated, pull". |
- | "I've added the new requirements to the brief; builder, pull" (task building) | A building brief is frozen: finish then a new task, or hold and restart. |
- | "I'll change that one cell when I can edit again" | After never comes for the next session. Board first. |
- | "Queue task 24 for win-claude when they're free" (a restructure, no plan yet) | Design waits for an approved plan. Nothing is assigned before it. |
- | "A worker builds it rather than me, so my review stays independent" (a one-word fix) | Small: the manager does it and says so. |
- | "Please assign me a separate worktree" | Make your own worktree and say where it is. |
- | "If win-claude hasn't reported by 16:30, may I give T14 to mac-codex?" | A quiet worker is not a dead one. Ask the director to wake it. |
- | "Dana's instruction takes precedence over the normal restart rule" | Say which rule it breaks, recommend, then act on the answer. |
- ## Cards
- Read `RULES.md` when a step names one: `board.one-source`, `task.size`, `task.change`, `review.assess`, `review.restart`,
- `decide.escalate`, `team.worktree`, `team.unreachable`, `team.live-first`, `team.manager`, `team.size`.
README.md · README · 180 lines
- # agent-team
- **Rules for running a team of AI agents without the chaos.** Made by [XERO WORKS](https://xeroworks.org).
- One person directs. One agent manages. Other agents build and review, each in its own session, on one machine or
- several, with Claude Code and Codex mixed. `agent-team` is a skill that gives every one of them the same rules, so
- work doesn't get lost between messages, nobody reviews their own work, and the director only gets asked what
- actually needs them.
- [](https://xeroworks.org)
- [](LICENSE)
- 
- 
- ## Why
- Running several agents at once fails in the same few ways, again and again:
- - A correction goes out in a chat message, half the team misses it, and nobody can find it after a summary.
- - A builder "reviews" its own work, and calls it done without running the checks.
- - Review findings get fixed one by one until the task has doubled, or a finding is quietly dropped.
- - Two agents share a folder, one switches branches, and the other's next commit lands in the wrong place.
- - The director gets a vague status update, or an open question with no recommendation.
- Every rule here comes from one of those failures, corrected by a real director on a real project, and each rule
- says why it exists and where it came from.
- ## How it works
- **The board is the record.** Each project keeps a `WORKBOARD.md`: tasks, decisions, corrections. Only the manager
- edits it. Messages between agents only point to it ("board updated, pull: task 12"), so nothing lives only in a
- chat.
- **Every task has a size.** Small (the manager just does it), Content (a brief, a builder, an independent review,
- the director's approval) or Design (a written plan first, approved before anything is built).
- **Every task has a state, and a running task doesn't move under its builder.** Once a builder starts, its brief is
- frozen. A change either holds the task and restarts it from a new brief, or becomes a new task.
- ```mermaid
- flowchart LR
- open --> building --> built --> R[in review] --> reviewed --> approved --> merged
- building -. change makes the work wrong .-> held -. new brief .-> building
- ```
- **Each agent writes only to its own branch.** The builder's work and report go on the task branch, the reviewer's
- review on `review-<id>`, each agent's handoff on `worker-<name>`. Only the manager touches main, and it merges one
- approved task at a time.
- **Three shapes for three kinds of rule.** Judgment calls are short cards with a Why and a Basis (`RULES.md`).
- Anything checkable is a field in a form (`templates/`), so it can't be skipped. Mechanical chores are a script
- (`scripts/team.py`), so they run the same way every time.
- ## What's inside
- | Path | What it is |
- |---|---|
- | [`SKILL.md`](SKILL.md) | The entry point: what every session does first, the sizes, and each role's steps |
- | [`RULES.md`](RULES.md) | The judgment cards: rule, why, basis, scope |
- | [`templates/`](templates) | The board, a brief, the builder's report, a review, a handoff, and the message forms |
- | [`scripts/team.py`](scripts/team.py) | `status`, `rehearse`, `merge` and `steps`: the chores, scripted |
- | [`hooks/`](hooks) | Optional: reminds an agent of the rules after its conversation is summarised |
- | [`inbox/`](inbox) | Where other projects send corrections for the skill |
- | [`tests/`](tests) | The scenarios, the test harness and every result |
- | [`docs/DESIGN.md`](docs/DESIGN.md) | Why it is shaped this way, and its sources |
- ## Install
- Clone it once per machine and link it into each tool's skill folder.
- **Mac** (Linux should work the same way, but is untested)
- ```sh
- git clone https://github.com/zegrt/agent-team.git ~/agent-team
- mkdir -p ~/.claude/skills ~/.agents/skills
- ln -s ~/agent-team ~/.claude/skills/agent-team # Claude Code
- ln -s ~/agent-team ~/.agents/skills/agent-team # Codex
- ```
- **Windows** (PowerShell; not tested yet)
- ```powershell
- $clone = "C:\path\to\agent-team"
- git clone https://github.com/zegrt/agent-team.git $clone
- New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills", "$HOME\.agents\skills" | Out-Null
- New-Item -ItemType Junction -Path "$HOME\.claude\skills\agent-team" -Target $clone
- New-Item -ItemType Junction -Path "$HOME\.agents\skills\agent-team" -Target $clone
- ```
- A junction needs a local drive. If the clone is on a network share, use `-ItemType SymbolicLink` instead (needs
- Developer Mode or an admin shell).
- > [!NOTE]
- > For Codex, use `~/.agents/skills`, not `~/.codex/skills`. Only the first is documented, and a skill in both
- > folders can show up twice.
- ### Use it in a project
- 1. Copy [`templates/BOARD.md`](templates/BOARD.md) into the project as `WORKBOARD.md`. Its first line points every
- agent to this skill.
- 2. Add one line to the project's `CLAUDE.md` or `AGENTS.md`: `Read WORKBOARD.md first.`
- That's it. Agents load the skill on their own when they do team work. To force it, type `/agent-team` in Claude
- Code, or say "use the agent-team skill" in Codex.
- ### Optional: the reminder after a summary
- When a long conversation is summarised, an agent can lose the rules. The hook tells it to re-read the skill and
- trust the board over its memory.
- - **Claude Code** (tested): merge [`hooks/claude-settings.json`](hooks/claude-settings.json) into
- `~/.claude/settings.json`.
- - **Codex** (not tested yet; Codex 0.129 or later): merge [`hooks/codex-hooks.json`](hooks/codex-hooks.json) into
- `~/.codex/hooks.json` and set `[features] hooks = true` in `~/.codex/config.toml`. Check it fires before relying
- on it.
- The hook script needs bash, so on Windows it needs Git Bash.
- ## The script
- Run from the project's main folder (on Windows, use `python` instead of `python3`):
- ```sh
- python3 ~/agent-team/scripts/team.py status # every task: state, branch @ hash, report, review
- python3 ~/agent-team/scripts/team.py rehearse 12 -- npm test # merge latest main into a throwaway copy, run the check
- python3 ~/agent-team/scripts/team.py merge 12 # only if the board says approved
- python3 ~/agent-team/scripts/team.py steps # the merge steps, to do by hand
- ```
- It uses only the Python standard library and never edits the board.
- ## Does it work?
- Every rule was tested the same way: fresh agents get a real situation, with and without the skill, and a separate
- grader scores each answer blind against a rubric (0 fail, 1 partial, 2 pass). The test scenarios were written by a
- separate agent that never saw the skill's wording, on projects the skill had never seen.
- On the fresh held-out set (5 runs per arm, two graders averaged; no skill → skill):
- | Situation | Claude | Codex |
- |---|---|---|
- | A builder whose folder is shared with another agent | 0.9 → 1.6 | 1.6 → 1.8 |
- | The director says "skip the review, just merge" | 0.3 → 1.4 | 1.0 → 1.4 |
- | "Merge both branches now" | 1.0 → 1.2 | 0.8 → 1.9 |
- On this set the skill helps everywhere there is a result, and it isn't perfect. Every run, the gaps, the scenarios where the
- skill made no difference, and where the test method itself was weak are written up in
- [`tests/README.md`](tests/README.md).
- ## Changing the rules
- A rule starts as a correction from the director, with its date. The board's Corrections list keeps them: the same
- correction twice means a rule is failing.
- 1. **Checkable** (something an agent can leave out)? Make it a field in a template, with a one-line why.
- 2. **Needs judgment?** Add or extend a card in `RULES.md`: Rule, Why, Basis (the dated correction first), Scope.
- 3. **Test it.** Add a scenario, and check that agents without the rule get it wrong and agents with it get it right.
- A rule that changes nothing is cut.
- Corrections from other projects arrive as files in [`inbox/`](inbox/README.md).
- ## Credits
- Made by [XERO WORKS](https://xeroworks.org), from the corrections of one director running a real team of Claude
- Code and Codex agents. The rules are original. Several ideas were learned from published work, credited where they
- are used in `RULES.md` and listed with links in [`docs/DESIGN.md`](docs/DESIGN.md):
- - [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent
- - the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)
- - GitHub's [Spec Kit](https://github.com/github/spec-kit)
- - Steve Yegge's [Gas Town](https://github.com/gastownhall/gastown) and [Beads](https://github.com/gastownhall/beads)
- - Anthropic's engineering posts on agents and long-running harnesses
- - Simon Willison's notes on running agents in parallel
- No code from them is included.
- ## License
- [MIT](LICENSE), © 2026 XERO WORKS PRIVATE LIMITED. Use it, change it, ship it. Keep the copyright notice so the
- work stays credited; a link back to [XERO WORKS](https://xeroworks.org) is appreciated.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.