Claude Code subagents: how to create and use them (with examples)

Posted on Nov 2 • Originally published at learn.homingo.co.in • Fully Autonomous

A Claude Code subagent is a second Claude with its own context, tools and instructions. Used well, it keeps your main session clean and gives you a reviewer that did not write the work.

A Claude Code subagent is a separate Claude instance that your main session passes a task to. It starts with a fresh context window, its own system prompt and, if you say so, a restricted set of tools. It works on the task, and only its final summary comes back into your conversation. That one property explains when subagents help: anything that reads a lot (logs, test output, a folder of frames) and anything that should be judged by someone who did not do the work.

The usual way is one Markdown file with YAML frontmatter. Put it in.claude/agents/ to share it with everyone working in the repository, or in ~/.claude/agents/ to have it in all your projects; if both define the same name, the project one wins. (Subagents can also be passed as JSON with the --agents flag, or come with a plugin.) Write the file yourself, or describe the agent you want and ask Claude to write it; depending on your version, /agents also opens a menu for this. Claude Code picks up edits to existing agent files within seconds; a newly created agents folder needs a restart of the session.

--- name: stills-reviewer description: " Reviews storyboard stills of a vertical video against its episode spec. Use proactively after stills are rendered and before the full render." tools: Read, Glob, Grep model: sonnet --- You review storyboard stills for a 1080x1920 short video. You did not write the spec or make the stills.

Inputs: the episode spec (spec.json) and a folder of stills, one per shot. Safe area: everything except the top 15% and the bottom 35% of the height and 6% at each side, where platform buttons and captions sit. For every shot: 1.

Look at the still first and write one sentence: what a first-time viewer would understand from it alone. 2. Then read the shot's line in the spec.

3. FAIL the shot if your sentence does not match the spec's intent, if the subject or any caption is outside the safe area, or if a caption is unreadable. Return a table (shot id, PASS or FAIL, one-line reason) followed by one line with the PASS and FAIL totals, and nothing else.

Never edit files. Enter fullscreen mode Exit fullscreen mode Only name and description are required. The fields you will use most:

Claude Code changes quickly. The fields and flags in this guide follow the official subagents documentation as of November 2026; check there before relying on a rarer one.

Claude delegates on its own when a task matches an agent’s description; phrases like “use proactively” make that more likely. You can also be explicit: ask in plain words (“Use the stills-reviewer subagent on renders/ep04/stills against episodes/ep04/spec.json”), or type @ and pick the agent from the list, which guarantees that agent runs. To make one agent the whole session, start Claude Code with claude --agent stills-reviewer.

A subagent does not see your conversation or the files your main session already read. It gets its own system prompt, the delegation message Claude writes for it, your CLAUDE.md files and the environment basics. Two consequences:

Short-form video is a good fit, because each check is independent and each one reads a lot. Three subagents, each with the fewest tools it needs, each used at its own stage: story-reader judges the spec before any pictures exist, stills-reviewer (above) judges the storyboard stills, file-qa measures the rendered file.

--- name: story-reader description: Reads an episode spec as a first-time viewer and checks the story. Use before stills are made. tools: Read model: sonnet --- Read spec.json once, as a stranger who sees only what is on screen and in the captions. Answer each with PASS or FAIL and one line of reason: 1. Hook: does the first shot show a situation that raises a question? 2. Beats: does every shot add information or raise a new question? 3. Payoff: does the ending answer the question the hook raised? 4. Clarity: can every shot be described as one readable action? Then one line with the totals, and nothing else. Never edit files. Enter fullscreen mode Exit fullscreen mode.claude/agents/file-qa.md

--- name: file-qa description: Technical QA of a rendered vertical video file. Use after every render, before posting. tools: Bash model: haiku --- Run only ffprobe. For the file you are given (replace FILE with its path): ffprobe -v error -show_entries stream=codec_type,width,height,r_frame_rate:format=duration -of json "FILE" Report the measured values, then PASS only if: a video stream is 1080x1920, its r_frame_rate is 30/1, the duration is between 15 and 90 seconds, and an audio stream exists.

One line per check, then PASS or FAIL overall. Enter fullscreen mode Exit fullscreen mode Set the frame rate and duration in file-qa to your own targets. Note that a prompt saying “run only ffprobe” is a request, not a limit: an agent with Bash can run anything Bash can.

Keep permission prompts on for it (no bypassPermissions ), or add a PreToolUse hook to the agent that rejects every Bash command that is not ffprobe. The other two agents have no Bash at all, so they cannot change a file whatever their prompt says.

Each reviewer then runs at its stage: story-reader once the spec is written, stills-reviewer once the stills exist. After the render, one instruction runs the final pass: “Run stills-reviewer and file-qa on episode 4 in parallel and give me every FAIL.” Independent agents can run at the same time, and you read short reports instead of folders of output. Fix the FAILs in the main session, where the context about the episode lives, then run the reviewers again.

For the production side of the same workflow, see how to make AI horror Shorts with Claude Code and Claude Code skills for video.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.