Skip to content
Back to search

team-avatar

MarketplaceWorks with Claude CodeGitHub

Team Avatar: principal-level engineering skills, each owned by a character from Avatar: The Last Airbender.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tmcfarlane/team-avatar with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tmcfarlane/team-avatar'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tmcfarlane--team-avatar/badge.svg)](/listings/tmcfarlane--team-avatar)

HTML

<a href="/listings/tmcfarlane--team-avatar"><img src="/api/listings/tmcfarlane--team-avatar/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.

Claude Code:

claude plugin marketplace add tmcfarlane/team-avatar && claude plugin install team-avatar@team-avatar

Codex:

codex plugin marketplace add tmcfarlane/team-avatar && codex plugin add team-avatar@team-avatar

Codex starts character subagents only when `multi_agent = true` is set under `[features]` in `~/.codex/config.toml`.

Then ask for `avatar-mode` (`/team-avatar:avatar-mode` in Claude Code, `$avatar-mode` in Codex) with any engineering task. [plugins/team-avatar](plugins/team-avatar/README.md) has the full roster and every skill.

Each character runs on the model named in your model sheet, and `avatar-setup` writes that sheet. On Codex, run `$avatar-setup` once. The built-in defaults name Claude models, which Codex can't run. [Pick the models](plugins/team-avatar/README.md#pick-the-models) lists the defaults.

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.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "team-avatar",
  3. "owner": {
  4. "name": "Trent McFarlane",
  5. "url": "https://github.com/tmcfarlane"
  6. },
  7. "description": "Team Avatar: principal-level engineering skills, each owned by a character from Avatar: The Last Airbender.",
  8. "plugins": [
  9. {
  10. "name": "team-avatar",
  11. "source": "./plugins/team-avatar",
  12. "description": "Principal-level engineering skills for Claude Code and Codex. Aang routes the work, and each character owns one discipline.",
  13. "version": "1.0.0"
  14. }
  15. ]
  16. }
README.md · README · 592 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <p align="center">
  3. <a href="https://github.com/tmcfarlane/team-avatar">
  4. <img src="screenshots/teamavatar.png" alt="Team Avatar" width="560">
  5. </a>
  6. </p>
  7. <div style="font-size: 2.5em; font-weight: 700; letter-spacing: 0.12em;">
  8. <strong>TEAM AVATAR</strong>
  9. </div>
  10. **A universal agent orchestrator for Claude Code, Codex, and Cursor.**<br>
  11. Nine characters from *Avatar: The Last Airbender*. 58 engineering skills. One mode that routes the work.<br>
  12. _Created by <a href="https://zeroclickdev.ai/">ZeroClickDev</a>_
  13. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  14. [![GitHub Stars](https://img.shields.io/github/stars/tmcfarlane/team-avatar)](https://github.com/tmcfarlane/team-avatar/stargazers)
  15. <br>
  16. </div>
  17. https://github.com/user-attachments/assets/61db75bb-73e7-46d8-8863-fe9bbb8fad8c
  18. <sub>App screens are recreated from this repository's real runs and files. Narration is an AI clone of the author's voice.</sub>
  19. ## Install
  20. Claude Code:
  21. ```bash
  22. claude plugin marketplace add tmcfarlane/team-avatar && claude plugin install team-avatar@team-avatar
  23. ```
  24. Codex:
  25. ```bash
  26. codex plugin marketplace add tmcfarlane/team-avatar && codex plugin add team-avatar@team-avatar
  27. ```
  28. Codex starts character subagents only when `multi_agent = true` is set under `[features]` in `~/.codex/config.toml`.
  29. Then ask for `avatar-mode` (`/team-avatar:avatar-mode` in Claude Code, `$avatar-mode` in Codex) with any engineering task. [plugins/team-avatar](plugins/team-avatar/README.md) has the full roster and every skill.
  30. Each character runs on the model named in your model sheet, and `avatar-setup` writes that sheet. On Codex, run `$avatar-setup` once. The built-in defaults name Claude models, which Codex can't run. [Pick the models](plugins/team-avatar/README.md#pick-the-models) lists the defaults.
  31. ### Try your first task
  32. Open a repository and ask Team Avatar to explain its structure and test setup. This first task is read-only.
  33. Claude Code:
  34. ```text
  35. /team-avatar:avatar-mode Explain this repository's structure and how to run its tests. Cite the relevant files. Do not change any files.
  36. ```
  37. Codex:
  38. ```text
  39. $avatar-mode Explain this repository's structure and how to run its tests. Cite the relevant files. Do not change any files.
  40. ```
  41. ## Origin story
  42. Team Avatar started in Cursor as oh-my-cursor. I upgraded to Cursor Ultra with 9 days left to burn about $300 in tokens, and built agent swarms to do real work while responsibly (irresponsibly) optimizing token burn. Turns out all it takes is Markdown config files and one orchestration rule. That edition still ships, and [Team Avatar for Cursor](#team-avatar-for-cursor-the-original-oh-my-cursor) covers it.
  43. ## The honest version
  44. We took [pstack](https://github.com/cursor/plugins/tree/main/pstack), Lauren Tan's excellent agent workflow pack, by way of Michael Denyer's [Claude Code and Codex port](https://github.com/michael-denyer/pstack-claude). Then we slapped Avatar characters on top of it.
  45. It probably made it worse. It is definitely cooler.
  46. Every pstack skill and playbook is here, renamed and owned by a character. Katara heals bugs. Toph reviews your diff and does not care about your feelings. Zuko owns performance and incidents. Iroh writes the docs and makes the tea. Aang routes everything through `avatar-mode`. [NOTICE](plugins/team-avatar/NOTICE.md) credits every upstream source.
  47. We measured it, too. On [SWE-bench Verified Mini](docs/evidence/team-avatar-swebench/README.md), Team Avatar, pstack, and no plugin at all solve about the same number of tasks in both Claude Code and Codex. None of the gaps is statistically significant, and both plugins cost more per task. You are not buying a higher score. You are buying habits: reproduce the bug first, write the regression test, review the diff, explain the number.
  48. ## See it work
  49. Each app gets one short request. The prompt names `avatar-mode` and three bug reports, and avatar-mode picks the workflow and the characters. These are unedited window captures from Claude Desktop and the Codex app. An agent typed each prompt by driving the app. [How they were made](docs/evidence/desktop-apps/README.md).
  50. ```text
  51. /team-avatar:avatar-mode Fix these three reported issues: the cart total comes out a cent short, slugs still have spaces in them, and page 1 shows the second page of results.
  52. ```
  53. **Claude Desktop.** Avatar-mode answers with its own plan. The first step loads `healing-water`, Katara's bug workflow.
  54. <img src="docs/evidence/desktop-apps/claude-desktop-prompt.png" alt="Claude Desktop showing the avatar-mode prompt and the plan avatar-mode chose" width="820">
  55. It fixes each bug against its failing test, then runs two Toph reviews at the same time in the Background tasks pane. It skips the pull request because the demo repo has no remote.
  56. <img src="docs/evidence/desktop-apps/claude-desktop-reviews.png" alt="Claude Desktop's Background tasks pane with two Toph reviews running" width="820">
  57. The reply explains each root cause with what it measured. It made one branch per bug, and with all three applied, 6 of 6 tests pass.
  58. <img src="docs/evidence/desktop-apps/claude-desktop-result.png" alt="Claude Desktop's final reply explaining the three fixes" width="820">
  59. **Codex.** Type `$avatar-m` and the picker lists Team Avatar's skills.
  60. <img src="docs/evidence/desktop-apps/codex-app-picker.png" alt="The Codex app's skill picker showing Team Avatar: Avatar Mode" width="820">
  61. From the same request, avatar-mode sends Toph to investigate and Katara to fix, then starts a Toph correctness review and a Toph quality review. This frame shows the two reviews running. Codex lists Katara on the same line, but Katara had already finished.
  62. <img src="docs/evidence/desktop-apps/codex-app-reviews.png" alt="The Codex app with two Toph reviews running after Katara's fix" width="820">
  63. The finished activity log shows the investigation, the fix, and the two reviews. All three tests pass.
  64. <img src="docs/evidence/desktop-apps/codex-app-activity.png" alt="The Codex app's expanded activity log for the run" width="820">
  65. ## Other harnesses
  66. Every skill is a plain Markdown `SKILL.md` in the [Agent Skills](https://agentskills.io) format, so any coding harness that loads Agent Skills can run them, including OpenCode, Hermes Agent, OpenClaw, Muse Code, Gemini CLI, GitHub Copilot, Amp, and Goose. [T3 Code](https://github.com/pingdotgg/t3code) runs the Claude Code, Codex, Cursor, and OpenCode agents already on your machine, so install Team Avatar into the one it drives.
  67. The [`skills` CLI](https://github.com/vercel-labs/skills) installs the 58 skills for the agents you pick:
  68. ```bash
  69. npx skills add tmcfarlane/team-avatar/plugins/team-avatar
  70. ```
  71. Keep the `plugins/team-avatar` path. The repository root also holds the Cursor edition's skills, and a bare `tmcfarlane/team-avatar` lists both sets.
  72. To install by hand, copy each folder in `plugins/team-avatar/skills/` into a directory your harness scans. OpenCode, OpenClaw, and Muse Code all read `~/.agents/skills/`. Hermes Agent reads `~/.hermes/skills/`, or add `~/.agents/skills` to `skills.external_dirs` in `~/.hermes/config.yaml`.
  73. Outside Claude Code and Codex you get the skills on their own. The `team-avatar:<character>` subagents, the session hook, and the helper tools that `master-plan`, `kyoshi-command`, `long-flight`, and `safe-landing` run from `plugins/team-avatar/tools` come only with the plugins.
  74. ## Team Avatar for Cursor (the original oh-my-cursor)
  75. The Cursor edition is a Cursor plugin: 8 agents, 9 slash commands, hooks that block bad commits, one orchestration rule, and 21 bundled skills. It runs on Cursor's built-in `Task` subagents, with no external runtime and no wrapper CLI. It doesn't use the Claude Code and Codex plugin above.
  76. Each agent runs on its own model through Cursor's `model:` field. When a pinned model can't run, Cursor runs that agent on another model and shows which one ran. [VALIDATION.md](VALIDATION.md) records which models were checked, and on which build.
  77. Jump to: [Install](#install-the-cursor-edition) · [Orchestrator](#the-orchestrator) · [Agents](#the-agents) · [Model policy](#model-policy) · [Slash commands](#slash-commands) · [Orchestration modes](#orchestration-modes) · [Architecture](#architecture) · [Hooks](#hooks) · [Automations](#automations) · [Bundled skills](#bundled-skills) · [FAQ](#faq)
  78. ### Install the Cursor edition
  79. You need [Cursor](https://www.cursor.com/) 3.27 or later. The installer adds the edition as a local Cursor plugin in `~/.cursor/plugins/local/team-avatar/`, which is how Cursor applies a rule to every project. On Enterprise plans, an admin must turn on **Allow Local Plugin Imports** first. Cursor's [plugin docs](https://cursor.com/docs/plugins.md) cover sharing a plugin through a team marketplace.
  80. macOS and Linux:
  81. ```bash
  82. curl -fsSL https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.sh | bash
  83. ```
  84. Windows (PowerShell):
  85. ```powershell
  86. irm https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.ps1 | iex
  87. ```
  88. <details>
  89. <summary>Installer options</summary>
  90. Append a flag to the macOS and Linux one-liner above. To work from a checkout, clone the repository and run `bash install.sh` with the same flags. Without `--project`, the installer builds the local plugin for every project. With it, the edition goes into the repository's `.cursor/` folder instead.
  91. ```bash
  92. bash -s -- --project # Install to this project only (./.cursor/)
  93. bash -s -- --claude --codex # Also copy the Cursor edition into .claude/ and .codex/
  94. bash -s -- --no-skills # Skip the bundled skills
  95. bash -s -- --dry-run # Preview changes
  96. bash -s -- --force # Update or overwrite existing files
  97. bash -s -- --uninstall # Uninstall
  98. bash -s -- --disable # Disable orchestration (agents stay)
  99. bash -s -- --enable # Re-enable orchestration
  100. ```
  101. `--claude` and `--codex` copy the Cursor edition's agents, rules, commands, and hooks. For the Claude Code and Codex plugin, use [Install](#install) instead.
  102. On Windows:
  103. ```powershell
  104. # PowerShell 7+ / Windows 11 one-liner with flags:
  105. & ([scriptblock]::Create((irm https://raw.githubusercontent.com/tmcfarlane/team-avatar/main/install.ps1))) -Scope project -Force
  106. # Or clone and run locally (all versions):
  107. git clone https://github.com/tmcfarlane/team-avatar.git && cd team-avatar
  108. .\install.ps1 # Default (user scope)
  109. .\install.ps1 -Scope project # Project scope
  110. .\install.ps1 -AlsoClaude -AlsoCodex # Also copy the Cursor edition into .claude/ and .codex/
  111. .\install.ps1 -NoSkills # Skip the bundled skills
  112. .\install.ps1 -Force # Overwrite
  113. .\install.ps1 -Uninstall # Remove
  114. ```
  115. Windows PowerShell 5.1 runs `irm | iex` with the defaults only. To pass flags there, clone the repository.
  116. </details>
  117. The installer writes to these folders. At user scope they sit inside the plugin folder, `~/.cursor/plugins/local/team-avatar/`.
  118. | Scope | Agents | Rules | Commands | Hooks | Skills |
  119. | ------------------ | ---------------------- | --------------------- | ------------------------ | --------------------- | ------------------- |
  120. | `--user` (default) | `agents/` | `rules/` | `commands/` | `hooks/` | `skills/` |
  121. | `--project` | `./.cursor/agents/` | `./.cursor/rules/` | `./.cursor/commands/` | `./.cursor/hooks/` | `./.cursor/skills/` |
  122. | `--claude` | Also `.claude/agents/` | Also `.claude/rules/` | Also `.claude/commands/` | Also `.claude/hooks/` | Not copied |
  123. | `--codex` | Also `.codex/agents/` | Also `.codex/rules/` | Also `.codex/commands/` | Also `.codex/hooks/` | Not copied |
  124. | `--no-skills` | ✓ | ✓ | ✓ | ✓ | Skipped |
  125. After you install, restart Cursor or run **Developer: Reload Window**, then open **Customize** and check that the team-avatar plugin is listed.
  126. When you upgrade a `--project` install from v0.1, the installer removes the old agent files, such as hephaestus, prometheus, and atlas.
  127. ### The orchestrator
  128. The orchestrator rule (`orchestrator.mdc`) turns the root thread into a pure dispatcher. Its only permitted tools are `Task`, `TodoWrite`, `AskQuestion`, and `SwitchMode`, so all work goes through the specialist agents.
  129. Here is a real example of the root thread's reasoning:
  130. > **Planning Installation Instructions**
  131. >
  132. > I need to follow the orchestrator's guidance, since the root can't use Read directly and must delegate via Task. I have to document this in the README and use iroh, but I'm unsure about the new installation instructions, which might be documented elsewhere. It's critical to know these details, so I could search the repository with iroh/toph for existing install docs. I'll have to organize a plan: dispatch toph to find the installation instructions and have iroh update the README after. Plus, I'll create a to-do list to keep track of everything.
  133. Every sentence maps to an orchestrator rule: agent routing (Iroh for docs, Toph for search), phase chaining (explore, then write), and mandatory task tracking with `TodoWrite`.
  134. ### The agents
  135. Eight agents, each an Avatar character with its own model and role. Expand an agent to see its skills and a screenshot of it at work.
  136. <p align="center">
  137. <a href="#agent-aang"><img src="screenshots/faces/aang.png" width="96" height="96" alt="Aang" /></a>&nbsp;&nbsp;
  138. <a href="#agent-sokka"><img src="screenshots/faces/sokka.png" width="96" height="96" alt="Sokka" /></a>&nbsp;&nbsp;
  139. <a href="#agent-katara"><img src="screenshots/faces/katara.png" width="96" height="96" alt="Katara" /></a>&nbsp;&nbsp;
  140. <a href="#agent-zuko"><img src="screenshots/faces/zuko.png" width="96" height="96" alt="Zuko" /></a>&nbsp;&nbsp;
  141. <a href="#agent-toph"><img src="screenshots/faces/toph.png" width="96" height="96" alt="Toph" /></a>&nbsp;&nbsp;
  142. <a href="#agent-appa"><img src="screenshots/faces/appa.png" width="96" height="96" alt="Appa" /></a>&nbsp;&nbsp;
  143. <a href="#agent-momo"><img src="screenshots/faces/momo.png" width="96" height="96" alt="Momo" /></a>&nbsp;&nbsp;
  144. <a href="#agent-iroh"><img src="screenshots/faces/iroh.png" width="96" height="96" alt="Iroh" /></a>
  145. </p>
  146. <a id="agent-aang"></a>
  147. <details open>
  148. <summary><img src="screenshots/faces/aang.png" width="20" height="20" /> <strong>Aang</strong> · <em>The Avatar</em> · <code>composer-2.5-fast</code></summary>
  149. Deep multi-file executor and architecture consultant. Masters all elements.
  150. > **Master of all four elements.** Multi-agent orchestration in action.
  151. Skills: [`design-patterns-implementation`](skills/design-patterns-implementation/SKILL.md) · [`refactoring-patterns`](skills/refactoring-patterns/SKILL.md) · [`vercel-react-best-practices`](skills/vercel-react-best-practices/SKILL.md)
  152. <p align="center"><a href="screenshots/teamavatar/aang.png"><img src="screenshots/teamavatar/aang.png" alt="Aang working screenshot"></a></p>
  153. </details>
  154. <a id="agent-sokka"></a>
  155. <details open>
  156. <summary><img src="screenshots/faces/sokka.png" width="20" height="20" /> <strong>Sokka</strong> · <em>The Strategist</em> · <code>claude-opus-5-5-high</code></summary>
  157. Planning, ambiguity analysis, and plan review. The brain behind every mission.
  158. > **Ask first, dispatch second.** The orchestrator clarifies before it sends agents.
  159. Skills: [`architect`](skills/architect/SKILL.md) · [`planning`](skills/planning/SKILL.md) · [`technical-roadmap-planning`](skills/technical-roadmap-planning/SKILL.md)
  160. <p align="center"><a href="screenshots/teamavatar/sokka.png"><img src="screenshots/teamavatar/sokka.png" alt="Sokka working screenshot"></a></p>
  161. </details>
  162. <a id="agent-katara"></a>
  163. <details open>
  164. <summary><img src="screenshots/faces/katara.png" width="20" height="20" /> <strong>Katara</strong> · <em>The Healer</em> · <code>composer-2.5-fast</code></summary>
  165. Disciplined implementation, debugging, and methodical fixes. Mends broken code.
  166. > **Precision healer.** Surgical debugging and the smallest possible fix.
  167. Skills: [`debugging`](skills/debugging/SKILL.md) · [`refactoring`](skills/refactoring/SKILL.md) · [`refactoring-patterns`](skills/refactoring-patterns/SKILL.md)
  168. <p align="center"><a href="screenshots/teamavatar/katara.png"><img src="screenshots/teamavatar/katara.png" alt="Katara working screenshot"></a></p>
  169. </details>
  170. <a id="agent-zuko"></a>
  171. <details open>
  172. <summary><img src="screenshots/faces/zuko.png" width="20" height="20" /> <strong>Zuko</strong> · <em>The Firebender</em> · <code>gemini-4-argon</code></summary>
  173. Visual design: image generation, icons, and UI mockups. Brings designs to life.
  174. > **Fire and finesse.** Image generation, icons, and UI mockups.
  175. Skills: [`create-an-asset`](skills/create-an-asset/SKILL.md) · [`implementing-figma-designs`](skills/implementing-figma-designs/SKILL.md) · [`web-design-guidelines`](skills/web-design-guidelines/SKILL.md)
  176. <p align="center"><a href="screenshots/teamavatar/zuko.png"><img src="screenshots/teamavatar/zuko.png" alt="Zuko working screenshot"></a></p>
  177. </details>
  178. <a id="agent-toph"></a>
  179. <details>
  180. <summary><img src="screenshots/faces/toph.png" width="20" height="20" /> <strong>Toph</strong> · <em>The Seer</em> · <code>composer-2.5-fast</code></summary>
  181. Codebase search, external docs, and media analysis. Sees everything.
  182. > **Seismic sense.** Multi-angle codebase search and doc exploration.
  183. Skills: [`codebase-search`](skills/codebase-search/SKILL.md) · [`exploring-codebases`](skills/exploring-codebases/SKILL.md) · [`mgrep-code-search`](skills/mgrep-code-search/SKILL.md)
  184. <p align="center"><a href="screenshots/teamavatar/toph.png"><img src="screenshots/teamavatar/toph.png" alt="Toph working screenshot"></a></p>
  185. </details>
  186. <a id="agent-appa"></a>
  187. <details>
  188. <summary><img src="screenshots/faces/appa.png" width="20" height="20" /> <strong>Appa</strong> · <em>The Heavy Lifter</em> · <code>composer-2.5-fast</code></summary>
  189. Systematic task list execution. Carries the team.
  190. > **Plan executor.** Works through the task list one step at a time.
  191. Skills: [`frontend-builder`](skills/frontend-builder/SKILL.md) · [`vercel-composition-patterns`](skills/vercel-composition-patterns/SKILL.md) · [`vercel-react-best-practices`](skills/vercel-react-best-practices/SKILL.md)
  192. <p align="center"><a href="screenshots/teamavatar/appa.png"><img src="screenshots/teamavatar/appa.png" alt="Appa working screenshot"></a></p>
  193. </details>
  194. <a id="agent-momo"></a>
  195. <details>
  196. <summary><img src="screenshots/faces/momo.png" width="20" height="20" /> <strong>Momo</strong> · <em>The Scout</em> · <code>composer-2.5-fast</code></summary>
  197. Quick, focused tasks. Small, agile, and independent.
  198. > **Speed demon.** Parallel micro-tasks at maximum speed.
  199. Skills: [`refactoring`](skills/refactoring/SKILL.md) · [`refactoring-patterns`](skills/refactoring-patterns/SKILL.md) · [`vercel-react-best-practices`](skills/vercel-react-best-practices/SKILL.md)
  200. <p align="center"><a href="screenshots/teamavatar/momo.png"><img src="screenshots/teamavatar/momo.png" alt="Momo working screenshot"></a></p>
  201. </details>
  202. <a id="agent-iroh"></a>
  203. <details>
  204. <summary><img src="screenshots/faces/iroh.png" width="20" height="20" /> <strong>Iroh</strong> · <em>The Storyteller</em> · <code>claude-opus-5-5-high</code></summary>
  205. Documentation specialist. The only agent that owns the README, the CHANGELOG, and the project docs.
  206. > **Man of his letters.** Iroh spends much of his time writing letters to family.
  207. Skills: [`crafting-effective-readmes`](skills/crafting-effective-readmes/SKILL.md) · [`docs-write`](skills/docs-write/SKILL.md) · [`documentation-engineer`](skills/documentation-engineer/SKILL.md) · [`documentation-writing`](skills/documentation-writing/SKILL.md)
  208. <p align="center"><a href="screenshots/teamavatar/iroh.png"><img src="screenshots/teamavatar/iroh.png" alt="Iroh working screenshot"></a></p>
  209. </details>
  210. ### Model policy
  211. Every agent defaults to Composer 2.5 (`composer-2.5-fast`), which is fast and draws on Cursor's Auto and Composer pool ([#20](https://github.com/tmcfarlane/team-avatar/issues/20), [#21](https://github.com/tmcfarlane/team-avatar/issues/21)). Cursor's model docs list what is currently available. Three agents use a different model:
  212. | Agent | Model | Reason |
  213. | --------- | ------------------------------ | -------------------------------------- |
  214. | **Sokka** | `claude-opus-5-5-high` | Maximum reasoning for complex planning |
  215. | **Iroh** | `claude-opus-5-5-high` | Long-form documentation quality |
  216. | **Zuko** | `gemini-4-argon` | Multimodal and visual work |
  217. Workers that a coordinator spawns run on the model their own file pins. If a workflow regresses on Composer 2.5, change `model:` in the agent's Markdown file.
  218. #### Per-agent model routing
  219. <p align="center">
  220. <img src="screenshots/guy-spills-it.png" alt="Cursor per-agent model routing in agent frontmatter">
  221. </p>
  222. Cursor's `model:` field in an agent's frontmatter routes that agent to a specific model ([Cursor docs](https://cursor.com/docs/subagents)). The value is a model ID. Run `cursor-agent models` to list the IDs your account can use. Effort is part of the ID, as in `claude-opus-5-5-high`:
  223. ```yaml
  224. ---
  225. model: composer-2.5-fast # fast executor pool
  226. ---
  227. ```
  228. ```yaml
  229. ---
  230. model: claude-opus-5-5-high # Claude Opus 5.5 at high effort
  231. ---
  232. ```
  233. > **When a pinned model can't run, Cursor runs the agent on another model and shows which one ran.** That happens when an admin blocks the model, your plan doesn't include it, or a legacy plan needs Max Mode for it. Cursor's docs say the desktop app picks a compatible model, and the CLI uses the parent's model since v2026.10.22. The subagent's task card or result names the model that ran. On a Free plan only Auto runs, so every agent runs on Auto. An agent with no `model:` line inherits its parent's model.
  234. Models this edition uses: `composer-2.5-fast`, `claude-opus-5-5-high`, and `gemini-4-argon`. On October 26, 2026, Cursor CLI 2026.10.22 recognized all three, and `cursor-agent models` listed the first two. `composer-2.5-fast` also ran on Cursor 3.9.8. None of them has run on a paid plan on 3.27 yet. Opus 4.8, which Sokka and Iroh used before, is now hidden by default.
  235. > **Model IDs change between Cursor versions.** Check them against your build before you rely on routing. The [VALIDATION.md](VALIDATION.md) sweep takes about 2 minutes.
  236. ### Slash commands
  237. Type a command in Cursor's chat to run its workflow:
  238. | Command | Agent | Purpose |
  239. | --------------- | ------ | ------------------------------------------------------------------------------------------- |
  240. | `/plan` | Sokka | Full planning pipeline: ambiguity analysis, plan creation, and self-review |
  241. | `/build` | Aang | Deep multi-file implementation with verification |
  242. | `/search` | Toph | Multi-angle exploration of the codebase and docs |
  243. | `/fix` | Katara | Methodical debugging and code healing |
  244. | `/tasks` | Appa | Systematic task list execution |
  245. | `/scout` | Momo | Quick, focused tasks |
  246. | `/doc` | Iroh | Documentation generation and updates |
  247. | `/image` | Zuko | Cursor image generation (Nano Banana Pro) for icons, mockups, and prompts |
  248. | `/cactus-juice` | Swarm | Splits the request into micro-tasks and spawns up to 10 parallel workers |
  249. #### Image generation
  250. Cursor's agent generates images with Google Nano Banana Pro and saves previews under `assets/` by default. Team Avatar routes image work to Zuko. His [`cursor-image-generation`](skills/cursor-image-generation/SKILL.md) skill rewrites a short request into a full prompt, then iterates on the result. Use `/image`, or delegate with `Task(zuko)`, for image-only work.
  251. ### Orchestration modes
  252. #### Avatar State (default)
  253. Coordinated, tiered orchestration. The orchestrator reads each request and picks which agents to dispatch.
  254. #### Cactus Juice mode
  255. <p align="left">
  256. <img src="screenshots/cactus-juice/cactus-juice.jpg" alt="" width="360">
  257. </p>
  258. `/cactus-juice` trades depth for parallelism:
  259. 1. The root splits your request into 5 to 10 independent micro-tasks, each scoped to a single file.
  260. 2. Up to 10 subagents start at once with `model: fast`.
  261. 3. Each worker writes code with low cognitive complexity.
  262. 4. The root collects the results, checks that they are consistent, and fixes integration issues.
  263. <p align="left">
  264. <img src="screenshots/cactus-juice/cactus-juice.gif" alt="Cactus Juice mode demo" width="500">
  265. </p>
  266. ### Architecture
  267. ```mermaid
  268. flowchart TD
  269. U["You (root thread)"] --> R["orchestrator.mdc<br/>(Team Avatar)"]
  270. R --> IG{"Intent gate<br/>what did the user ask?"}
  271. IG -->|"search / 'how does X work?'"| T["Task(toph)<br/>Seer"]
  272. IG -->|"ambiguous / complex scope"| S["Task(sokka)<br/>Strategist"]
  273. IG -->|"visual assets"| Z["Task(zuko)<br/>Firebender"]
  274. IG -->|"complex feature"| PLAN["Task(sokka) → plan"]
  275. PLAN --> IMPL["Task(aang / katara)<br/>Coordinators"]
  276. IMPL -->|"spawns"| T2["toph (fast)"]
  277. IMPL -->|"spawns"| M2["momo (fast / inherited)"]
  278. IG -->|"task list"| AP["Task(appa)<br/>Heavy Lifter"]
  279. AP -->|"spawns"| M3["momo"]
  280. IG -->|"quick task"| MO["Task(momo)<br/>Scout"]
  281. IMPL --> V{"Verification<br/>lints / build / tests"}
  282. V -->|pass| DONE["Done"]
  283. V -->|fail| FR["Failure recovery<br/>(retry → aang → user)"]
  284. subgraph swarmNote ["Swarm Mode (Cursor 3.4+)"]
  285. N1["Coordinators spawn workers async.<br/>Max depth = 2. Workers are leaf nodes."]
  286. end
  287. ```
  288. ### Async subagents
  289. On Cursor 3.4 and later, the agents run as a two-tier swarm. Coordinators (Aang, Sokka, Katara, and Appa) spawn workers (Toph and Momo) as leaf nodes. Zuko runs only from the root.
  290. | Pattern | How it works |
  291. | --------------------- | -------------------------------------------------------------------- |
  292. | **Research-then-Act** | Spawn Toph for parallel research, collect the results, then implement |
  293. | **Fire-and-Collect** | Spawn several Momo workers, wait for all of them, and verify each |
  294. ### Hooks
  295. Hooks enforce rules at the system level, so nothing depends on an agent remembering to verify. They run through Cursor's [hooks](https://cursor.com/docs/hooks) system, from the plugin's `hooks/hooks.json` or a project's `.cursor/hooks.json`. Each hook is a script that reads a JSON payload on stdin. For `beforeShellExecution`, it returns an allow, deny, or ask decision.
  296. > **Both installs include the hooks on macOS and Linux.** The local plugin carries them in `hooks/hooks.json`, and `--project` writes `.cursor/hooks.json` into the repository. On Windows, Cursor runs hooks through PowerShell and these hooks are bash scripts, so `install.ps1` leaves them off. Plugin hooks start in the plugin's folder, so the guard moves to the command's working directory from Cursor's payload before it checks a commit. After you install, quit Cursor completely (Cmd+Q) and reopen it, and make sure the workspace is trusted. `scripts/test-cursor-hooks.sh` checks the guard's replies against Cursor's hook schema.
  297. | Hook handler | Event | Purpose |
  298. | --------------------- | ---------------------- | ------------------------------------------------------------------------------- |
  299. | `guard-shell.sh` | `beforeShellExecution` | Blocks destructive commands (`rm -rf /`, a force-push to `main`, a hard reset of a shared branch) and commits that contain forbidden anti-patterns (`as any`, `@ts-ignore`, empty catches). It matches text in the command, so it also blocks `rm -rf` on any absolute or home path and a force-push to any branch whose name contains `main` or `master`. It also blocks a command that stages files and commits in one go, because the anti-pattern check only sees what was staged before the command ran. |
  300. | `post-edit-lint.sh` | `afterFileEdit` | Lints the edited file and reports issues right away. It never blocks. |
  301. | `pre-commit-check.sh` | (library) | The anti-pattern checker that `guard-shell.sh` calls. It also works as a git pre-commit hook. |
  302. To try the hooks without blocking anything, set `OMC_HOOKS_OBSERVE=1`. `guard-shell.sh` then logs what it would block and allows it. Use observe mode to check the hooks on your build before you let them block. To turn the plugin's hooks off, replace `~/.cursor/plugins/local/team-avatar/hooks/hooks.json` with `{"version": 1, "hooks": {}}`. The installer keeps that edit unless you pass `--force`.
  303. #### Auto-review policy (`permissions.json`)
  304. `permissions.json` is a tuned [auto-review](https://cursor.com/docs/agent/security) policy (`autoRun.allow_instructions` and `block_instructions`). Team Avatar agents run safe calls on their own, such as lints, tests, builds, and read-only git. Risky calls wait for review: destructive file operations, history rewrites, credential and secret access, and outbound network. The policy takes effect when a Run Mode is enabled in **Cursor Settings > Agents > Approvals & Execution**.
  305. > Hooks and auto-review are best-effort, not a security boundary. They prevent common mistakes and cut down on approval prompts, but they don't replace real sandboxing.
  306. > **Validate the whole stack in one pass.** [`docs/E2E-TEST.md`](docs/E2E-TEST.md) is a runbook of 15 checks (model routing, hook enforcement, and auto-review) that Codex runs while you watch. Paste its Driver Prompt into Codex with Computer Use, and it fills in a pass and fail table against your live Cursor app.
  307. ### Automations
  308. Cursor Automations (Cursor 3.8 and later) start Team Avatar agents from events:
  309. - A review comment on a PR sends Katara to fix it.
  310. - An issue labeled `design` sends Zuko to mock it up.
  311. - A Slack reaction (🔧, 🎨, or 🔍) dispatches the matching agent.
  312. Cursor automations are cloud-only, with no config file you can commit yet, so these ship as ready-to-paste `/automate` recipes rather than installable config. See [`automations/`](automations/README.md).
  313. ### Prompting tips
  314. ```text
  315. You are Team Avatar. Use @toph to explore the codebase, @sokka to create a plan,
  316. and @aang to implement. Verify with lints/build/tests. Keep going until done.
  317. ```
  318. Or chain the slash commands: `/plan add OAuth support with JWT tokens`, then `/build based on the plan above`.
  319. ### Bundled skills
  320. The Cursor edition installs 21 skills: 20 vendored from the community, plus `cursor-image-generation`, written for this repository. Each is a `SKILL.md` folder that Cursor discovers and offers to agents as domain knowledge. They ship inside the repository, so the installer never fetches third-party files and copies one tree. The installer adds them by default. To skip them, pass `--no-skills`.
  321. <details>
  322. <summary><strong>Bundled skills (21)</strong></summary>
  323. | Skill | Source | Agents | What it provides |
  324. | ------------------------------ | --------------------------------- | ------------------ | ---------------------------------------------------------------------------- |
  325. | architect | thebushidocollective/han | Sokka | System architecture and high-level technical design |
  326. | codebase-search | supercent-io/skills-template | Toph | Systematic search strategies for navigating large codebases |
  327. | create-an-asset | anthropics/knowledge-work-plugins | Zuko | Generate tailored sales assets (landing pages, decks, one-pagers) |
  328. | crafting-effective-readmes | community | Iroh | Templates and guidance for writing effective READMEs matched to project type |
  329. | cursor-image-generation | tmcfarlane/team-avatar | Zuko | Rewrites short image requests into full prompts for Cursor image generation |
  330. | debugging | oimiragieo/agent-studio | Katara | Systematic 4-phase debugging with root cause investigation |
  331. | design-patterns-implementation | aj-geddes/useful-ai-prompts | Aang | Apply design patterns such as Singleton, Factory, Observer, and Strategy |
  332. | docs-write | metabase/metabase | Iroh | Documentation following Metabase's conversational, user-focused style |
  333. | documentation-engineer | charon-fan/agent-playbook | Iroh | Technical documentation for creating clear, comprehensive docs |
  334. | documentation-writing | rysweet/amplihack | Iroh | Clear, discoverable docs following the Eight Rules and Diataxis framework |
  335. | exploring-codebases | community | Toph | Semantic search using AST-aware expansion for full context |
  336. | frontend-builder | daffy0208/ai-dev-standards | Appa | Modern React/Next.js frontend patterns and component architecture |
  337. | implementing-figma-designs | onekeyhq/app-monorepo | Zuko | Implement Figma designs 1:1 using component libraries |
  338. | mgrep-code-search | intellectronica/agent-skills | Toph | Semantic code search using mgrep for efficient exploration |
  339. | planning | thebushidocollective/han | Sokka | Technical implementation planning and architecture design |
  340. | refactoring | eyadsibai/ltk | Katara, Momo | Code restructuring, renaming, extraction, and migration |
  341. | refactoring-patterns | wondelai/skills | Aang, Katara, Momo | Named refactoring transformations to improve code structure |
  342. | technical-roadmap-planning | aj-geddes/useful-ai-prompts | Sokka | Comprehensive technical roadmaps aligned with business goals |
  343. | vercel-composition-patterns | vercel-labs/agent-skills | Appa | React composition patterns that scale |
  344. | vercel-react-best-practices | vercel-labs/agent-skills | Aang, Appa, Momo | React and Next.js performance optimization from Vercel Engineering |
  345. | web-design-guidelines | vercel-labs/agent-skills | Zuko | Web Interface Guidelines compliance for UI review |
  346. </details>
  347. To add your own skill, create a `SKILL.md` folder under `.cursor/skills/` (project) or `~/.cursor/skills/` (user). Cursor discovers it on its own.
  348. ### FAQ
  349. #### Do I need to choose agents myself?
  350. No. The orchestrator delegates on its own. Slash commands such as `/plan`, `/build`, and `/fix` give you explicit control when you want it.
  351. #### Does it work on any Cursor plan?
  352. Yes, if your plan includes agent mode with subagents.
  353. #### How do I update?
  354. Run the install command again with `--force` (`-Force` on Windows). Installers before Cursor 3.27 wrote straight into `~/.cursor/agents/`, `rules/`, `commands/`, `hooks/`, and `skills/`. The new installer moves those files into `~/.cursor/team-avatar-backup-<timestamp>/` and prints each move. It deletes nothing.
  355. #### How do I uninstall?
  356. Run the install command with `--uninstall` (`-Uninstall` on Windows). It removes `~/.cursor/plugins/local/team-avatar/` and leaves `~/.cursor/permissions.json` in place.
  357. #### What about Claude Code and Codex?
  358. Install the plugin from [Install](#install). It has the 9 characters and 58 skills built for those tools. The installer's `--claude` and `--codex` flags still work, but they copy only the Cursor edition.
  359. #### What if I also use the Claude Code edition?
  360. Cursor 3.27 loads Claude Code plugins, so it loads both editions, and the Claude Code edition's agents take over the shared names (`aang` through `zuko`). This edition's agents and model pins then don't run. To use this edition in Cursor, turn off **Include Third-Party Plugins, Skills, and Other Configs** in Cursor Settings. That also stops Cursor from loading your other Claude Code plugins and skills. Otherwise, uninstall one of the two. The installer warns when it finds both.
  361. ## Inspiration
  362. The Cursor edition adapts [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (formerly oh-my-opencode): agent specialization, parallel dispatch, and phased orchestration, applied to Cursor's native `Task` subagents. The Claude Code and Codex plugin adapts pstack, as [The honest version](#the-honest-version) explains.
  363. ## Star history
  364. [![Star History Chart](https://api.star-history.com/svg?repos=tmcfarlane/team-avatar&type=date&legend=top-left)](https://www.star-history.com/#tmcfarlane/team-avatar&type=date&legend=top-left)
  365. ## Contributing
  366. Contributions that improve clarity, behavior, or docs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  367. To work on the plugin, see [Develop](plugins/team-avatar/README.md#develop) in the plugin README. To work on the Cursor edition, clone the repository and run `bash install.sh` (macOS and Linux) or `.\install.ps1` (Windows) to install from source. Changes to agents, rules, commands, or hooks take effect after you reinstall.
  368. ## Security
  369. To report a vulnerability, see [SECURITY.md](SECURITY.md).
  370. ## License
  371. MIT. See [LICENSE](LICENSE). _Steal it respectfully._

Ratings and comments

Sign in to rate this skill.

Sign in

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