📝 Written ● Intermediate Updated 2026-05-13

How do I write a subagent for LingCode?

TL;DR: Create a markdown file in .claude/agents/<your-agent>.md with frontmatter (name, description, optional tools) and a system prompt below. The main agent can delegate to it via the Agent tool — useful for tasks with isolated context.

A subagent is a specialist the main agent can delegate to — its own system prompt, its own tools, its own context window. Use one when a task has a clean boundary, when its working assumptions differ from the conversation around it, or when you simply don't want it polluting the main context.

The default mode of working with an agent is one long, growing conversation. Every prompt, every tool result, every file the agent reads — all of it accumulates in the same context window. That works fine for short tasks. It works badly for long ones, because two failure modes show up together. The first is dilution: the longer the chat, the more competing instructions the model is trying to balance, and the more important things start to drift. The second is leakage: a research task that should have been a read-only exploration ends up with the agent suggesting code changes it has no business making yet, because the main context is in "write" mode.

A subagent fixes both. It's a fresh agent invocation with its own system prompt and its own tool set, called by the main agent like a tool. The subagent does its job in isolation, returns a structured result, and disappears — its 20,000 tokens of intermediate scratch work never enter the parent conversation. Only the summary comes back.

The art of subagents is figuring out which tasks deserve one. The wrong answer is "everything" — delegating trivial work to subagents adds latency and confusion. The right answer is "tasks with a clean boundary and a different mental mode." Code review. Test generation. Codebase exploration. Anything that takes meaningful work but produces a compact result.

What you'll learn

The subagent file format (markdown with frontmatter)
How a description guides delegation
Restricting which tools a subagent can use
When to write a subagent vs. a skill vs. a slash command
Common patterns: code review, test writer, doc summarizer

Step 1: The file format

One markdown file per subagent

Subagents live in .claude/agents/<name>.md (project-local) or ~/.claude/agents/<name>.md (user-wide). Each file is markdown with YAML frontmatter:

---
name: code-reviewer
description: Use this for in-depth code review of staged or unstaged changes. Invoke when the user says "review this," "look over this diff," or before they push.
tools: [Read, Grep, Glob, Bash]
---

# Code reviewer

You are a senior code reviewer. Read the staged diff with `git diff --staged`,
and the unstaged diff with `git diff`. For each meaningful change:

- Note what was changed and whether it accomplishes the stated goal.
- Flag bugs, race conditions, and security issues.
- Flag missing tests for non-trivial logic.
- Flag style violations only if egregious.

Do NOT propose fixes — that's the main agent's job. Report findings only.

The frontmatter has three meaningful fields: name (used to invoke), description (used for routing), and optionally tools (a restricted tool whitelist).

Step 2: Description guides delegation

The description is the routing logic

When the main agent decides whether to delegate, it reads available subagents' descriptions and picks the one whose description matches the situation. A vague description ("helps with code") gets ignored; a specific one ("Use this for code review of staged or unstaged changes") gets picked.

Write descriptions in the form "Use this for [task]" or "Invoke when the user [says/wants/needs] [thing]." Imagine future-you reading the description cold — would you know when to dispatch?

The description is read by the model, not by humans. Be specific about triggers, not flowery about capabilities. "Use this when the user asks for tests" beats "An expert at writing comprehensive test suites with deep knowledge of testing patterns."

Step 3: Restrict tools

A subagent should only do its job

By default a subagent can use any tool the main agent can. Restrict it with the tools field in the frontmatter to the minimum set needed for its purpose:

A code reviewer needs Read, Grep, Glob, and maybe Bash for git commands — and should NOT have Edit, Write, or anything destructive. It reviews; it doesn't fix.
A research subagent needs reading tools and probably WebFetch. It explicitly should NOT have Edit or Write.
A test writer needs Read, Grep, Edit, Write, Bash. The full edit set, but scoped to test files by the system prompt.

The tool list is policy, not preference. A subagent that lacks Edit literally cannot edit, regardless of what the model "wants" to do. This is exactly what you want for a code reviewer: even if the model is tempted to "just fix this small thing," it can't.

Step 4: Invocation — implicit and explicit

Two ways the main agent delegates

Subagents are invoked two ways:

Implicit: the main agent reads the situation, sees a matching subagent description, and delegates without being told. This is the common case for well-described subagents. You see it happen as a tool call named "Agent" with the subagent's name in the parameters.
Explicit: you say "use the code-reviewer subagent on this diff." The main agent dispatches as instructed. Useful when you know the right subagent and don't want to leave routing to chance.

Either way, the subagent gets a fresh context window, does its work, returns a summary, and disappears. The main conversation continues with just the summary in scope.

Step 5: When a subagent is the wrong tool

Three smells

The task is conversational. Back-and-forth dialog doesn't fit subagents — they return one summary, not a chat. If you need iteration, the main agent should handle it.
The result has to be all the work product. Subagents return summaries; their detailed work is gone. If you wanted to see the agent's actual diff exploration, a subagent loses it. Run in the main context.
It's a one-line operation. "Format this file" doesn't need a subagent. The overhead of spinning one up is larger than the task. Reserve subagents for work that justifies a fresh context window.

Step 6: Subagent vs. skill vs. slash command

Three customization tools, three different jobs

Skill — teaches the agent how to do something. The main agent reads the skill and applies it within the current context. No isolation.
Subagent — delegates a task to a fresh agent with its own context. Isolation. Returns only a summary.
Slash command — a user-typed shortcut that triggers a known prompt template. Convenience, not isolation.

Rule of thumb: if you want isolation, write a subagent. If you want different behavior in the same context, write a skill. If you want a fast trigger, write a slash command.

Subagents see the main conversation only in summary form. When the main agent dispatches, it passes a brief — "review the staged diff and report findings." The subagent doesn't see the full chat history. Write subagent prompts that work from cold context.