Skip to main content
Comparison10 min read·Updated August 1, 2026
🧩

Agent Skills vs Subagents vs Hooks: Which to Use (2026)

B

A. Frans

Published August 1, 2026

Claude CodeAgent SkillsSubagentsHooksDeveloper Tools

Most people pick between skills, subagents and hooks by asking what they want the agent to do. That's the wrong question and it's why so many Claude Code setups end up with a skill that should have been a hook.

The right question is who decides, and when. A skill is loaded when the model judges it relevant. A subagent runs when the model chooses to delegate. A hook fires whether the model likes it or not, at a fixed point in the loop, every single time.

Once you sort by that, most design arguments resolve themselves. Everything below was checked against the Claude Code documentation on August 1, 2026, because this area has shifted more than any other part of the product in the last six months.

The one-line version

SkillSubagentHook
Who triggers itModel decides, or you type /nameModel delegatesThe system, deterministically
Where it lives.claude/skills/name/SKILL.md.claude/agents/name.mdsettings.json
FormatMarkdown plus YAML frontmatterMarkdown plus YAML frontmatterJSON config plus a script
ContextLoads into the current conversationIts own context windowNone, it's outside the model
Can it block anythingNoNoYes
Good forKnowledge and procedureIsolation and parallelismEnforcement and automation

Skills: reusable instructions the model chooses to read

A skill is a SKILL.md file with YAML frontmatter and markdown instructions. The frontmatter tells Claude when the skill is relevant; the body tells it what to do once loaded. Create one when you notice you're pasting the same instructions into a conversation for the third time, and if you've never written one, start here.

The first thing to know in 2026 is that custom slash commands have been folded into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both give you /deploy and behave the same way. Existing commands directories keep working. Skills just add things commands never had: a directory for supporting files, and frontmatter that controls behaviour.

Only description is required. The fields worth knowing:

  • description carries the whole burden of discovery. Claude reads it to decide whether to load the skill at all. It counts toward a 1,536-character cap along with the name, so write it as trigger conditions rather than a summary. "Use when the user asks what changed, wants a commit message, or asks to review their diff" beats "helps with git."
  • allowed-tools pre-approves tools for the turn that invokes the skill, and the grant clears on your next message. This is how a skill runs a bundled script without a permission prompt.
  • disable-model-invocation: true makes a skill manual only. Use it for anything with side effects you don't want triggered by a description match.
  • context: fork runs the skill in its own subagent context, which is the seam between the first two columns of that table.
  • argument-hint and arguments give you autocomplete hints and named positional substitution, the parts that used to belong to slash commands.

Location determines reach. Personal skills at ~/.claude/skills/name/SKILL.md apply everywhere. Project skills at .claude/skills/name/SKILL.md apply to one repo and belong in version control. Plugin skills are namespaced as plugin-name:skill-name so they can never shadow yours. When names collide, enterprise wins over personal wins over project, and any of those overrides a bundled skill of the same name.

Two behaviours that save real debugging time. Claude Code watches skill directories and picks up edits live, so you can iterate on a SKILL.md without restarting, though that only covers the markdown, not hooks or MCP config inside a skill-as-plugin. And skills are discovered from nested directories: when Claude touches a file in a monorepo package, that package's .claude/skills/ becomes available. A package can ship its own skills without polluting the root.

This is also why third-party skill repos vary so much in usefulness. A well-written one encodes hard-won specifics, the way the Android and Kotlin skills document Ktor plugin ordering traps. A weak one restates the framework docs the model already knows.

The catch nobody mentions: skills consume context. Every loaded skill is instructions competing with your actual code for the model's attention. Four overlapping skills produce an agent that hedges. Claude Code will resolve two skills with the same name by precedence, but it has no mechanism for two differently-named skills that flatly disagree with each other.

Subagents: a second context window with a narrower job

A subagent is a separate Claude instance with its own context window, its own system prompt, its own tool access and its own permissions. It works independently and returns a summary to the main conversation.

The reason to reach for one is almost always context, not capability. Searching a large codebase generates enormous output that you never need to read again. Run it in a subagent and the main conversation gets three paragraphs instead of forty file dumps. Claude Code's built-in Explore and Plan subagents exist for exactly this: exploration output stays out of the conversation you came to have.

Subagent frontmatter is considerably richer than skill frontmatter: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation and color. Two of those matter more than the rest. Setting model lets you push cheap work down a tier, and overriding the built-in Explore with your own definition at model: haiku is the standard cost move. Setting tools narrowly is how you make a subagent that can read a codebase but cannot write to it.

Precedence runs managed settings, then the --agents CLI flag, then .claude/agents/, then ~/.claude/agents/, then plugin agents last. Project subagents are found by walking up from the working directory, and since v2.1.178 the definition closest to your working directory wins when names repeat.

Two things that will trip you up. The /agents command stopped opening an interactive wizard in v2.1.198; it now just tells you to ask Claude or edit the files directly. And agents loaded from a plugin silently ignore the hooks, mcpServers and permissionMode fields. If you need those, the file has to live in .claude/agents/ or ~/.claude/agents/.

Subagents are not free. Each one is a fresh context that knows nothing about your conversation beyond the prompt you hand it, so delegating a task that needs the last twenty minutes of discussion produces confident, wrong work. Delegate tasks with clean inputs and clean outputs.

Hooks: the only one that can say no

Hooks are shell commands defined in your JSON settings files that fire at fixed points in the agent loop. The model does not choose to run them and cannot skip them. That single property is the entire reason hooks exist.

The configuration nests three levels: pick an event, add a matcher to narrow when it fires, then define handlers. A PreToolUse hook matched to Bash sees every shell command before it runs, and can deny it.

The events fall into three cadences. Once per session for SessionStart and SessionEnd. Once per turn for UserPromptSubmit, Stop and StopFailure. Once per tool call for PreToolUse and PostToolUse. Beyond those there's PermissionRequest, PermissionDenied, UserPromptExpansion, MessageDisplay, InstructionsLoaded, Setup and more.

Exit code 2 is the signal for "stop, don't do this," and its effect varies by event because some events represent actions that can still be blocked and others report things that already happened. PreToolUse also accepts structured JSON on stdout with a permissionDecision of allow, deny, ask or defer, plus a reason string that gets shown to the model. That's the mechanism behind every "block rm -rf" hook you've seen: read the command from stdin as JSON, grep it, emit a deny decision or exit 0 and let normal permission flow continue.

Use a hook when the requirement contains the word "always" or "never." Always run the formatter after an edit. Never let the agent commit to main. Never touch the production env file. Encoding those as a skill means encoding them as a suggestion, and a suggestion the model can rationalise around at 2am in a long session is not a control.

Hooks also run your code with your permissions. A bad matcher can fire a script on every tool call in every session. Test the handler standalone before wiring it up.

Picking, in practice

Use a skill when the answer is knowledge. How this repo does migrations. The house style for API error responses. The five commands that reproduce a flaky test. Anything you'd otherwise explain to a new hire.

Use a subagent when the answer is isolation. The work generates output you don't want in the main context, or needs different tool permissions, or a cheaper model, or should run in parallel with three siblings.

Use a hook when the answer is enforcement. The rule must hold even when the model disagrees, forgets, or is nine thousand tokens deep in something else.

The common mistake is reaching for a skill because it's the easiest to write. A markdown file feels like less work than a JSON config plus a script, so people encode policy as prose and then discover it holds about eighty percent of the time. Eighty percent is fine for a style preference and useless for a safety rail.

The reverse mistake is rarer but worse: hooks that encode judgement. A hook cannot read the situation. If your rule needs an exception under conditions you can't express as a regex, it belongs in a skill, and you should accept that it's advice.

They compose, and that's the point

These are not three ways to do one thing. A real setup uses all three at once.

Say you're automating code review. A hook on PostToolUse runs the linter after every edit, deterministically. A code-review subagent runs with read-only tools in its own context so a large diff never floods your conversation. A skill carries your team's actual review standards, the things a linter can't check, and it's preloaded into that subagent through the subagent's skills field.

Skills can also fork into their own subagent context with context: fork, and subagents can carry their own hooks in frontmatter, though not when they're loaded from a plugin. The boundaries are more porous than the three names suggest.

If you're deciding where MCP servers fit alongside all of this, we covered skills, MCP servers and plugins separately, and there's a narrower piece on how slash commands folded into skills. The short answer: MCP adds tools, skills add judgement, and they're solving different halves of the same problem.

FAQ

Are slash commands deprecated? No, and your .claude/commands/ files keep working. They've been merged into skills, so a command file and a SKILL.md with the same name produce the same /name behaviour. New work should go in .claude/skills/ because that's where the frontmatter options and the supporting-file directory live.

Why isn't my skill loading? Almost always the description. Claude reads it to decide relevance, so a vague one never matches. Rewrite it as explicit trigger conditions naming the words a user would type. If it still doesn't fire, invoke it directly with /skill-name to confirm the file parses, then fix the description.

Can a hook stop the agent from running a command? Yes. A PreToolUse hook can return a permissionDecision of deny with a reason, or exit with code 2, and the tool call never happens. This is the only one of the three that can block anything.

Does a subagent see my conversation? No. It gets a fresh context window and knows only what its system prompt and the delegating prompt contain. That isolation is the feature, and it's also why delegating context-dependent work produces confidently wrong answers.

How many skills is too many? There's no hard cap, but every loaded skill competes for attention with your code. Symptoms of too many: the agent hedges, cites rules that contradict each other, or applies the wrong repo's conventions. Prune to the skills that fire regularly and move the rest to disable-model-invocation so they're manual only.

Which should I build first? A skill, almost always. It's the cheapest to write and the easiest to throw away. Reach for a hook the first time you catch the agent breaking a rule it already knew, and for a subagent the first time a task floods your context with output you'll never read. For a broader look at what the wider community is shipping, our full list for developers is a reasonable place to start.

Share this article

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.