Claude Code subagents and skills
The difference in one rule, two files you can copy, and the header fields each one reads.
Claude Code has two ways to hand work a shape of its own: a subagent and a skill. They are easy to mix up, because both are a Markdown file with a short header. They solve different problems. A subagent does a job in a separate context and brings back only the answer. A skill is a set of instructions Claude loads when the task calls for them. This guide shows both, with files you can copy. Field names and paths were checked against Claude Code 2.1.327; run claude --help on your version.
Subagent or skill: the one-line rule
- Subagent: use it when the job is noisy and you only want the result. A search through hundreds of files, a log analysis, a review. The subagent works in its own context window, so the files it reads never fill yours. Only its final answer comes back.
- Skill: use it when you want Claude to follow the same procedure every time. A release-notes routine, a commit format, a checklist. A skill adds instructions to the conversation you are already in, or can be set to run in a fork.
Claude Code already ships subagents such as Explore (a read-only search agent), Plan and general-purpose. You only write your own when the built-in ones do not fit.
Write a subagent
A subagent is a Markdown file. The header between the --- lines configures it, the text below is its system prompt. Put it in .claude/agents/ to share it with a project, or in ~/.claude/agents/ to have it in every project. A file without a name is skipped.
mkdir -p .claude/agents
cat > .claude/agents/log-reader.md <<'EOF'
---
name: log-reader
description: Reads long log files and reports only the lines that matter. Use proactively when a task needs a look into logs.
tools: Read, Grep, Glob
model: sonnet
maxTurns: 12
---
You read log files. Search with Grep first, read only the matching
regions, and answer with at most ten lines: what failed, when, and the
likely cause. Never modify files.
EOF
The description is what Claude reads to decide when to hand a task to this agent, so write it as a trigger ("Use when ...", "Use proactively when ..."), not as a title. tools replaces the default tool set; here the agent can only read and search. Leave it out and the agent inherits every tool of the main session.
The other header fields this version reads:
disallowedTools: tools to remove from the default set. Ignored iftoolsis set.model: an alias such assonnetoropus, a full model ID, orinheritfor the main model.effort:low,medium,high,maxor an integer.permissionMode:default,acceptEdits,planorbypassPermissions. Preferplanfor agents that should only look.maxTurns: a positive integer; the agent stops after that many turns.skills: skills preloaded into the agent.mcpServersandhooks: servers and hooks that exist only while this agent runs.memory:user,projectorlocal, a folder where the agent keeps notes between runs (forproject:.claude/agent-memory/<name>/).background:trueto run it as a background task by default.isolation:worktreeruns it in a temporary git worktree.
The /agents wizard of older versions is gone: in 2.1.327 the command only tells you to ask Claude to create the subagent for you, or to edit the files in .claude/agents/ directly. Either works. Reading the file Claude wrote is a good habit anyway.
For a one-off or a scripted run you can pass agents as JSON without any file: claude --agents '{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}' (with --print the argument may also be a path to a file). --agent <name> starts the whole session as one agent.
Write a skill
A skill is a folder with a SKILL.md file, in .claude/skills/<name>/ (project) or ~/.claude/skills/<name>/ (all projects).
mkdir -p .claude/skills/release-notes
cat > .claude/skills/release-notes/SKILL.md <<'EOF'
---
name: release-notes
description: Draft release notes from the git log since the last tag. Use when asked for a changelog or release notes.
allowed-tools: Bash(git log:*), Bash(git describe:*)
argument-hint: [since-tag]
disable-model-invocation: true
---
Write release notes for the changes since $ARGUMENTS (or the latest tag
if none is given). Group the entries under Added, Changed and Fixed.
EOF
You run it by typing /release-notes v1.4.0; whatever follows the name replaces $ARGUMENTS. /skills lists what Claude Code found. The fields this version knows:
descriptionandwhen_to_use: how Claude decides to use the skill by itself.allowed-tools: tools the skill may use without asking, such as the two narrow git commands above.argument-hint: the hint shown for the argument.disable-model-invocation: withtrueonly you can start it. Use that for anything with side effects.user-invocable: whether it shows up as a/command.context:inline(default) orfork; withforkthe skill runs as a subagent, andagentpicks which agent type.paths: glob patterns; the skill only loads when Claude touches matching files.model,effortandhooks, as for agents.
A skill costs little while idle: only its one-line listing sits in the context each turn, and the full SKILL.md loads when it runs. That is also why a vague description is a bug. If it does not say when to use the skill, Claude will not pick it.
Keep them safe
- Narrow tools first. A reviewer needs
Read,GrepandGlob, notBash. Add tools when a real task fails without them. - Do not hand out
bypassPermissionsin an agent file that sits in a repository others can clone. An agent or skill file is instructions plus rights; read one before you trust it, like any script. - Keep your hooks and deny rules in place and test that a subagent is stopped by them too, instead of assuming it. See the guide on blocking dangerous commands with a hook.
- Cap unattended work with
maxTurnsin the agent and--max-budget-usdon the command line.
A short checklist
- Noisy job, only the answer matters: subagent in
.claude/agents/. - Repeatable procedure: skill in
.claude/skills/<name>/SKILL.md. - The
descriptionsays when to use it, in one or two sentences. - Smallest possible
toolslist; side effects behinddisable-model-invocation: true. - After adding a file, check
/skillsor ask Claude to list its subagents; a file with a missingnameis skipped.