Claude Code subagents：建立與使用方法（附範例）

Originally published on Homingo Learn.

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.

What is a Claude Code subagent?

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.

How to create a Claude Code subagent

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.

.claude/agents/stills-reviewer.md

---
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.

Only name and description are required. The fields you will use most:

• name: the unique identifier you call the agent by. Lowercase words joined by hyphens are the safe convention.
• description: when Claude should pass work to this agent. It is the routing rule, so write it like the request it should catch.
• tools: an allowlist, comma-separated or as a YAML list. Leave it out and the agent inherits every tool available to subagents. A reviewer that only has Read, Glob, Grep cannot change anything by accident. disallowedTools is the opposite: a denylist.
• model: sonnet, opus, haiku, a full model ID, or inherit (the main session’s model). Routine checks run well on a smaller, cheaper model.
• maxTurns, permissionMode, hooks, skills (skills preloaded into the agent) and isolation: worktree (work in a temporary git worktree) cover the rarer cases.

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.

How to use a subagent: automatic and explicit delegation

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.

Fresh context: what the subagent does not know

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:

• Put the method in the agent file, not in the chat. Anything the agent needs every time (what to check, what a FAIL is, what to return) belongs in its prompt.
• Ask for a short, fixed return format. The summary is all that comes back. A table of PASS and FAIL lines costs your main session a few hundred tokens; a raw dump of everything the agent read costs thousands and defeats the point.

Example: three reviewer subagents that check a reel

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.

.claude/agents/story-reader.md

---
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.

.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.

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.

Subagents or skills?

• A skill is a method the working session loads when it is relevant (only its description is always in context): steps, reference files and scripts. Use it for how to do a job. See how to write a SKILL.md.
• A subagent is a separate worker with its own context. Use it to keep heavy reading out of your session, to run independent checks in parallel, or to get a review from someone who did not write the work.
• Together: a production skill does the work in the main session; reviewer subagents check it. If a reviewer needs shared rules, preload only the checking part (a QA skill) through the skills field, not the production method, so it still judges as an outsider.

Common mistakes

• Every tool for every agent. A reviewer with write access will eventually “fix” what it was asked to judge. Restrict it.
• A subagent for a two-line job. Each one starts cold and has to gather its own context; small, quick edits are faster in the main session.
• Expecting it to remember the chat. If the agent needs a decision you made earlier, it goes in the delegation message or in the agent file.
• Long descriptions. Every agent’s description sits in the main session’s context. Keep it to the trigger; move the method into the body.

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.