Skills vs Subagents vs Hooks: When to Use Each in Claude Code

Claude Code gives you several ways to extend it, and the names blur together fast. Should “run the tests before committing” be a skill, a hook or a line in CLAUDE.md? Should your reviewer be a skill or a subagent? This page answers those questions directly, using the distinctions in Anthropic’s official Extend Claude Code documentation as of October 2026.

The one-line answer

• Skill = reusable know-how Claude loads when relevant or when you type /name.
• Subagent = a separate worker with its own context window that returns a summary.
• Hook = a guarantee: a command, HTTP call, MCP tool call, prompt or agent that Claude Code runs on a lifecycle event, every time.

And the supporting cast: CLAUDE.md is always-on project context, MCP connects external systems, and plugins package all of the above for sharing.

Side-by-side comparison

	Skill	Subagent	Hook
What it is	Instructions, knowledge or a workflow in SKILL.md	Isolated worker defined in .claude/agents/*.md	Handler bound to an event in settings.json
Who triggers it	You (/name) or Claude, matching the description	Claude delegates, or you ask for it	Claude Code, on an event such as PreToolUse or Stop
Deterministic?	No, Claude interprets it	No, it’s another model loop	Yes, fires without Claude deciding
Context cost	Description every request; full body when used	Separate window; only the summary returns	Zero unless the hook returns output
Best for	Checklists, playbooks, style guides, /deploy	Research, test runs, log digging, parallel work	Formatting, blocking risky actions, notifications, gates
Deep dive	Skills guide	Subagents guide	Hooks guide

When should I use a skill?

Use a skill when Claude should know how to do something, and that knowledge isn’t needed every session.

Skills come in two flavours, per the official docs:

• Reference skills: knowledge Claude uses while working, such as your API style guide or database conventions.
• Action skills: a workflow you trigger, such as /release or /fix-issue 123.

A minimal action skill at .claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests and run them

disable-model-invocation: true means only you can trigger it, and its description stays out of Claude’s context until you do. The docs recommend this for skills with side effects.

Signal you need a skill: you’ve pasted the same playbook into chat for the third time, or you keep typing the same prompt to start a task.

When should I use a subagent?

Use a subagent when the work would flood your main conversation with output you won’t need again, or when you want parallel, specialised workers.

A subagent starts with a fresh context: its own system prompt, any skills listed in its skills: field, CLAUDE.md and git status, plus whatever the main agent passes in. It might read dozens of files or run the full test suite; your conversation only receives the summary.

---
name: test-runner
description: Runs the test suite and reports only failures with likely causes. Use after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the project's tests. Report each failing test, the error, and the most
likely cause in two lines or fewer. Do not paste passing output.

Save it as .claude/agents/test-runner.md. Picking a smaller model for simple subagents is also one of Anthropic’s own cost tips; see Claude Code pricing.

Signal you need a subagent: a side task (tests, logs, a broad search) keeps pushing your real work out of the context window. The context management guide shows how to check with /context.

When should I use a hook?

Use a hook when something must happen every time, regardless of what the model decides.

The official docs are explicit: “never edit .env” written in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

That formats every file Claude edits, with no reminder needed. Hooks are also the right place for desktop notifications, audit logging, and “don’t stop until tests pass” gates.

Signal you need a hook: you’ve told Claude the same rule twice and it still slips sometimes, or the action is mechanical and doesn’t need judgment.

Where do CLAUDE.md, MCP and plugins fit?

Feature	Role	Use it for
CLAUDE.md	Always-on context, loaded every session	Build commands, conventions, “always/never” rules. Keep it under about 200 lines.
.claude/rules/	Rules that load always or only for matching file paths	Language- or directory-specific guidelines
MCP server	Tools and data from external systems	Databases, issue trackers, browsers, Slack
Plugin	Packaging layer	Sharing skills, subagents, hooks and MCP servers across repos via a marketplace

Quick distinctions the official docs draw:

• CLAUDE.md vs skill: CLAUDE.md loads every session; a skill loads on demand and can be triggered with /name. Put “always do X” rules in CLAUDE.md and reference material in skills. See our CLAUDE.md guide.
• MCP vs skill: MCP provides the connection and tools; a skill teaches Claude how to use them well, such as your schema and query patterns. Browse options in best MCP servers.
• Plugins: package the rest once a second repository needs the same setup. Plugin skills are namespaced, like /my-plugin:review. See the plugins guide.

Decision checklist

Ask these in order:

1. Must it happen every time, with no judgment? → Hook.
2. Does Claude need it in every session? → CLAUDE.md (or a path-scoped rule).
3. Is it a procedure or reference Claude needs sometimes? → Skill.
4. Will the work produce lots of output you won’t reference again, or can it run in parallel? → Subagent.
5. Does Claude need data or actions from another system? → MCP server.
6. Do other repos or teammates need the same setup? → Plugin.

Anthropic’s docs also suggest adding features as triggers appear rather than all up front: a convention Claude gets wrong twice goes into CLAUDE.md, a repeated prompt becomes a skill, a noisy side task becomes a subagent, a must-always action becomes a hook.

How they combine

The features are designed to stack. Patterns from the official docs:

Pattern	Example
Skill + subagent	An /audit skill kicks off security, performance and style subagents in isolated contexts
Subagent + skill	A reviewer subagent preloads your review checklist via skills:
Skill in a fork	A skill with context: fork runs in its own subagent context
Skill + MCP	MCP connects the database; a skill documents the schema and query rules
Hook + MCP	A post-edit hook calls an MCP tool to notify Slack when critical files change
CLAUDE.md + skills	CLAUDE.md says “follow our API conventions”; a skill holds the full style guide

How they behave when defined in several places

• CLAUDE.md files are additive: user, project and nested files all contribute.
• Skills and subagents override by name: one definition wins by priority (for subagents: managed, then CLI flag, then project, then user, then plugin).
• MCP servers override by name: local, then project, then user.
• Hooks merge: every registered hook fires for its event, whatever its source.

Building a kit from these pieces

A “Claude kit” is simply a deliberate mix of these features: lean CLAUDE.md, a handful of skills, a few subagents, guard-rail hooks and the MCP servers you actually use. Our guide to what a Claude kit is walks through assembling one, and best Claude Code skills lists proven skills to start from. For more quick answers, see the Claude Code FAQ.