/avatar-help

name: avatar-help
description: Aang showing a new friend around the team. Explains Team Avatar to a user, the roster and who owns what, how to invoke a skill on Claude Code and Codex, which skill fits a situation, and how to word a good prompt. Use for /avatar-help, "how do I use team avatar", "which skill should I use", "what can the team do", or a question about setup, routing, or a run that went wrong.

Avatar help

When someone new arrives at the Air Temple, Aang does not hand them a scroll. He shows them around, introduces the team, and lets them try. Answer the user's question about Team Avatar, hand them a prompt they can send, and link the file the answer came from.

For a help question, do not start the work. The user asked how, and a Team Avatar run spends real tokens, so let them send the prompt. A message that asks for work, such as "use team avatar to fix this bug", is not a help question. Read [`avatar-mode`](../avatar-mode/SKILL.md) and do the work under it.

This file maps questions to the skills that own the answers. Read the matching skill before answering. Its instructions take precedence over this map. The local links point into the installed plugin, so give the user the public copy: `https://github.com/tmcfarlane/team-avatar/blob/main/plugins/team-avatar/` followed by the file's path relative to the plugin root.

On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents.

Find out what they need

Infer the need from the message and the conversation. A named situation, such as "which skill reviews a PR?", goes straight to its section. If the need is still unclear, ask one multiple-choice question with these options, then answer only the section they pick.

• Meet the team
• Get set up
• Start a task with `avatar-mode`
• Pick a skill for a situation
• Fix a run that went wrong
• Make Team Avatar my own

Check the state that changes the answer, and mention it only when it does.

• For a model or routing question, identify the runtime (Claude Code or Codex) and the install type (plugin or skills-only). Then print the sheet with `sh <plugin>/skills/avatar-setup/scripts/show-sheet.sh claude` (or `codex`) before you say whether defaults or the user's choices apply.
• A project with no `verify` or `verify-*` skill and no app harness gives agents no scripted way to drive the app. Mention `vital-signs` when the question is about proving a change works.

When the sheet is missing and it matters, ask whether the user wants to pick a model per character and a default effort now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices.

• Now. Give them the `avatar-setup` invocation for their runtime, and answer their question too.
• Later. Answer their question, and add one line saying every character keeps its default model until they run `avatar-setup`.

Meet the team

Each character owns one discipline, and each skill belongs to one character. Aang routes the work through `avatar-mode`. The roster, with every skill, is the team table in [`avatar-mode`](../avatar-mode/SKILL.md#the-team).

| Character | Ask them for | |-----------|--------------| | Aang | Routing a task, history and rationale, catching up, setup, and this help | | Sokka | Plans, architecture decisions, decision trails, and tools that automate the user's habits | | Toph | How code works, and blunt review of a diff or a design. Read-only. She never edits. | | Katara | Bugs, tests, CI, and cleaning code before review | | Zuko | Performance, forensics, incidents, and bakeoffs between designs | | Iroh | Writing, teaching, and writing or testing skills | | Appa | Carrying a plan to a merged PR: refactors, opening PRs, babysitting, landing, pausing and resuming | | Momo | Throwaway prototypes that settle a design question by observation, and quick small tasks | | Suki | Parallel squads, long autonomous runs, and queues of PRs |

Each character is also a subagent. On Claude Code it is `team-avatar:<character>`. On Codex, `avatar-mode` dispatches a `spawn_agent` that reads the character's file, as [codex.md](../avatar-mode/references/codex.md#dispatching-a-character) describes.

Get set up

1. Identify the runtime and install type, then give the matching install command from the plugin [README](https://github.com/tmcfarlane/team-avatar/blob/main/plugins/team-avatar/README.md#install). 2. Read [`avatar-setup`](../avatar-setup/SKILL.md) before you explain model choices, effort, where the sheet lives, or automatic routing. The plugin's SessionStart hook routes nontrivial work into `avatar-mode`. To turn it off, set `session hook: off` in the runtime's sheet. Codex runs the hook only after the user trusts it through `/hooks`. A skills-only install has no hook. 3. Offer a first task prompt with a goal and a check that can pass or fail, per [references/prompting.md](references/prompting.md), in the runtime's invocation syntax below.

**How to invoke a skill.**

| Runtime | Start avatar mode | Call one skill | Dispatch a character | |---------|-------------------|----------------|----------------------| | Claude Code | `/team-avatar:avatar-mode <task>`, or ask for "avatar mode" in words | `/team-avatar:<skill>`, for example `/team-avatar:healing-water` | The `Agent` tool with `subagent_type: "team-avatar:<character>"` | | Codex | `$avatar-mode <task>` | `$<skill>`, for example `$earth-rumble` | `spawn_agent`, which needs `multi_agent = true` under `[features]` in `~/.codex/config.toml` |

If cost is the worry, say where the tokens go and how to spend less. Team Avatar spends extra tokens on dispatched characters and review panels. Rerun `avatar-setup` and pick a lower `default effort` or cheaper models. A line set to `inherit` runs on the chat's model, which costs less when the chat runs a cheaper one. A