Claude guide

How to create a Claude agent: start with one subagent file

There are two ways to use a Claude agent. In the Claude app you describe the outcome and hand over the whole task. In Claude Code you create your own subagent from one file that states its role. This guide covers how to create, save and call a subagent, and how it differs from skills and agent teams.

Skillshop operator and creator of the Maker Evan YouTube channel
9 min read

Translated from Korean. View original. Some screenshots are available in Korean only.

A main conversation handing research, review and testing to subagents and getting short summaries back
In this guide
  1. What does “Claude agent” refer to?
  2. How do I hand over work without code?
  3. What is a subagent, and why use one?
  4. How do I create my first subagent?
  5. Where does the file go, and what goes in it?
  6. How do I call the subagent I created?
  7. How do skills, subagents and agent teams differ?
  8. What should I check when a subagent is not used?
  9. When is it better not to use one?
  10. Frequently asked questions
  11. Sources

What does “Claude agent” refer to?

“Claude agent” covers several things. In the broadest sense it means Claude doing more than answering: reading files, using tools and working through several steps on its own. Handing a whole task to the Claude app counts, and so does keeping a subagent for each role in Claude Code.

To begin, remember two paths. To hand over document and research work without code, use the Claude app. To keep a dedicated role for work you repeat, use subagents in Claude Code. Agent teams and agent view can wait until later.

OptionWhat it isStatus
Hand it to the Claude appDescribe the outcome in a conversation and Claude works through the steps. The former Cowork is now part of chatRolling out on paid plans
SubagentsWorkers inside one Claude Code session that work separately and return only a summaryBuilt in
Agent viewDispatch and monitor several background sessions from one screenResearch preview
Agent teamsSeveral sessions that share a task list and message each otherExperimental, off by default
Agent SDKThe same agent capabilities in your own app, in Python or TypeScriptFor developers
Based on the Claude Code documentation and Anthropic announcements, checked in November 2026.

The comparison table from the official documentation. Check the linked page for the current status of each option.

View original Korean screenshot
Claude Code 한국어 문서의 ‘에이전트를 병렬로 실행하기’ 표다. 서브에이전트, 에이전트 뷰, 에이전트 팀, 프로젝트, 동적 워크플로우를 제공되는 기능과 사용 시기로 비교하고, 에이전트 팀이 실험적이며 기본적으로 비활성화돼 있다고 적혀 있다.
공식 문서의 비교표예요. 최신 상태는 연결된 공식 안내에서 확인해 주세요.출처: 클로드 코드 공식 문서 · 에이전트를 병렬로 실행하기

How do I hand over work without code?

Write the outcome you want in a conversation in the Claude app. Anthropic announced on September 16, 2026 that Cowork and chat had become one. In the new experience there is no mode to choose: Claude searches the web, reads your files, runs code and puts the results together. You get finished files back, such as documents, spreadsheets with working formulas and presentations.

The experience is rolling out in stages to the Pro, Max and Ultra plans, and on Team and Enterprise it depends on the organization's settings. Longer tasks keep running in the cloud after you close your laptop. Tasks that use folders or apps on your computer need the Claude desktop app open. A permission setting in the message box lets you choose whether Claude asks before each action (Manual) or keeps working while automated safety checks run (Auto).

Describe the outcomePull the main themes out of these five interview notes
Claude splits the workSearching, reading files, running code
Get files backDocuments, spreadsheets, presentations
Review and reviseAsk for changes in the same conversation
In the Claude app you start from the outcome, without choosing a mode.

What is a subagent, and why use one?

A subagent is a dedicated worker for one kind of task. According to the Claude Code documentation, a subagent works in its own context window and returns only a summary. That keeps search results, logs and other content you will not look at again from filling up the main conversation.

Claude Code already includes built-in subagents: Explore, which searches files and code read-only; Plan, which gathers context before a plan is presented; and General-purpose, which takes multi-step tasks. You can add subagents for your own work. You can restrict the tools so one only reads, or send lighter work to a faster model.

Working in the main conversation
  • Files read and search results pile up in the conversation
  • Good for work refined through back-and-forth
  • Several steps share the same context
Handing it to a subagent
  • It works separately and only a summary comes back
  • You can restrict the tools it may use
  • Good for splitting off independent work
The longer the output and the more independent the task, the better a subagent fits.

How do I create my first subagent?

A subagent is one Markdown file with its configuration at the top. You can write it by hand, but the quickstart in the documentation shows how to ask Claude to write it. In Claude Code, describe the subagent you want and where to save it, and Claude writes a file with a name, a description, a tool list, a model and instructions.

Once the file exists, open it to check that it matches what you asked for, then call it by name. If Claude cannot find the new subagent, restart Claude Code. Note that the “/agents” command no longer opens a creation screen. It only prints a notice telling you to ask Claude or edit the files directly.

An example request to type into Claude Code
Create a personal subagent called draft-reviewer in ~/.claude/agents/.
It reads a draft article and lists awkward sentences, claims that need fact-checking and missing points.
Make it read-only so it never edits files, and have it use Sonnet.
The resulting file: ~/.claude/agents/draft-reviewer.md
---
name: draft-reviewer
description: Reads a draft article and reports awkward sentences, claims that need fact-checking and missing points. Use when asked to review a draft.
tools: Read, Grep, Glob
model: sonnet
---

You are an editor reviewing a draft article. Read the files and never edit them.
For each problem, quote the sentence, explain why it is a problem and give a corrected sentence.
Finish with a summary of the three things to fix first.
STEP 1Ask in plain languageState the role, where to save it, whether it is read-only and the model.
STEP 2Check the fileConfirm the name, description, tools and model match your request.
STEP 3Call it by nameUse the draft-reviewer subagent to review this draft.
The three steps of the quickstart in the documentation.

Where does the file go, and what goes in it?

Where you save the file decides where it applies. In a project's .claude/agents/ folder it works only in that project, and checking it into the repository shares it with your team. In ~/.claude/agents/ on your computer it works in every project. When the same name exists in more than one place, the higher-priority location wins, and the project comes before the personal folder.

Configuration goes between the “---” lines at the top, and the instructions the subagent follows go below. Only two fields are required: name and description. Claude uses the description to decide when to hand work to this subagent, so write which requests it is for in the words you actually use. Edits to the file are picked up within a few seconds.

FieldRequiredWhat to write
nameYesA unique name for the subagent. It cannot contain a colon (:)
descriptionYesWhen Claude should delegate to this subagent
toolsNoThe tools it may use. If omitted, it inherits every available tool
modelNoA model such as sonnet, opus or haiku. If omitted, Claude Code chooses
skillsNoNames of skills to preload when it starts
The five fields to begin with, chosen from the frontmatter reference in the documentation.
  • my-project
  • .claude
  • agentsUsed only in this project
  • draft-reviewer.mdOne file per subagent
  • skillsSkills are kept separately here
Project subagents go under .claude/agents/. Personal ones go under ~/.claude/agents/.

The table of locations and priority in the official documentation.

View original Korean screenshot
Claude Code 한국어 문서의 ‘서브에이전트 범위 선택’ 표다. 관리형 설정, --agents CLI 플래그, .claude/agents/, ~/.claude/agents/, 플러그인의 agents/ 디렉터리가 범위와 우선순위 1부터 5까지로 정리돼 있다.
공식 문서의 저장 위치와 우선순위 표예요.출처: 클로드 코드 공식 문서 · 서브에이전트 범위 선택

How do I call the subagent I created?

Claude hands work over on its own. It decides whether to delegate from your request, the subagent's description and the current context. The more specific the description, the more reliably the subagent is used.

There are three ways to call one directly. Mention its name in the request and Claude usually delegates. Type “@” and pick it from the list to tell Claude to run that subagent for the task. To run a whole session as one subagent, start it from the terminal with “claude --agent name”.

Ask by name
Use the draft-reviewer subagent to review the guide.md draft
Point to it with @
@agent-draft-reviewer review the guide.md draft
Run the whole session as the subagent (terminal)
claude --agent draft-reviewer
Automatic delegationDefaultClaude delegates when the request matches the description
Naming itLightMention the subagent's name in the request
@-mentionDefiniteTells Claude this subagent should do this task
--agentWhole sessionStarts the session with that subagent's tools and model
Each row down is a stronger way to choose the subagent.

How do skills, subagents and agent teams differ?

A skill is a method, and a subagent is a worker that takes the job separately. A skill is loaded into the main conversation's context and supplies the order of work and the criteria. A subagent works in a separate context and returns only a summary. The documentation also suggests a skill when you need a reusable workflow that runs in the main conversation.

You can use them together. List skill names in the skills field of a subagent file and the full content of each skill is injected into the subagent when it starts. Agent teams go a step further: several sessions share a task list and message each other. They are still experimental and off by default, and they use far more tokens than a single session, so consider them only when subagents are not enough.

Preload a skill into a subagent
---
name: report-writer
description: Writes a draft weekly report in the team's format.
skills:
  - weekly-report-format
---

Write the draft report following the format and order in the preloaded skill.
AspectSkillSubagentAgent team
What it isInstructions and material that describe a methodA dedicated worker that works separatelySeveral sessions that talk to each other
Where it worksThe main conversation's contextIts own contextAn independent context per session
ResultContinues directly in the conversationOnly a summary returns to the main conversationTeammates message each other directly
StatusBuilt inBuilt inExperimental, off by default
Summarized from the Claude Code documentation.

What should I check when a subagent is not used?

First check that the file was loaded. According to the documentation, Claude Code skips files whose format has a problem. Without a name it treats the file as a document, and it skips a file with no description or with YAML it cannot parse. If the opening “---” is not the first line, it reads the file as having no configuration.

If the file loads but is not used automatically, revise the description. Write which requests it is for in the words you actually use, and compare with what happens when you point to it with “@”. To look further, run “claude --debug” in the terminal and read the debug log.

  • Is the opening “---” on the first line of the file?
  • Are both name and description present?
  • Does the name contain a colon (:) or start with “-”?
  • Is there another subagent with the same name in a different folder?
  • Does it run when you point to it with “@”?

When is it better not to use one?

Not everything needs to be split up. The documentation says to use the main conversation for work that needs frequent back-and-forth, for phases that share significant context such as planning, implementing and testing, and for quick, targeted changes. A subagent starts fresh, so it needs time to gather context.

Consider the cost too. A subagent's requests count against the same usage limits as the main conversation, and running several at once multiplies token usage. Claude Code is included in every paid plan and shares its limits with chat. Create one subagent, use it on real work a few times, then add more.

Frequently asked questions

Do I need to know how to code to create a Claude agent?

No. A subagent is a single Markdown file, so you do not write code. Describe the role and where to save it in Claude Code, and Claude writes the file. If the terminal is unfamiliar, begin by describing the outcome you want in a conversation in the Claude app.

How is a subagent different from a skill?

A skill is a set of instructions describing a method, and it runs in the main conversation's context. A subagent is a worker that works in a separate context and returns only a summary. You can combine them by listing skills in the subagent's skills field.

Does using subagents consume more of my usage?

A subagent's requests count against the same usage limits as the main conversation, and running several at once multiplies token usage. In return, long search results and logs stay out of the main conversation, which helps it last longer.

Can a subagent call another subagent?

According to the documentation, by default subagents can spawn their own subagents up to three layers below the main conversation. To stop one subagent from doing so, leave Agent out of the tools list in its file.

Where did Claude Cowork go?

Anthropic announced on September 16, 2026 that Cowork and chat had become one Claude. On accounts with the new experience there is no “Chat” or “Cowork” option to choose, and you can hand over a whole task from any conversation. Existing Cowork tasks and settings carry over.

Sources