Claude Code Subagents and Skills: Complete Guide [2026]

A subagent is a separate Claude instance the main agent invokes to delegate a specific type of task. According to the official documentation, each subagent runs in its own context window, with its own system prompt, access to specific tools and independent permissions. When Claude finds a task that matches a subagent's description, it delegates to it; the subagent works on its own and returns a summarized result.

The main benefit is context preservation. If a secondary task is going to flood your conversation with search results, logs or file contents you will never look at again, that work goes to a subagent: the noise stays in its window, and only the conclusion comes back to your main conversation.

Where subagents live

A subagent is a Markdown file with YAML frontmatter. Its location defines its scope, and when two share a name the higher-priority one wins:

Project subagents (.claude/agents/) get committed to the repository: the whole team uses and improves them with version control. User subagents (~/.claude/agents/) are personal and travel with you across projects.

A subagent's frontmatter

Four fields define the behavior: name, description, tools and model. A code-review subagent, taken from the official tutorial, looks like this:

---
name: code-improver
description: Scans files and suggests improvements for readability,
  performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

A skill is a directory with a SKILL.md file that packages procedural knowledge: instructions, checklists, output formats, reference material. Claude loads it automatically when the request matches its description, or you invoke it with /skill-name. The official skills documentation gives the exact creation criterion: create a skill when you find yourself pasting the same manual or multi-step procedure into the chat over and over, or when a section of your CLAUDE.md stopped being a fact and became a procedure.

The key difference with CLAUDE.md is deferred loading: CLAUDE.md content enters the context every session, while a skill's body loads only when used. In the official doc's words: "long reference material costs almost nothing until it is needed". That makes skills the right place for long procedures you do not want to pay for in tokens all the time.

One fact that confuses many people: custom commands merged with skills. A file in .claude/commands/deploy.md and a skill in .claude/skills/deploy/SKILL.md both create /deploy and work the same; skills add supporting files, invocation-control frontmatter and automatic loading.

Structure of a skill

my-skill/
├── SKILL.md           # main instructions (required)
├── references/        # detailed reference documentation
├── assets/            # templates, output examples
└── scripts/           # scripts Claude can execute

Only SKILL.md is required. The rest is material Claude loads on demand if SKILL.md references it. The official advice: keep SKILL.md under 500 lines and move detail into separate files.

Where skills live

If two skills share a name, enterprise overrides personal and personal overrides project. The command name comes from the directory name: .claude/skills/deploy-staging/SKILL.md is invoked as /deploy-staging. Edits to an existing skill take effect in the current session without restarting.

A skill's frontmatter

The two invocation-control fields are among the most underrated tools: they separate "knowledge Claude applies when appropriate" from "actions only a human triggers". In our system, everything touching money or client communication is manual invocation.

The short rule: a skill defines WHAT to know how to do; a subagent defines WHO does it and with what context. They do not compete, they complement each other.

Everything above is the mechanics. What follows is what we learned operating this for real: at Duotach we built an internal system on Claude Code to deliver SEO and GEO services to multiple clients, and its current state is 53 skills in production. The architecture has three layers:

The pattern that makes this work is not the number of skills but the closed loop: every piece of work goes through a validator with an objective stop condition before moving on. Without that layer, an agent system produces volume, not quality. With it, the criterion for "this is right" stops living in someone's head and becomes versioned in the repository.

The full system, with results, is documented in our case study, and the general introduction to agents is in the AI agents with Claude Code guide.

The ones we saw (and made) building the system:

Minimum reproducible setup, verified against the official documentation.

---
description: Summarizes recent repository changes in plain
  language. Use when asked for a summary of what changed.
---

Review the latest commits with git log and summarize the changes
in 3-5 bullets, grouped by area. Close with one line on what
deserves a closer review.

From there, the path is incremental: every time you repeat a procedure, new skill; every time a task dirties your context, new subagent; every time a skill produces important deliverables, a validator to audit it.

For a team already using Claude (not just developers), skills and subagents are the difference between "each person chats with the AI their own way" and "the company has versioned procedures the AI executes the same way every time". The quality manual stops being a PDF nobody opens and becomes a skill applied automatically to every task.

At Duotach we work on this in two ways:

If you are evaluating this for your team, write to us and we will discuss it over your concrete case. And if you are just arriving at Claude Code, start with the pricing and usage guide.

Frequently Asked Questions