Most people run Claude Code out of the box and never touch its extensibility surface. That's fine for casual use, but the moment you're running the agent daily against a real codebase — or building your own tooling on top of it, as I do with openseek — the same three questions keep coming up. How do I give the agent a fresh, focused context for a big task? How do I make it always run my formatter, no exceptions? And how do I stop retyping the same 200-word prompt every morning?
Claude Code answers each with a different primitive: subagents, hooks, and slash commands. They look superficially similar — all three are usually just Markdown or JSON files under .claude/ — but they solve genuinely different problems, and reaching for the wrong one is where people waste an afternoon. This guide walks through each: what it is, when to use it, a concrete example, and the gotcha that bit me.
Subagents: Isolated Context for Delegated Work
A subagent is a separate Claude instance that the main agent spawns to handle a focused task, then returns a summary. The key word is separate: the subagent runs in its own context window, so a noisy 40-file research crawl or a sprawling refactor doesn't pollute your main conversation. You define one as a Markdown file in .claude/agents/ (project-scoped) or ~/.claude/agents/ (personal), with YAML frontmatter on top and the system prompt as the Markdown body.
When to reach for it: the task is self-contained, generates a lot of intermediate noise, and you only care about the conclusion. Code review, dependency audits, "find every place we call this deprecated API", exploratory research — anything where you want the answer back in your main thread without the 30 tool calls it took to get there. Subagents can also run in parallel, which is why they're the backbone of decomposition-heavy workflows.
A minimal reviewer agent looks roughly like this:
---
name: security-reviewer
description: Reviews changed code for injection, auth, and secret-handling bugs. Use after writing security-sensitive code.
tools: Read, Grep, Glob
model: sonnet
---
You are a security reviewer. Inspect the diff for injection risks,
missing authorization checks, and hardcoded secrets. Report findings
as a prioritized list with file:line references. Do not modify code.
The description field is load-bearing — it's how the main agent decides whether to delegate to this subagent automatically. Vague descriptions mean the agent never picks it. Restricting tools (here, read-only) is a good habit: a reviewer that can't write can't "helpfully" edit your files mid-review.
The gotcha: subagents are loaded at session start. If you edit an agent file on disk, the running session generally won't pick up the change until you restart — but agents you create or edit through the interactive /agents command take effect immediately. I lost time editing a file and wondering why nothing changed. Use /agents while iterating, then trust the file on disk afterward.
Hooks: Deterministic Guarantees Around Tool Calls
Subagents are intelligence you delegate to. Hooks are the opposite — they're deterministic scripts that fire at fixed points in the agent's lifecycle, with no model judgment involved. They run before a tool executes (PreToolUse), after it completes (PostToolUse), when a session starts, when the agent stops, and at several other lifecycle events. You configure them in settings.json — ~/.claude/settings.json for global, .claude/settings.json for a project.
When to reach for it: whenever "the agent should remember to do X" isn't good enough and you need "X always happens." A PostToolUse hook that runs Prettier on every edited file. A PreToolUse hook that blocks rm -rf or edits to protected paths. Because a hook is code, not a suggestion in a prompt, it can't be forgotten or reasoned away.
Here's a PreToolUse hook that inspects every Bash command before it runs:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": ".claude/hooks/check-command.sh" }
]
}
]
}
}
The hook script receives context on stdin as JSON — including tool_name and tool_input — so check-command.sh can read the actual command and decide what to do. Per the current docs, a PreToolUse hook can block the call: exiting with code 2 stops the tool, and a hook can also return a hookSpecificOutput object with a permissionDecision of allow, deny, or ask. (Exact field names and exit-code semantics have shifted across releases, so check the hooks reference for the version you're on before you rely on the precise contract.)
The gotcha: hooks run with your shell's permissions and no confirmation prompt — that's the whole point, and also the danger. A buggy PostToolUse formatter that rewrites files can quietly corrupt work across a whole session, and a slow hook adds latency to every matching tool call. Keep them fast, keep them narrow with a matcher, and test the script standalone before wiring it in.
Slash Commands: Reusable Prompt Shortcuts
A slash command is a saved prompt you invoke by name. Drop a Markdown file at .claude/commands/deploy.md and you get /deploy, expanding to the same instructions every time. The file body is the prompt; optional YAML frontmatter adds a description, an argument-hint, allowed-tools, and a few other fields — all optional, though a description is worth having.
When to reach for it: a repeatable, multi-step instruction you'd otherwise retype — "open a PR with this checklist", "run the full release gate", "summarize what changed since main". Arguments make them dynamic: $ARGUMENTS captures everything after the command name as one string, and $1, $2 split positional inputs.
---
description: Open a PR with our standard checklist
argument-hint: <pr-title>
---
Create a pull request titled "$ARGUMENTS". Include a summary of the
diff, a testing checklist, and link any issue referenced in the branch
name. Run the lint and typecheck gate before opening it.
Invoke it with /open-pr Fix flaky auth test and $ARGUMENTS fills in the title.
The gotcha: as of 2026, single-file slash commands and skills have converged — a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and share the same frontmatter. The docs now label the single-file form "legacy" and steer you toward skills for anything that needs helper scripts, examples, or versioning. Existing command files keep working, so there's no fire drill — but if your command is growing bundled files, promote it to a proper skill. (See what a Claude Code skill is and how to write one.)
How They Combine
The three aren't competitors — the strongest setups layer them. A slash command is your entry point; it kicks off a workflow with one keystroke. Inside that workflow, the main agent delegates the heavy, noisy parts to subagents so the primary context stays clean. And hooks run underneath all of it as a safety net, enforcing formatting, guarding protected files, and blocking dangerous commands regardless of what the agent or any subagent decides to do.
Concretely: a /ship command orchestrates a release. It spawns a review subagent to audit the diff in isolation, and a PreToolUse hook silently refuses any push to main. The command carries the intent, the subagent carries the isolated reasoning, and the hook carries the guarantee. That's the whole mental model — commands for intent, subagents for isolation, hooks for enforcement — and it maps almost one-to-one onto the best-practices most heavy users converge on.
If you only remember one heuristic: ask whether you need judgment (subagent), a guarantee (hook), or a shortcut (slash command). Pick the primitive that matches, and don't force one to do another's job.
We track the best community skills, agents, and Claude Code tooling every week — the weekly digest is where we surface what's actually worth adopting, and where the sharpest skills tend to show up first.