Claude Code Subagents & Skills: The Practical Guide

An agent that does everything does nothing well. Use Claude Code seriously for more than a week and you know the pattern: brilliant on the first task, mediocre on the fifth, losing the thread by the tenth — because a single context is supposed to be everything at once: reviewer, builder, researcher, historian.

Claude Code ships two built-in answers that surprisingly few teams use: subagents and skills. Both are Markdown files. Both take an hour to build. Together, they're the difference between a clever toy and a tool your whole team uses equally well every day.

The map: subagent, skill, MCP server

Three abstractions, three jobs — mixing them up is the most common beginner mistake:

Mnemonic: skills are knowledge, subagents are division of labour, MCP is a connection to the world. How to build the latter is in the MCP tutorial — today is about the first two.

A skill in 20 minutes — from a real example

Skills live as SKILL.md in .claude/skills/<name>/ inside the project. The frontmatter says when the skill applies; the body says how to work. A real example from our marketing repo — a skill that makes SEO audits repeatable:

---
name: geo-score
description: Use when auditing this site's AI-search readiness —
  after changing structured data, meta tags, or llms.txt.
---

# GEO Score Audit

1. Render the key pages and extract JSON-LD, meta, hreflang.
2. Score against the checklist below (0–100).
3. Append the result to docs/GEO-SCORE.md — never overwrite history.

## Checklist
- Entity graph present, @ids stable … (etc.)

The point isn't the content — it's the effect: before, audit quality depended on who asked and how. After, everyone on the team (and every future agent run) produces the same audit against the same bar. A skill is codified team convention that the agent discovers on its own.

The craft is in the description field: it decides whether the agent loads the skill at the right moment. Write it as a trigger ("Use when …"), not a summary.

A subagent in 20 minutes

Subagents live in .claude/agents/<name>.md — YAML frontmatter plus a system prompt. The most important effect: they run in their own context window. A research job across thirty files no longer burns your main session's memory.

---
name: review-gate
description: Adversarial code reviewer. Use before merging
  agent-generated changes.
tools: Read, Grep, Glob
---

You are a skeptical reviewer. You did NOT write this change.
Actively hunt for defects: edge cases, missing tests,
architecture violations. Report findings with file and line.
You never modify code — you report.

Two decisions make the difference:

1. Cut down tool permissions. The reviewer above can read but not write — it cannot "quickly fix" its own criticism. Role separation, technically enforced instead of hoped for.
2. One role per subagent. "Research and implement and test" is not a subagent, that's the main session. The sharper the role, the better the output — the same principle as with human reviews.

How the pieces fit together

The pattern that has held up for us: the main session orchestrates and implements. Skills hold the conventions (how we spec, audit, release). Subagents take the context-hungry or role-foreign parts — research before building, review after building. And MCP servers connect the outside world.

Cut it this way and you get something bigger than the sum of its parts: a workflow that works even when it's not the team enthusiast driving it, but anyone on a Tuesday afternoon.

What you can do this week

Build one skill for the one thing your team constantly does differently — the review ritual, the release checklist, the audit. Twenty minutes of Markdown. Measure the effect by how often someone asks "how do we do this again?" over the next two weeks.

More build guides like this — subagents, skills, MCP, multi-agent patterns — land regularly on the blog; the newsletter delivers the next one first.