Agents vs Skills vs the Rest
Claude Code gives you six ways to customize it, and they overlap just enough to be confusing. This is the decision guide: which piece solves which problem, and how they fit together. (For step-by-step creation, see Agents & Skills.)
TL;DR: The Six Pieces
CLAUDE.md
Always-on project facts and rules
Skill
Know-how loaded when relevant
Subagent
A specialist with its own context
Hook
Code that always runs at a set moment
MCP server
A connection to an outside tool or data
Plugin
A box that ships any of the above
Restaurant version: CLAUDE.md is the house rules on the wall, a skill is a recipe card, a subagent is a line cook at their own station, a hook is the health inspector who checks every plate, an MCP server is the supplier's delivery door, and a plugin is a franchise kit.
1Side-by-Side
| Skill | Subagent | Hook | MCP | |
|---|---|---|---|---|
| Triggered by | Claude (matches description) or you (/name) | Claude delegates, or you ask / @-mention | An event (after an edit, before a command...) | Claude calls its tools when useful |
| Context | Loads into the main conversation (or its own with context: fork) | Separate, fresh window; returns a summary | Runs outside the model; zero context unless it reports back | Tool definitions and results use context |
| Tools & model | Can pre-approve tools (allowed-tools) and set model / effort | Own tool list, model, permission mode | Whatever your script does | Adds new tools |
| Guaranteed? | No: guidance Claude follows | No: guidance Claude follows | Yes: deterministic | N/A: it's an ability, not a rule |
| Best for | Standards, checklists, repeatable workflows | Big or noisy tasks, restricted roles | Formatting, blocking, notifications | GitHub, databases, deploys, docs |
Plugins aren't in the table because they aren't an alternative: a plugin Plugin (Claude Code) An installable bundle that adds skills, subagents, hooks, and MCP servers to Claude Code in one step. A plugin has a `.claude-plugin/plugin.json` manifest; its skills are invoked as `/plugin-name:skill-name`. Install with `/plugin install commit-commands@claude-plugins-official` or browse with `/plugin`. "Like an expansion pack for a game. One install, and you get new characters, levels, and items together."
2The Decision Framework
Go down the list; the first "yes" is usually your answer.
"Does it need to happen EVERY time, no exceptions?"
Yes → Hook. Instructions can be forgotten. Hooks can't.
"Does Claude need access to something outside the project (GitHub, a database, deploy logs)?"
Yes → MCP server. Skills teach; MCP connects.
"Is it a short fact or rule that applies to almost every task?"
Yes → CLAUDE.md. Always loaded, so keep it brief.
"Is it a procedure, checklist, or standard used only for some tasks?"
Yes → Skill. Loads only when relevant.
"Will the work read lots of files or produce noise you don't want in your chat?"
Yes → Subagent. Its context is thrown away; you get the summary.
"Does it need a different model, tighter tool limits, or its own permission mode for a whole task?"
Yes → Subagent. Skills can do this per-skill too; pick an agent when it's a role, not a recipe.
"Do you want to share the setup across repos or with other people?"
Yes → Plugin. One install gives them everything.
3Skill or Subagent? The Real Test
Choose a skill when...
- • You want Claude to know how to do something your way
- • The output should stay in your conversation
- • It's a standard: commit format, review checklist, SQL conventions
- • You want a reusable /command
Examples: commit style, PR checklist, "how we write API routes", pre-deploy check.
Choose a subagent when...
- • The task would flood your context (searching 60 files, reading logs)
- • It's a role with fixed limits: read-only reviewer, DB-only analyst
- • You want it to run in parallel or in its own worktree
Git Worktree
A second (or third) working folder attached to the same Git repository, each checked out on its own branch. It lets several AI agents edit code in parallel without trampling each other's files. Claude Code can create one for you with `claude --worktree feature-auth`, and subagents can use `isolation: worktree`.
"Like giving each contractor their own copy of the blueprints and their own room to work in, then merging the finished rooms."
- • A fresh perspective helps (review work it didn't write)
Examples: code reviewer, security auditor, test-writer, codebase explorer.
The middle ground: a skill with context: fork runs inside its own subagent. Use it for a recipe that's noisy to execute ("research X thoroughly") when you don't need a whole persona.
The combo: a subagent can preload skills with its skills: field. Agent = who, skill = how.
4Hooks: When "Please" Isn't Enough
"Always run Prettier" in CLAUDE.md works most of the time. A hook Hooks (Claude Code) Handlers that run automatically at specific moments in a Claude Code session, such as before a tool runs (PreToolUse), after it finishes (PostToolUse), when you submit a prompt, or when Claude stops. A hook can be a shell command, an HTTP call, an MCP tool, or a prompt, and can block risky actions. Configure them under the `hooks` key in settings.json or ship them in a plugin. "Like motion-sensor lights. When something happens (motion), an action triggers automatically (lights on)."
.claude/settings.json (block any Bash command that mentions .env)
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' | grep -q '\\.env' && exit 2 || exit 0"
}
]
}
]
}
}Exit code 2 blocks the tool call. Recipes and gotchas: Hooks & Automation.
5MCP vs Skill: Access vs Know-How
An MCP server MCP (Model Context Protocol) An open standard for connecting AI apps to external tools and data (databases, GitHub, docs, browsers). Servers run locally over stdio or remotely over Streamable HTTP, and remote servers use OAuth 2.1 for sign-in. In Claude Code: `claude mcp add --transport http <name> <url>`. "Like USB ports for AI. A universal way to plug in new capabilities."
Neon MCP + db-conventions skill
MCP runs the SQL; the skill keeps it on a dev branch and in your naming style.
GitHub MCP + pr-review skill
MCP reads the PR and posts comments; the skill decides what's worth flagging.
Every MCP server is also a door for untrusted text. Connect only what you trust; see the MCP Playbook.
6A Real Setup for a Next.js SaaS
Here's how one solo builder might wire it all up. Notice each piece does one job.
CLAUDE.md
Stack, commands, "auth lives in proxy.ts", "never edit applied migrations".
Skills
commit-style, api-route-conventions, pre-deploy (disable-model-invocation: true).
Subagent
code-reviewer: read-only, runs after each feature, preloads the api-route-conventions skill.
Hooks
Prettier after every edit; block commands touching .env.
MCP
GitHub (issues/PRs), Vercel (deploy logs), Neon (dev branch only).
Plugin
Once it works, bundle the skills, agent, and hooks so the next project starts with them.
Start small. CLAUDE.md plus one skill covers most of the value. Add a subagent when your context keeps filling up, a hook when a rule keeps getting skipped, and a plugin when you're copying the same folder into a third repo.
7Signs You Picked Wrong
Your CLAUDE.md is 400 lines
Move procedures into skills; keep only always-true facts.
Your "agent" just holds a checklist
It's a skill. Agents are for isolation and roles.
You keep reminding Claude to format/lint
That's a hook.
You paste API responses into chat
Connect the service via MCP instead.
Ready to build your own?
Create your first agent and skill, then learn how to ship them as a plugin.