Claude Code subagents, skills and commands, explained

Claude Code gives you three ways to extend it: subagents, skills and slash commands. They live in the same .claude/ folder, they are all plain markdown, and almost everyone uses them wrong at first, usually by stuffing everything into one giant CLAUDE.md and hoping for the best.

Here is what each one actually does, when to reach for it, and how they work together.

Subagents: specialists with their own context window

A subagent is a markdown file in .claude/agents/ with frontmatter and a system prompt. When Claude Code delegates a task to it, the subagent runs in its own context window, does the work, and reports back a summary.

---
name: billing-engineer
description: Stripe integrations, webhooks, dunning, entitlements.
  Use for anything that touches money.
tools: Read, Edit, Bash, Grep
---

You are a senior billing engineer. Before writing code, read
CLAUDE.md and the existing Stripe integration. Always verify
webhook signatures. Never log full card or customer objects...

Two properties make subagents powerful:

• Context isolation. A subagent can read 40 files and burn 80k tokens figuring something out, and your main conversation only receives the conclusion. Your main thread stays clean.
• A persistent point of view. The system prompt is always there. A security auditor agent is paranoid on every run, not just when you remember to ask for paranoia.

Use a subagent when the work benefits from a specialist identity or would flood your main context: audits, reviews, research across many files, anything with strict rules that must never be forgotten.

Skills: playbooks loaded on demand

A skill is a folder in .claude/skills/ with a SKILL.md inside. It describes a procedure: how to do a security audit, how to write a launch email, how to migrate a database. Claude Code reads the skill's description and loads the full playbook only when the task matches.

That on-demand loading is the point. A 2,000 word checklist for Stripe webhook testing would be dead weight in every conversation, but as a skill it costs you almost nothing until the day you are testing Stripe webhooks.

Use a skill when the knowledge is procedural: step by step processes, checklists, house style guides, templates with instructions. If you find yourself pasting the same long instructions twice, that is a skill.

Slash commands: buttons you press

A command is a markdown file in .claude/commands/. Type /ship and Claude Code runs the prompt inside ship.md, with any arguments you pass. Commands are the entry points, the things you actually type at 11pm.

Good commands are short. They do not contain the knowledge, they orchestrate it: a /security-scan command might invoke the security-auditor subagent, which follows the audit skill, and then ask for a prioritized report.

How to decide, in one line each

• Who does the work and with what standards: subagent.
• How the work gets done, step by step: skill.
• What you type to kick the work off: command.

The mistakes that waste your context window

One mega CLAUDE.md. If your CLAUDE.md is 3,000 lines of procedures, every conversation pays for all of it. Move procedures into skills, identities into agents, keep CLAUDE.md for facts about your project. We wrote a full guide on what belongs in CLAUDE.md.

Generic agents. An agent whose prompt is "you are a helpful senior developer" adds nothing. The value is in specificity: which tools it may use, what it must always check, what it must never do.

Commands that duplicate each other. Ten commands with 90 percent identical prompts become unmaintainable fast. Extract the shared part into a skill and keep the commands thin.

What a full setup looks like

A working SaaS setup is not one clever agent, it is a roster. A tech lead that reviews architecture, a billing engineer that knows Stripe, a QA engineer that tests where money lives, plus marketing: a copywriter, an SEO strategist, an email marketer. Each with its own rules, all reading the same CLAUDE.md so they know your product, your customers and your voice.

You can build that roster yourself over a few weekends. That is genuinely how we started. Or you can start from one that already exists and adapt it.