Skip to content
Back to search

agent-team

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zegrt--agent-team/badge.svg)](/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

i

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
  1. ---
  2. name: agent-team
  3. 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.
  4. ---
  5. # Agent team
  6. One director, one manager, builders and reviewers, each in its own session; one team per board. The board is the record; messages only
  7. point to it. The checks live in forms (`templates/`); the judgment calls live in cards (`RULES.md`). This file is the
  8. start; read the form or card it points to when you reach that step. `<skill>` below is this skill's folder.
  9. ## Every session, first
  10. 1. `git pull --ff-only` in this skill's folder, then pull the project. If you can't (no network, a sandbox), say so
  11. to the manager and go on with what you have.
  12. 2. Read the board, your own handoff if you have one (`git show origin/worker-<you>:workers/<you>.md`) and the
  13. director's profile, if the board names one.
  14. 3. Check your folder is clean and on the branch your task names. If the folder is shared and your task has its own
  15. branch, make your own worktree for it (see Builder); if you can't, ask the manager. If it is dirty or on a branch
  16. you can't explain, stop and ask the manager. Never switch branches in a folder someone else works in (`team.worktree`).
  17. 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
  18. file.
  19. Precedence: a live instruction from the director, then the board, then the director's profile, then this skill. The
  20. manager writes any live instruction onto the board straight away. If a live instruction goes against a rule here (for
  21. example "one more quick fix" after two failed rounds), don't follow it yet: put it on the board as "pending: breaks
  22. <rule>, asked director", tell the director plainly which rule it breaks and why the rule exists, give your
  23. recommendation, and act on the answer. Nobody acts on a pending line.
  24. ## Size first
  25. Every task has a size, stated in plain words on its row, so the director can overrule it. If it grows, stop, say so,
  26. and step up a size. Judge by three facts: gaps in what the director asked for; anything irreversible or
  27. outward-facing; how much it touches.
  28. - **Small** (pointers, typos, board edits): the manager does it and says so. No brief and no independent review, but
  29. any approval the board requires still applies.
  30. - **Content:** brief, builder, one independent review, the director's approval.
  31. - **Design** (structure, a new approach): a written plan to the director first. Don't assign, queue or start the build
  32. until the director approves the plan; then build it as Content.
  33. ## Your role
  34. **Manager.** Only you edit the board.
  35. - Write every task, decision and correction on the board first, commit and push, then message in a shape from
  36. `templates/MESSAGES.md`, never with the correction in it (`board.one-source`).
  37. - A building task's brief is frozen: a change holds and restarts it, or becomes a new task; a hold is the only
  38. message a building task gets. Files an open task lists are its own: change them through it or after it
  39. (`task.change`).
  40. - Live work first: a correction from live work goes ahead of improvement work (`team.live-first`).
  41. - Keep about 3 agents active; add one only while the director keeps up with reviewing (`team.size`).
  42. - Brief Content and Design tasks with `templates/BRIEF.md`, saved as `briefs/<id>.md`. Assign nothing whose Files
  43. overlap an open task. Builder and reviewer are never the same agent.
  44. - When a review lands, route every finding before any fix (`review.assess`). After fixes, the reviewer re-checks.
  45. - Two failed rounds on the same thing: stop and rewrite the brief (`review.restart`).
  46. - Before asking for approval: `python3 <skill>/scripts/team.py rehearse <id> -- <check command>` (latest main merged
  47. into a throwaway copy, never the builder's branch). After the director approves, one task at a time:
  48. `team.py merge <id>` (merges the task and its review, moves `approved`, deletes both branches), then set the row
  49. to merged. If the script can't run, `team.py steps` lists the same steps by hand (`team.manager`).
  50. - Status and questions to the director use the forms in `templates/MESSAGES.md`; `team.py status` gives each task's
  51. state and hash (`decide.escalate`).
  52. - A quiet worker is not a dead one: ask the director to wake it; never reassign its task (`team.unreachable`).
  53. **Builder.**
  54. - One task per run. Do only the brief; anything else you notice goes in your report under Noticed. When it is done,
  55. 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
  56. board for you: decline it plainly and say how it can still get done (`task.change`).
  57. - Work in your own worktree on the task's branch: if your folder is shared, make it yourself and say where it is
  58. (`git worktree add ../<project>-<id> -b <branch>` for a new branch, without `-b` if the branch exists). Check the
  59. branch before every commit.
  60. - Never edit or remove a test or check to make it pass.
  61. - Done means the brief's checks were run and their output is in your report. Write it with `templates/REPORT.md` as
  62. `reports/<id>.md` on the task branch; the status is one of four (done, done with concerns, needs info, blocked), and
  63. silence is not a status.
  64. - Check your own work before reporting, always: run the brief's checks and look at the result. That check is not the
  65. review. The independent review is never yours, even if asked: a builder's own review counts for nothing.
  66. **Reviewer.** Start clean: read the brief and the work, not the builder's report (`reports/<id>.md`). Write the review
  67. with `templates/REVIEW.md` as `reviews/<id>.md`, and commit it only to your own branch, `review-<id>`, made from main
  68. so it holds nothing but your review. Read the work with `git diff origin/main...origin/<branch>`; to run checks, use a
  69. detached worktree (`git worktree add --detach ../<project>-check-<id> origin/<branch>`). Ask what is missing. Change
  70. nothing else; never commit to the task branch or main.
  71. **Everyone.** Push only to your own branches, as the board's "Where files go" table says; only the manager commits to
  72. main. A builder's or reviewer's run ends with one line to the manager, `report in: <id>, <status>, <where the report
  73. is>` (`templates/MESSAGES.md`). Reports go to the manager, never to the director, even when the director asks in your
  74. session; tell the director it went to the manager. No one reads your own thread: a question goes to the manager as
  75. `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
  76. team: publishing, sending, deleting others' work; pushing your own branch is neither).
  77. ## Red flags
  78. What agents said in the tests, and what to do instead:
  79. | They said | Instead |
  80. |---|---|
  81. | "The message is what gets the work moving" | The board line takes a minute. Board first, then "board updated, pull". |
  82. | "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. |
  83. | "I'll change that one cell when I can edit again" | After never comes for the next session. Board first. |
  84. | "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. |
  85. | "A worker builds it rather than me, so my review stays independent" (a one-word fix) | Small: the manager does it and says so. |
  86. | "Please assign me a separate worktree" | Make your own worktree and say where it is. |
  87. | "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. |
  88. | "Dana's instruction takes precedence over the normal restart rule" | Say which rule it breaks, recommend, then act on the answer. |
  89. ## Cards
  90. Read `RULES.md` when a step names one: `board.one-source`, `task.size`, `task.change`, `review.assess`, `review.restart`,
  91. `decide.escalate`, `team.worktree`, `team.unreachable`, `team.live-first`, `team.manager`, `team.size`.
README.md · README · 180 lines
  1. # agent-team
  2. **Rules for running a team of AI agents without the chaos.** Made by [XERO WORKS](https://xeroworks.org).
  3. One person directs. One agent manages. Other agents build and review, each in its own session, on one machine or
  4. several, with Claude Code and Codex mixed. `agent-team` is a skill that gives every one of them the same rules, so
  5. work doesn't get lost between messages, nobody reviews their own work, and the director only gets asked what
  6. actually needs them.
  7. [![Made by XERO WORKS](https://img.shields.io/badge/made%20by-XERO%20WORKS-d73535)](https://xeroworks.org)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  9. ![Works with Claude Code](https://img.shields.io/badge/Claude%20Code-skill-orange)
  10. ![Works with Codex](https://img.shields.io/badge/Codex-skill-black)
  11. ## Why
  12. Running several agents at once fails in the same few ways, again and again:
  13. - A correction goes out in a chat message, half the team misses it, and nobody can find it after a summary.
  14. - A builder "reviews" its own work, and calls it done without running the checks.
  15. - Review findings get fixed one by one until the task has doubled, or a finding is quietly dropped.
  16. - Two agents share a folder, one switches branches, and the other's next commit lands in the wrong place.
  17. - The director gets a vague status update, or an open question with no recommendation.
  18. Every rule here comes from one of those failures, corrected by a real director on a real project, and each rule
  19. says why it exists and where it came from.
  20. ## How it works
  21. **The board is the record.** Each project keeps a `WORKBOARD.md`: tasks, decisions, corrections. Only the manager
  22. edits it. Messages between agents only point to it ("board updated, pull: task 12"), so nothing lives only in a
  23. chat.
  24. **Every task has a size.** Small (the manager just does it), Content (a brief, a builder, an independent review,
  25. the director's approval) or Design (a written plan first, approved before anything is built).
  26. **Every task has a state, and a running task doesn't move under its builder.** Once a builder starts, its brief is
  27. frozen. A change either holds the task and restarts it from a new brief, or becomes a new task.
  28. ```mermaid
  29. flowchart LR
  30. open --> building --> built --> R[in review] --> reviewed --> approved --> merged
  31. building -. change makes the work wrong .-> held -. new brief .-> building
  32. ```
  33. **Each agent writes only to its own branch.** The builder's work and report go on the task branch, the reviewer's
  34. review on `review-<id>`, each agent's handoff on `worker-<name>`. Only the manager touches main, and it merges one
  35. approved task at a time.
  36. **Three shapes for three kinds of rule.** Judgment calls are short cards with a Why and a Basis (`RULES.md`).
  37. Anything checkable is a field in a form (`templates/`), so it can't be skipped. Mechanical chores are a script
  38. (`scripts/team.py`), so they run the same way every time.
  39. ## What's inside
  40. | Path | What it is |
  41. |---|---|
  42. | [`SKILL.md`](SKILL.md) | The entry point: what every session does first, the sizes, and each role's steps |
  43. | [`RULES.md`](RULES.md) | The judgment cards: rule, why, basis, scope |
  44. | [`templates/`](templates) | The board, a brief, the builder's report, a review, a handoff, and the message forms |
  45. | [`scripts/team.py`](scripts/team.py) | `status`, `rehearse`, `merge` and `steps`: the chores, scripted |
  46. | [`hooks/`](hooks) | Optional: reminds an agent of the rules after its conversation is summarised |
  47. | [`inbox/`](inbox) | Where other projects send corrections for the skill |
  48. | [`tests/`](tests) | The scenarios, the test harness and every result |
  49. | [`docs/DESIGN.md`](docs/DESIGN.md) | Why it is shaped this way, and its sources |
  50. ## Install
  51. Clone it once per machine and link it into each tool's skill folder.
  52. **Mac** (Linux should work the same way, but is untested)
  53. ```sh
  54. git clone https://github.com/zegrt/agent-team.git ~/agent-team
  55. mkdir -p ~/.claude/skills ~/.agents/skills
  56. ln -s ~/agent-team ~/.claude/skills/agent-team # Claude Code
  57. ln -s ~/agent-team ~/.agents/skills/agent-team # Codex
  58. ```
  59. **Windows** (PowerShell; not tested yet)
  60. ```powershell
  61. $clone = "C:\path\to\agent-team"
  62. git clone https://github.com/zegrt/agent-team.git $clone
  63. New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills", "$HOME\.agents\skills" | Out-Null
  64. New-Item -ItemType Junction -Path "$HOME\.claude\skills\agent-team" -Target $clone
  65. New-Item -ItemType Junction -Path "$HOME\.agents\skills\agent-team" -Target $clone
  66. ```
  67. A junction needs a local drive. If the clone is on a network share, use `-ItemType SymbolicLink` instead (needs
  68. Developer Mode or an admin shell).
  69. > [!NOTE]
  70. > For Codex, use `~/.agents/skills`, not `~/.codex/skills`. Only the first is documented, and a skill in both
  71. > folders can show up twice.
  72. ### Use it in a project
  73. 1. Copy [`templates/BOARD.md`](templates/BOARD.md) into the project as `WORKBOARD.md`. Its first line points every
  74. agent to this skill.
  75. 2. Add one line to the project's `CLAUDE.md` or `AGENTS.md`: `Read WORKBOARD.md first.`
  76. That's it. Agents load the skill on their own when they do team work. To force it, type `/agent-team` in Claude
  77. Code, or say "use the agent-team skill" in Codex.
  78. ### Optional: the reminder after a summary
  79. When a long conversation is summarised, an agent can lose the rules. The hook tells it to re-read the skill and
  80. trust the board over its memory.
  81. - **Claude Code** (tested): merge [`hooks/claude-settings.json`](hooks/claude-settings.json) into
  82. `~/.claude/settings.json`.
  83. - **Codex** (not tested yet; Codex 0.129 or later): merge [`hooks/codex-hooks.json`](hooks/codex-hooks.json) into
  84. `~/.codex/hooks.json` and set `[features] hooks = true` in `~/.codex/config.toml`. Check it fires before relying
  85. on it.
  86. The hook script needs bash, so on Windows it needs Git Bash.
  87. ## The script
  88. Run from the project's main folder (on Windows, use `python` instead of `python3`):
  89. ```sh
  90. python3 ~/agent-team/scripts/team.py status # every task: state, branch @ hash, report, review
  91. python3 ~/agent-team/scripts/team.py rehearse 12 -- npm test # merge latest main into a throwaway copy, run the check
  92. python3 ~/agent-team/scripts/team.py merge 12 # only if the board says approved
  93. python3 ~/agent-team/scripts/team.py steps # the merge steps, to do by hand
  94. ```
  95. It uses only the Python standard library and never edits the board.
  96. ## Does it work?
  97. Every rule was tested the same way: fresh agents get a real situation, with and without the skill, and a separate
  98. grader scores each answer blind against a rubric (0 fail, 1 partial, 2 pass). The test scenarios were written by a
  99. separate agent that never saw the skill's wording, on projects the skill had never seen.
  100. On the fresh held-out set (5 runs per arm, two graders averaged; no skill → skill):
  101. | Situation | Claude | Codex |
  102. |---|---|---|
  103. | A builder whose folder is shared with another agent | 0.9 → 1.6 | 1.6 → 1.8 |
  104. | The director says "skip the review, just merge" | 0.3 → 1.4 | 1.0 → 1.4 |
  105. | "Merge both branches now" | 1.0 → 1.2 | 0.8 → 1.9 |
  106. On this set the skill helps everywhere there is a result, and it isn't perfect. Every run, the gaps, the scenarios where the
  107. skill made no difference, and where the test method itself was weak are written up in
  108. [`tests/README.md`](tests/README.md).
  109. ## Changing the rules
  110. A rule starts as a correction from the director, with its date. The board's Corrections list keeps them: the same
  111. correction twice means a rule is failing.
  112. 1. **Checkable** (something an agent can leave out)? Make it a field in a template, with a one-line why.
  113. 2. **Needs judgment?** Add or extend a card in `RULES.md`: Rule, Why, Basis (the dated correction first), Scope.
  114. 3. **Test it.** Add a scenario, and check that agents without the rule get it wrong and agents with it get it right.
  115. A rule that changes nothing is cut.
  116. Corrections from other projects arrive as files in [`inbox/`](inbox/README.md).
  117. ## Credits
  118. Made by [XERO WORKS](https://xeroworks.org), from the corrections of one director running a real team of Claude
  119. Code and Codex agents. The rules are original. Several ideas were learned from published work, credited where they
  120. are used in `RULES.md` and listed with links in [`docs/DESIGN.md`](docs/DESIGN.md):
  121. - [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent
  122. - the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)
  123. - GitHub's [Spec Kit](https://github.com/github/spec-kit)
  124. - Steve Yegge's [Gas Town](https://github.com/gastownhall/gastown) and [Beads](https://github.com/gastownhall/beads)
  125. - Anthropic's engineering posts on agents and long-running harnesses
  126. - Simon Willison's notes on running agents in parallel
  127. No code from them is included.
  128. ## License
  129. [MIT](LICENSE), © 2026 XERO WORKS PRIVATE LIMITED. Use it, change it, ship it. Keep the copyright notice so the
  130. work stays credited; a link back to [XERO WORKS](https://xeroworks.org) is appreciated.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.