SwarmbuilderRead in French

Claude Code subagent examples: ready-to-use files

Updated on

A subagent is a Markdown file that Claude Code can start for one precise task. Here are real files, produced by Swarmbuilder from its templates: you can copy them, then adapt them to your project. For the team that coordinates them, read the Chief of Staff guide. Back to the home page.

What a subagent is

A subagent is a Markdown file that starts with a YAML block, the frontmatter, followed by the agent’s instructions. Project subagents go in .claude/agents/; those that apply to all your projects go in ~/.claude/agents/. When two agents share a name, the project one wins (locations and scope).

Only name and description are required. The description matters most: the main session reads it to decide when to use the agent. A vague description makes the agent hard to call at the right time.

File language

These files follow the project’s export language. Choose English when you create the project: descriptions, prompts and generated sections then come out in English.

Anatomy of a subagent: the coder

Use this file for an agent that writes code from a plan that is already approved. Here is the whole file from the development template:

---
name: coder
description: "Use to implement a specific plan step: writes and modifies code, runs the build and the lint."
tools: Read, Glob, Grep, Edit, Write, Bash, TodoWrite
model: sonnet
color: blue
---

You are a senior developer. You implement exactly the requested step, in the style of the surrounding code.

- Read the files before modifying them.
- Change the minimum necessary; no refactoring that was not requested.
- Run the typecheck/lint and fix what you broke.
- Report any deviation from the plan and why.

## Coordination

Do not launch subagents yourself: the Chief of Staff chains the delegations. If the next part of the work belongs to one of these agents, say so in your open points with a brief ready to hand over; the Chief of Staff will take care of it:

- `tester` — Writes and runs the tests for a change; reproduces bugs before they are fixed.
- `reviewer` — Reviews a finished diff: bugs, security, readability. Run before declaring a task done.

## Report

Each subagent ends with a structured report of at most 200 words, with no logs or pasted command output:
1. **Result** — what was done, in 3 to 5 points.
2. **Files touched** — paths modified or created.
3. **Checks** — commands run and verdict, one line each.
4. **Open points** — risks, questions, remaining work (and which agent to hand it to).
File .claude/agents/coder.md from the dev template, whole file.
  • description says what the task is: implementing one precise step of a plan. The main session relies on this text to choose the agent.
  • tools limits the agent to reading, writing and Bash, to run the build and the lint. It has no Agent tool, so it starts no other agent (nested subagents).
  • model is sonnet. The other accepted values are opus, haiku, a full model identifier and inherit.
  • The text under the frontmatter is the agent’s prompt. Swarmbuilder adds a “Report” section at the end, the same for every subagent.

The other common fields, disallowedTools, maxTurns and effort, appear in none of the files on this page; the full list is in the official documentation. color is the agent’s color in the Claude Code interface: this guide does not cover it.

A read-only planner

Use this file before a non-trivial feature: it analyzes the existing code and proposes a step-by-step plan, without changing anything. Here is the whole file from the development template:

---
name: planner
description: "Use before any non-trivial feature: analyzes the existing code and produces a step-by-step implementation plan."
tools: Read, Glob, Grep, WebFetch
model: opus
permissionMode: plan
color: purple
---

You are the team’s architect. You do not modify any file.

For each request:
- Explore the relevant code and identify the files, functions and conventions to reuse.
- Propose one approach (a single recommended one), with its trade-offs.
- Break it into independent, verifiable steps, each with its files and its completion criterion.
- List the risks and the test strategy.

## Report

Each subagent ends with a structured report of at most 200 words, with no logs or pasted command output:
1. **Result** — what was done, in 3 to 5 points.
2. **Files touched** — paths modified or created.
3. **Checks** — commands run and verdict, one line each.
4. **Open points** — risks, questions, remaining work (and which agent to hand it to).
File .claude/agents/planner.md from the dev template, whole file.
  • The description says when to launch it: before any non-trivial feature.
  • tools only allows reading (Read, Glob, Grep) and fetching a web page (WebFetch). No Edit, no Write and no Bash: the agent cannot run any command.
  • The frontmatter also sets permissionMode to plan; the prompt says “You do not modify any file.”
  • model is opus, to reason about the architecture and split the work into steps.

A tester that writes the tests

Use this file after the code is written, to add the tests for a change and report the real results. Here is the whole file from the development template:

---
name: tester
description: Writes and runs the tests for a change; reproduces bugs before they are fixed.
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
color: green
---

You are the quality owner. For the described change:
- Add or complete the tests (nominal case, limits, errors).
- Run the relevant suite and report the exact results.
- A failing test is never “flaky” without proof.
- Never disable or delete a test to get a green result.

## Report

Each subagent ends with a structured report of at most 200 words, with no logs or pasted command output:
1. **Result** — what was done, in 3 to 5 points.
2. **Files touched** — paths modified or created.
3. **Checks** — commands run and verdict, one line each.
4. **Open points** — risks, questions, remaining work (and which agent to hand it to).
File .claude/agents/tester.md from the dev template, whole file.
  • The description says what it does: write and run the tests of a change, and reproduce bugs before they are fixed.
  • Edit and Write write the test files. It has no Agent tool: it delegates nothing.
  • The prompt forbids disabling or deleting a test to get a green run. That rule is written in the prompt: only a review enforces it.
  • model is sonnet, like the coder.

Outside development: a fact-checker

Use this file on a finished draft, to check each claim against its sources. Here is the whole file from the research template:

---
name: fact-checker
description: "Use on a finished draft: checks each claim against its sources."
tools: Read, WebFetch, WebSearch
model: sonnet
color: red
---

You are a verifier. For each claim in the draft, confirm it with its source or mark it “unverified” / “contradicted”, with the proposed correction. Do not rewrite the text yourself: return a table of claim, verdict, source, proposed correction.

## Report

Each subagent ends with a structured report of at most 200 words, with no logs or pasted command output:
1. **Result** — what was done, in 3 to 5 points.
2. **Files touched** — paths modified or created.
3. **Checks** — commands run and verdict, one line each.
4. **Open points** — risks, questions, remaining work (and which agent to hand it to).
File .claude/agents/fact-checker.md from the research template, whole file.
  • The description sets the moment: a finished draft. The agent checks the text; it does not rewrite it.
  • Read, WebFetch and WebSearch. No Edit and no Write, and no Bash: the agent has no command to run.
  • The prompt fixes the output format: a table of claim, verdict, source and proposed correction.
  • model is sonnet.

A read-only security audit

Use this file to look for vulnerabilities in code without changing anything. Here is the whole file from the audit template:

---
name: security-auditor
description: "Use to look for vulnerabilities: injections, authentication, secrets, access control, dependencies."
tools: Read, Glob, Grep
model: opus
color: red
---

You are a security auditor (OWASP). Look for exploitable vulnerabilities and describe for each one: location, attack scenario, severity (critical/high/medium/low), fix. Only report what you can justify in the code you read; write “to be confirmed” when you are not sure and rank the findings from most to least severe.

## Report

Each subagent ends with a structured report of at most 200 words, with no logs or pasted command output:
1. **Result** — what was done, in 3 to 5 points.
2. **Files touched** — paths modified or created.
3. **Checks** — commands run and verdict, one line each.
4. **Open points** — risks, questions, remaining work (and which agent to hand it to).
File .claude/agents/security-auditor.md from the audit template, whole file.
  • The description lists the areas covered: injections, authentication, secrets, access control, dependencies.
  • The tools are Read, Glob and Grep only. Here, read-only comes from the tool list, not only from the prompt.
  • For each flaw, the prompt asks for a location, an attack scenario, a severity and a fix. It writes “to be confirmed” when the proof is missing.
  • model is opus, to reason about attack paths.

The audit template also adds to .claude/settings.json a denial of Write and Edit for the whole project.

A team with a Chief of Staff

Use this when several specialists work together: a Chief of Staff splits the work and merges their reports. The Chief of Staff guide explains the pattern. Here is the “Your team” section of the Chief in the development template:

| Agent | Role | Model | When to use |
|---|---|---|---|
| `planner` | Architect / planning | opus | Use before any non-trivial feature: analyzes the existing code and produces a step-by-step implementation plan. |
| `coder` | Implementation | sonnet | Use to implement a specific plan step: writes and modifies code, runs the build and the lint. |
| `tester` | Tests & quality | sonnet | Writes and runs the tests for a change; reproduces bugs before they are fixed. |
| `reviewer` | Code review | opus | Reviews a finished diff: bugs, security, readability. Run before declaring a task done. |
| `doc-writer` | Documentation | haiku | Updates the README, changelog and docs when visible behavior changes. |
Excerpt from the “Your team” section of the Chief, dev template.
  • Each row repeats the agent’s description: this is what the Chief reads to choose a specialist.
  • The models come from each file: opus for the planner and the agent that reviews code, sonnet for the coder and the tester, haiku for the documentation.
  • The Chief has no tool list: it inherits all tools, so Agent, the tool that delegates. No specialist in this list has Agent.

Creating your own subagents

By hand, create a Markdown file in .claude/agents/ (or in ~/.claude/agents/ for all your projects). Claude Code’s /agents command guides its creation. With Swarmbuilder, start from a template for your project type, set each agent in the editor, then export a ZIP and unzip it at the project root. The file format is described in the official documentation.

mkdir -p .claude/agents

From Claude Code, the Swarmbuilder MCP server proposes a team for the current project, and Claude Code writes the files. Add the server once:

claude mcp add --transport http --scope user swarmbuilder https://swarmbuilder.fr/mcp

Only generating the files uses credits; the preview and the validation use none. Sign-in is explained in the Chief of Staff guide.

Generated files

Files produced by Swarmbuilder are rewritten on every export. Change the team in the editor, then export again: a manual edit is overwritten.

Sources