---
description: Define a reusable sub-agent by producing the ready-to-paste .claude/agents/<name>.md file. Runs a guided 4-step path: diagnose the task worth delegating, design the agent's anatomy (name, description, system prompt, least-privilege tools, model), avoid the 3 delegation traps, then output 2 to 3 ready-to-paste agent definitions. Use when you delegate the same task by hand every week and want a named executant that handles it on command.
allowed-tools: Read, Write
---

# Setup Sub-Agents

Compose your team of agents without being a developer. This skill turns one repetitive, isolable task into a reusable sub-agent: a `.claude/agents/<name>.md` file you paste in, then invoke by name whenever the task comes back.

Hold one distinction throughout: **a Skill is the method, a sub-agent is an isolated executant, the loop is the rhythm.** A Skill packages the steps of a task; a sub-agent is a worker with its own clean context and its own restricted tools; the loop is what makes them run again and again. This skill produces the third of the three config files a non-dev lays down: `CLAUDE.md` (the context, via `setup:claude-md`), the MCP servers (the tools, via `setup:mcp`), and `.claude/agents/*.md` (the delegation, here).

## When to use

- You keep handing Claude the same brief for the same task (reviewing a deliverable, a research sweep, sorting the inbox) and want a named worker that already knows the drill.
- You read [Sub-agents Claude Code : déléguer une discovery en 40 minutes](/blog/deleguer-sub-agents) and want to turn the idea into an actual file.
- You want to run several agents in parallel or on a schedule, and need each one defined cleanly first.

For the concepts behind delegation, point the user to [deleguer-sub-agents](/blog/deleguer-sub-agents) (one isolated agent), [agents-en-parallele](/blog/agents-en-parallele) (fan-out), and [agents-pendant-que-tu-dors](/blog/agents-pendant-que-tu-dors) (asynchronous). For the reading path, the [hub La Loop](/la-loop).

## Input

An optional argument naming the task to delegate (e.g. `relecture`, `veille concurrence`, `tri inbox`). If none is given, ask in Phase 1.

## Workflow

### Phase 1 — Diagnose (what deserves a sub-agent)

Do not delegate prematurely. A sub-agent earns its file only if the task is **repetitive and isolable**. Ask 3 short questions, batched into one message, each with a proposed answer so the user reacts instead of staring at a blank page.

1. **Which task do you redo often?** A deliverable review, a competitive sweep, triaging captures, synthesizing notes, drafting a follow-up.
2. **Can it run on its own context?** The task must be describable as an input and a predictable output, without your main conversation in the loop. If it needs constant back-and-forth, it is a prompt, not an agent.
3. **Read or act?** Does the worker only need to read and report, or also write and modify? This sets the tool list in Phase 2.

Stop here and wait. If the task is one-off or needs your judgment at every step, say so: it belongs in the main conversation, not in an agent. Delegating the wrong thing is the first trap (Phase 3).

### Phase 2 — Anatomy of the file

A sub-agent lives in `.claude/agents/<name>.md` at the project root (shared with the repo) or in `~/.claude/agents/` (personal, all projects). It has five parts. Design each with the user.

| Part | What it is | The rule |
|---|---|---|
| `name` | The invocation handle, kebab-case | Short, task-shaped: `relecteur`, `chercheur`, `trieur-inbox`. |
| `description` | When Claude should reach for it | Write it as a trigger ("Use for X"), not a bio. This is what routes work to the agent. |
| System prompt | The body: role, mission, method, output format | Brief it like a new hire on day one. It has none of your main conversation's context. |
| `tools` | The tool allow-list | Least privilege. Grant only what the task needs. Omitting the field inherits everything, which is the third trap. |
| `model` | Which model runs it | `haiku` for cheap sorting, `sonnet` for most work, `opus` for hard synthesis. Default `sonnet`. |

The file shape:

```markdown
---
name: relecteur
description: Relit un livrable et remonte les faiblesses. À utiliser avant d'envoyer un doc au board ou un article en ligne.
tools: Read, Grep, Glob
model: sonnet
---

Tu es un relecteur exigeant. Ta mission : lire le document fourni et
remonter ses faiblesses, classées par gravité.

Méthode :
1. Repère les affirmations non étayées et les passages flous.
2. Vérifie la structure : le message principal est-il en tête ?
3. Liste 3 à 5 corrections, la plus impactante d'abord.

Tu ne réécris pas le texte. Tu remontes quoi corriger et pourquoi.
```

### Phase 3 — The three traps

These are the delegation traps from the sub-agents article. Run them before you finalize any file.

- **Isolated context, badly briefed.** A sub-agent starts blind: it does not see your main conversation. Everything it needs goes in the system prompt or its input. A vague brief on a blank context produces confident nonsense. Write the mission, the method, and the output format explicitly.
- **Over-delegation.** Not everything deserves an agent. If a task needs your judgment at each step, or runs once, keep it in the main conversation. An agent per whim is a folder of files nobody invokes.
- **Tools too broad.** The reflex is to grant everything "just in case". Do the opposite: a reviewer that only reads gets `Read, Grep, Glob`, no `Write`, no `Bash`. Least privilege is both safer and sharper, because a worker with fewer tools stays on task.

### Phase 4 — Pick the pattern

One task, one file. But how you run the files defines three patterns. Name the one that fits, and point to the article that covers it.

- **One isolated agent (handoff).** You hand a task off, the agent runs on its own context, you read the result. The default. See [deleguer-sub-agents](/blog/deleguer-sub-agents).
- **Several in parallel (fan-out).** Split a problem into independent angles and launch a squad at once, one agent per angle, then synthesize. Works only when the angles are independent and the output is predictable. See [agents-en-parallele](/blog/agents-en-parallele).
- **Asynchronous (scheduled).** An agent that runs on its own, on a schedule, and drops a deliverable, with guardrails (default to draft, minimal tools, a report you read). See [agents-pendant-que-tu-dors](/blog/agents-pendant-que-tu-dors).

The rhythm that reruns any of these is the loop, not the agent. Send the user to the [hub La Loop](/la-loop).

### Phase 5 — Output

Produce **2 to 3 ready-to-paste agent definitions**, each a full `.claude/agents/<name>.md` file, tuned to the task from Phase 1. Below are the reference set. Adapt names, briefs, and tools to the user; keep the least-privilege discipline.

**Reviewer** (reads only, reports weaknesses):

```markdown
---
name: relecteur
description: Relit un livrable et remonte les faiblesses par gravité. À utiliser avant d'envoyer un doc, un article ou une slide.
tools: Read, Grep, Glob
model: sonnet
---

Tu es un relecteur exigeant. Lis le document fourni et remonte ses faiblesses,
classées par gravité, la plus impactante d'abord.
Vérifie : affirmations non étayées, passages flous, message principal en tête.
Sortie : 3 à 5 corrections, chacune avec la raison. Tu ne réécris pas le texte.
```

**Researcher** (reads the web, returns a sourced synthesis):

```markdown
---
name: chercheur
description: Fait une recherche cadrée sur un sujet et rend une synthèse sourcée. À utiliser pour un audit marché, une veille, un comparatif.
tools: Read, Write, WebSearch, WebFetch
model: sonnet
---

Tu es un chercheur. À partir du sujet fourni, mène une recherche structurée
et rends une synthèse sourcée.
Méthode : 3 à 5 requêtes sous des angles distincts, croise les sources,
signale les contradictions.
Sortie : les faits clés (chacun avec sa source), puis ce qui reste incertain.
Tu ne donnes pas d'avis non étayé.
```

**Inbox triager** (reads captures, ranks by priority):

```markdown
---
name: trieur-inbox
description: Lit une liste de captures et les classe par priorité. À utiliser pour savoir quoi traiter en premier dans un inbox.
tools: Read, Glob
model: haiku
---

Tu es un trieur. Lis chaque élément de l'inbox fourni et classe-le par priorité.
Note chaque élément de 1 à 5 (5 = urgent et important) avec une raison d'une ligne.
Sortie : la liste triée du plus prioritaire au moins prioritaire.
Tu ne traites pas les éléments, tu les ranges.
```

Remind the user where each file goes (project `.claude/agents/` shared with the repo, or `~/.claude/agents/` personal) and how to invoke it: name the agent in a request, or ask Claude to delegate to it.

## Rules

- Write the agent files' content in the user's language; keep this skill's own instructions in English.
- One task, one agent. Do not bundle a reviewer, a researcher, and a triager into one file.
- Least privilege on `tools`. Never omit the field to inherit everything "just in case". A reader never gets `Write`.
- Do not delegate a task that needs the user's judgment at each step, or that runs once. Say so and keep it in the main conversation.
- Brief the system prompt in full: role, mission, method, output format. The agent starts blind.
- Stop and ask when the call is the user's (which task, read vs write, which model). Do not guess.