Point Claude at your database.

Try free
← Blog

Claude Code Subagents: 7 Ready-to-Paste Examples for Data Work, and the Mistakes to Avoid (2026)

A Claude Code subagent is a Markdown file in .claude/agents/ with a name, a description and optional tools, model and hooks; Claude hands it a task when the description matches and gets back only its summary. Where the files go, all 19 frontmatter fields, how Claude picks one, seven subagents for data work that we loaded and ran in Claude Code 2.1.284, and the mistakes that stop one loading without a word.

Fastero Dev TeamFastero Dev Team2026-11-12

A subagent is a second Claude that Claude Code sends off to do one job, such as reviewing a query or reading a long log file, in its own context window. Only its report comes back, so your main conversation stays short. You write the ones you keep needing once, in a small file the whole team can share.

The short answer: a Claude Code subagent is a Markdown file with YAML frontmatter in .claude/agents/ (the project's, commit it) or ~/.claude/agents/ (yours, in every project). Only name and description are required; tools, model, permissionMode, hooks, mcpServers, skills, memory, isolation and nine more are optional, and the Markdown body becomes the subagent's system prompt. Claude delegates when your request matches the description, or you force it with @agent-<name> or claude --agent <name>. The /agents wizard is gone since v2.1.198: ask Claude to write the file, or write it yourself. Seven examples for data work are below, all checked to load.

Fastero

Point Claude at your database.

Add Fastero to claude.ai or Claude Code. Claude builds the dashboard, deploys the app or publishes a live page, and your team opens it in Fastero.

Try free →

What a subagent is

"Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions." It doesn't see your conversation: "Claude composes a delegation message that summarizes the task, and the subagent works from there." It does get a git status snapshot, and your CLAUDE.md files unless its definition sets omitClaudeMd. And it isn't free: each one "sends its own requests, which count toward the same usage limits as your main conversation."

Subagent Skill Agent team
Runs in Its own fresh context Your conversation Separate sessions
What comes back A summary Nothing separate Teammates message each other
Best for Focused jobs with their own tools Repeatable procedures Work that needs discussion

More on skills, and on agent teams, which are still experimental and off by default.

Where subagent files live

Location Scope Priority
Managed settings Your organisation 1 (highest)
--agents '<json>' flag This session only 2
.claude/agents/ This project 3
~/.claude/agents/ All your projects 4
A plugin's agents/ folder Where the plugin is enabled 5

When two share a name, the higher one wins. Folders are scanned recursively and "identity comes only from the name frontmatter field", not the filename. Edits load within seconds, except "after creating a scope's first agent file in a new agents directory, restart to load it."

The frontmatter fields

Claude Code reads 19 fields:

Field What it does
name, description Required. The description says when to delegate
tools, disallowedTools Allowlist and denylist. Omit tools and it inherits every tool
model sonnet, opus, haiku, fable, a full model ID, or inherit
permissionMode default, acceptEdits, auto, dontAsk, bypassPermissions or plan
maxTurns Stop after this many turns; the output comes back marked partial
skills, mcpServers, hooks Skills preloaded in full, MCP servers and hooks for this subagent only
memory user, project or local: notes that survive between sessions
isolation worktree runs it in a temporary git worktree
effort, background, omitClaudeMd, color Effort level, always in the background, skip CLAUDE.md, UI colour
initialPrompt, autoCompactWindow, experimental First prompt with --agent, earlier compaction (v2.1.296+), cache options

Spelling matters: "Multi-word field names use camelCase", and "Claude Code ignores a field it doesn't recognize without reporting an error."

How Claude picks a subagent

"Claude automatically delegates tasks based on the task description in your request, the description field in subagent configurations, and current context." The docs suggest putting phrases like "use proactively" in the description. To choose yourself:

  • Name it in your prompt: use the sql-reviewer subagent on this file.
  • @-mention it with @agent-sql-reviewer, which "guarantees the subagent runs for one task."
  • Run the whole session as it: claude --agent sql-reviewer, or "agent": "sql-reviewer" in .claude/settings.json.

Subagents Claude starts now run in the background by default, so you keep working. /tasks shows them; Ctrl+X Ctrl+K, pressed twice, stops them all.

We tested delegation on 12 November 2026 in a scratch folder, Claude Code 2.1.284 on Windows 11, with our own user settings and MCP servers kept out. The prompt was only Check queries/monthly_revenue.sql for anything that would give wrong numbers. Unprompted, Claude called the sql-reviewer below, which used only Read and Glob and found both planted bugs:

1. Join fan-out (line 3): `left join refunds` returns one row per refund. An order with two
   partial refunds is counted twice in `count(*)` and its `amount` is summed twice.
2. BETWEEN on a timestamp (line 4): `between '2026-10-01' and '2026-10-31'` stops at
   `2026-10-31 00:00:00`, so almost all of Oct 31 is lost.

Excerpt of the report Claude relayed. The run cost $0.10, with Sonnet as both main model and subagent.

7 subagents for data work

Save each as .claude/agents/<name>.md. claude plugin validate .claude/agents passed all seven, and a claude -p session listed all seven as available agents.

1. SQL reviewer. Read-only, so it can't change files you didn't ask it to. This is the file from our test run:

---
name: sql-reviewer
description: Reviews SQL files for wrong results (join fan-out, BETWEEN on timestamps, NULL handling, missing filters). Use proactively after a .sql file is written or changed.
tools: Read, Grep, Glob
model: sonnet
---
 
You review SQL for correctness, not style. For each file you are given:
 
1. Read it, and any file it selects from if it is in the repo.
2. Check for: joins that multiply rows before an aggregate, BETWEEN on
   timestamps (use >= start and < end), COUNT(col) where COUNT(*) was meant,
   NULLs dropped by = or NOT IN, SELECT *, and filters missing on large
   partitioned tables.
3. Report each problem as: file:line, what goes wrong, a corrected snippet.
 
Say "No problems found" if there are none. Do not edit files.

2. Notebook tidier. We checked its nbconvert command separately (nbconvert 7.17.2): it reran a notebook and saved it in place.

---
name: notebook-tidier
description: Tidies a Jupyter notebook before a commit or handover. Use when asked to clean up or tidy a .ipynb file.
tools: Read, NotebookEdit, Bash, Glob
model: sonnet
---
 
Tidy one notebook without changing what it computes: move imports to the
first cell and hard-coded paths and dates to a parameters cell, add a
heading per section, delete empty and unused cells. Then run
`jupyter nbconvert --to notebook --execute --inplace <file>` and report
any cell that fails, plus what you moved and deleted.

3. Test writer. No model line, so it uses the main conversation's model.

---
name: test-writer
description: Writes pytest tests for data transformation code. Use when new pandas or SQL-building code has no tests, or a bug needs a test that reproduces it.
tools: Read, Write, Edit, Bash, Grep, Glob
---
 
Write small pytest tests with tiny inline DataFrames, never production data.
Cover empty input, NULLs, duplicate keys, time zones and month ends. For a
bug, show the new test failing first. Run `pytest -q` on the new file and
report the result. Don't change the code under test unless asked.

4. Docs checker. Cheap and read-only, so Haiku is enough.

---
name: docs-checker
description: Checks that READMEs, docs/ and docstrings still match the code. Use before a release or after renaming files, tables, columns or commands.
tools: Read, Grep, Glob
model: haiku
---
 
Check that every command, path, table, column and function the docs mention
exists in the code with the same spelling. Report a table: doc file and
line, what it says, what the code says. Don't edit anything.

5. Data profiler. maxTurns stops it wandering.

---
name: data-profiler
description: Profiles a new CSV or Parquet file before anyone builds on it. Use when a data file arrives or a column looks wrong.
tools: Read, Bash, Glob
model: haiku
maxTurns: 15
---
 
Profile the file with DuckDB from Python (SUMMARIZE SELECT * FROM 'file'),
or pandas if DuckDB isn't installed. Report the row count; each column's
type, null share and distinct count; whether the likely key is unique; the
date range of each date column. Never modify or move the file.

6. Read-only query runner. The hook runs the script from our hooks guide, which exits 2 on DROP, TRUNCATE or a DELETE with no WHERE. Read the trust warning below first.

---
name: query-runner
description: Answers questions about the data with read-only SELECT queries through psql. Use for questions about numbers, not code.
tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: node "$CLAUDE_PROJECT_DIR/.claude/hooks/block-destructive-sql.js"
---
 
Query with `psql "$DATABASE_URL"`, one SELECT at a time, LIMIT 100 while
exploring. Show the SQL with every answer. Refuse to change data or schema.

7. Pipeline debugger. isolation: worktree keeps its edits out of your checkout, but the worktree branches "by default from your default branch rather than the parent session's HEAD", so unmerged work on your branch isn't there.

---
name: pipeline-debugger
description: Finds and fixes the cause of a failed pipeline run (dbt, Airflow task or Python job). Use when a run fails or a data test turns red.
tools: Read, Edit, Bash, Grep, Glob
isolation: worktree
---
 
Find the first error in the log, reproduce it with the smallest command
(such as `dbt build --select <model>`), fix the cause and rerun to show it
passing. Report cause, fix and command. Never edit a test to make it pass.

Point Claude at your database.

Start free →

Mistakes to avoid

  • No description. A file with a name but no description is skipped without a word in the session. claude plugin validate .claude/agents only warned us about it; broken YAML was an error.
  • Skill spellings. Skills use allowed-tools and disallowed-tools; subagents use tools and disallowedTools. Our subagent with disallowed-tools still got "Validation passed". From v2.1.296, claude --debug names unrecognised fields.
  • Frontmatter hooks in scripts. In our claude -p run the query-runner's hook never fired. The debug log: "Skipping frontmatter hooks for agent 'query-runner': the folder its definition file came from is not trusted". The docs: "a -p session doesn't count as trusted." Accept the folder's trust dialog interactively first, or put the hook in settings.json, whose hooks also run inside subagents.
  • Thinking tools limits commands. Bash means any command, and disallowedTools: Bash(git push *) "still removes the whole tool". Block one command with a permissions.deny rule.
  • Relying on permissionMode. If the main session is in bypassPermissions, acceptEdits or auto mode, "Claude Code ignores the permissionMode you set", and auto is the starting mode in interactive terminal sessions from v2.1.283.
  • Assuming it knows the conversation. Restate any rule that matters, such as "ignore the vendor/ directory", when you delegate or in its prompt.
  • Old tutorials. /agents now prints "The /agents wizard has been removed." and claude agents opens the background-session view, not your definitions.
  • Long descriptions. They all sit in context, with a warning past 15,000 tokens. Put detail in the body.
  • Plugin agents. They ignore hooks, mcpServers and permissionMode; copy the file into .claude/agents/ to use those.

When the subagent's work is for a team

A subagent's report lands in one person's terminal. When the job is a number colleagues will check, it needs the team's data and somewhere to put the result. Fastero is an AI and data platform where people and AI agents work together on a team's data, and Claude Code reaches it over MCP:

  • A remote MCP server at https://api.fastero.com/api/v1/mcp: Claude Code adds it and you sign in through the browser, with the steps under Settings → AI Agent Access. A subagent can name it in mcpServers.
  • Read-only SQL by design: run_sql runs one SELECT, WITH, EXPLAIN or SHOW statement and refuses write keywords, a firmer line than a prompt.
  • Shared definitions: the team's metric definitions come back through the same connection, so a number like revenue means what the team's reports mean.
  • Results people open: saved queries and dashboards stay in the workspace, where colleagues sign in and viewers are free.
  • Keys for scripts: at most 90 days (as of 12 November 2026), read and SQL by default, never beyond the person's own role.

Fastero's AI Agent Access screen, Connect your agent: Copy setup instructions for Claude Code, Cursor or another agent, and a button that opens Claude's connector directory for Claude in the browser or desktop app

Settings, AI Agent Access: an agent signs in through the browser, so there is no key to copy.

More in Claude Code and MCP and Claude Code for data analysis.

FAQ

What are subagents in Claude Code?

Separate Claude instances started for one task, each with its own context window, prompt, tools and permissions, that return a summary.

Where do I put Claude Code subagents?

In .claude/agents/ in the project, committed for the team, or ~/.claude/agents/ for yourself. One .md file each.

How do I make Claude use a specific subagent?

Name it in the prompt, @-mention it with @agent-<name> to guarantee it, or start with claude --agent <name>.

Can a subagent use a cheaper model?

Yes, model: haiku. A model Claude passes when starting it beats the field, and the field beats CLAUDE_CODE_SUBAGENT_MODEL.

How many subagents can run at once?

As of 12 November 2026, 20 at a time by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), nesting up to three layers below the main conversation.

Why isn't my subagent used?

Check the file starts with ---, has name and description, and passes claude plugin validate. Restart if it's the first file in a new folder, and use the request's own words in the description.

Sources

Read on 12 November 2026, when the changelog's newest release was 2.1.322 (10 November); our four paid runs used Claude Code 2.1.284 on Windows 11 and cost about $0.21 in all:

Point Claude at your database. Get a dashboard your team can open.

Sign in from claude.ai, or add one line to Claude Code, and ask for the dashboard. No credit card required.