If you've started using Claude Code, you've probably run into two terms that sound similar but do very different jobs: agents and skills. This article breaks both down from scratch, shows how they connect, and — most usefully — shows what actually changes in the output depending on how you set things up. Here's a scenario to keep in mind as we go: imagine you're working on a project that already has a CLAUDE.md file with your general project rules. Now you need to add several new API endpoints to the codebase, each expected to follow the same conventions — validation, response shape, naming, rate limiting. This is exactly the kind of recurring, rule-heavy task where skills and subagents start to earn their keep, and we'll use it as the running example throughout. What's a Subagent? Start with the concrete thing: a subagent is a separate worker that Claude Code launches to do one focused job on its own — in its own isolated context window — and then reports back just a summary, without cluttering your main conversation. Think of it like handing a task off to a contractor: they go do their own research, their own work, in their own space, and hand back a finished report. The important part isn't secrecy — it's isolation: your main conversation doesn't need to hold the subagent's entire working process, only its result, which is what keeps the main session lean. A subagent works in a loop to get that job done: plan → act → observe → repeat until it's finished. It reads files, runs commands, checks the results, and keeps going until the task is complete — not a one-shot guess from memory. flowchart LR P["Plan decide the next step"] --> Ac["Act read a file, run a command"] Ac --> O["Observe check the result"] O -->|not done yet| P O -->|task complete| Done(["Report back"]) One more useful property: subagents can run in parallel. If a task naturally splits into independent pieces — say, reviewing three separate API modules — Claude Code can run multiple subagents concurrently instead of one after another, and collect their results once they finish. A Note on Terminology That loop — plan, act, observe, repeat — is actually the general definition of an agent. Claude Code itself is an agent; a subagent is just a second agent instance, launched by and subordinate to the main one (hence "sub"). This article uses "Claude Code" for the main system and "subagent" for the launched-worker feature, to keep things unambiguous. The Core Idea, in One Sentence A subagent answers "who does the work?" A skill answers "how should this kind of work be done?" They're not alternatives you choose between — the most useful setups combine them: a subagent gives you isolation and specialization, and a skill preloaded into it gives that specialist your team's actual playbook. You can use a skill without a subagent, a subagent without a skill, or both together — which is exactly what the running example below does. What's a Skill? A skill is a folder with a SKILL.md file: plain-language instructions (plus optional scripts or templates) that teach Claude Code how to do a specific recurring task your way. your-project/ ├── CLAUDE.md # always-loaded project rules ├── .claude/ │ ├── skills/ │ │ └── api-conventions/ │ │ └── SKILL.md # "how we write endpoints here" │ └── agents/ │ └── code-reviewer.md # a subagent definition Here's what that SKILL.md file actually looks like, for our running example — a set of conventions for writing API endpoints: --- name: api-conventions description: "Use when writing, editing, or reviewing REST API endpoint code (routes, controllers, request handlers) in this repo — covers response format, validation, naming, and rate limiting rules." --- # API Conventions - All endpoints return { data, error } shape - Use zod for validation - Endpoint names are kebab-case - Every endpoint must have a rate limiter The description field, in the frontmatter at the top, is the key mechanic: it's short, always-available metadata that Claude uses to judge when this skill is relevant to what you're doing. The content below it — the actual rules — only gets pulled into context once Claude decides the skill applies. That's how a project can have dozens of skills sitting around without bloating every conversation with all of them at once. Life Without a Skill Here's what tends to happen without one. Say a developer is adding endpoints one at a time, over several sessions, without an api-conventions skill in place: Endpoint 1 — Day 1 Endpoint 2 — Day 2 Endpoint 3 — New session Endpoint 4 — New dev Rules typed in prompt Forgot the rate limiter Reworded the shape rule Recalled rules from memory ✅ Followed ⚠️ Drifted ⚠️ Drifted ⚠️ Drifted None of this is a "bug" in Claude — it did exactly what it was told each time. The problem is there was never one single source of truth being consulted; every endpoint's standard is only as good as whatever the developer happened to type that day. A skill fixes exactly this: the conventions live in one file, get pulled in the same way every time, and nobody has to remember or retype them. The important point isn't just persistence across sessions, either — it's that the team's procedure becomes an explicit, reusable artifact instead of knowledge that only ever lived inside someone's prompt. The Subagent File Now let's wire the skill into a subagent. Here's a code-reviewer subagent that reviews endpoint code — notice it explicitly lists the api-conventions skill we just defined above, via the skills: field: --- name: code-reviewer description: Reviews code changes for correctness, style, and API convention compliance. Use after writing or editing API endpoints. tools: Read, Grep, Glob skills: [api-conventions] model: sonnet permissionMode: default --- You are a careful, no-nonsense code reviewer for this repository. When invoked: 1. Identify what files were just changed or created. 2. Check the code against the preloaded `api-conventions` skill. 3. Also check for general issues: error handling gaps, missing validation, unclear naming. 4. Do NOT rewrite the code yourself — report findings only. Output format: - ✅ What's correct / follows convention - ⚠️ Convention violations - 🐛 Bugs or risks - One-line verdict: Approve / Needs changes That skills: [api-conventions] line matters more than it looks. A subagent runs in its own isolated context and doesn't automatically inherit whatever the main session happens to know — if you forget to list a skill there, the subagent simply won't load it. It'll still check for generic issues, but it won't know your project's response shape, validation library, naming rule, or rate-limiter requirement even exist. It can end up approving code that quietly breaks your own conventions, simply because nobody told it those conventions were relevant to its job. Example: From Command to Code Let's see the skill actually do its job. Suppose the developer types: "make an endpoint for GET /books" Claude Code checks the descriptions of the skills available in the project, notices api-conventions matches ("writing... REST API endpoint code"), pulls in the full skill, and writes the endpoint using those exact rules: // routes/get-books.js import { z } from 'zod'; import rateLimit from '../middleware/rate-limit.js'; const querySchema = z.object({ limit: z.number().int().positive().max(100).optional(), offset: z.number().int().min(0).optional(), }); router.get('/get-books', rateLimit(), async (req, res) => { const parsed = querySchema.safeParse(req.query); if (!parsed.success) { return res.status(400).json({ data: null, error: parsed.error.message }); } try { const books = await Book.find(parsed.data); return res.json({ data: books, error: null }); } catch (err) { return res.status(500).json({ data: null, error: 'Failed to fetch books' }); } }); Every rule from api-conventions shows up here: the response is always { data, error }, zod handles validation, the route follows kebab-case, and there's a rate limiter on the handler. None of that was restated in the command — it came entirely from the skill. Output Comparison: Subagent vs. No Subagent Same command — "review my codebase" — run two different ways. Without subagent With subagent Skill loading Claude decides to use a relevant skill if the description matches Explicitly included via the subagent's skills: field Where it runs Main conversation Isolated context window What you see Tool activity and intermediate progress as part of the main session Just a clean summary/verdict Tool access Whatever your main session has Can be restricted (e.g. read-only) Best for Quick one-off checks Isolated, specialized, parallelizable, or permission-sensitive reviews Without a subagent, the work happens in the main session, so file reads and intermediate steps are part of that same conversation. With the subagent, your main conversation just receives something like this — notice how each line maps directly back to a bullet in the Output format section of the subagent file above: the generic "✅ What's correct / follows convention" instruction becomes a concrete, specific finding. ✅ Response shape matches convention on all 3 new endpoints ⚠️ POST /orders is missing a rate limiter (api-conventions rule #4) 🐛 No input validation on the `quantity` field in POST /orders Verdict: Needs changes Takeaways A subagent answers "who does the work"; a skill answers "how it should be done." They combine rather than compete. Subagents are isolated workers, useful for isolated, specialized, parallelizable, or permission-sensitive tasks — and they can run concurrently when a task splits into independent pieces. Skills are on-demand procedural knowledge: a short description acts as always-available metadata that Claude uses to judge relevance, and the full instructions load once it decides the skill applies. Without a skill, standards drift — every session relies on someone remembering and retyping the rules correctly, and the procedure never becomes a shared, reusable artifact. Once loaded, a skill doesn't just get consulted abstractly — it directly shapes the generated code, as the GET /books example shows. Preloading a skill into a subagent trades visibility for consistency: you're more likely to get the convention check every time, but only if the skill is actually listed — leave it out, and the subagent silently misses it.