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

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:

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:

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

A short checklist

The handbook covers running Claude Code on a server long term: sessions, alerts, backups and rules for what the agent may never do: Pocket Server.