Claude Code skills, hooks and subagents: what each one is for

Claude Code is the agent harness we use most for building software. Out of the box it reads and edits files, runs commands and searches code. What makes it useful on a real team is how you extend it, and there are now five ways to do that.

They overlap just enough to be confusing. This guide is the version we wish we had when we started: what each one is, when to use it, and a small example of each.

Claude Code changes quickly. File locations and options below are correct at the time of writing; check the official Claude Code documentation before you rely on a detail.

The one-table summary

Mechanism	What it is	Runs when	Use it for
CLAUDE.md	A Markdown file of project instructions	Loaded at the start of every session	Facts that are always true: stack, commands, conventions
Skill	A folder with SKILL.md and optional scripts	When Claude decides the task needs it, or you call /skill-name	Procedures used sometimes: releasing, writing a migration, a review checklist
Hook	A shell command tied to an event	Every time the event fires	Rules that must always hold: format on save, block rm -rf, run tests before stopping
Subagent	A separate agent with its own prompt, tools and context	When delegated to	Side tasks whose details you don’t need: search, review, research
MCP server	A process that exposes tools to Claude	When Claude calls one of its tools	Connecting systems: databases, ticketing, design tools, your ERP

The rule of thumb: knowledge goes in CLAUDE.md or skills, enforcement goes in hooks, isolation goes in subagents, and outside systems come in through MCP.

CLAUDE.md: what is always true

CLAUDE.md sits at the root of the repository and is loaded into every session. Running /init drafts one for you from the codebase.

Keep it short and factual. Every line costs context in every session, so it should hold only what Claude would otherwise get wrong:

# Project notes
- Astro 5 static site, deployed to Firebase Hosting.
- `npm run dev` to develop, `npm run build` to check. No test suite.
- Copy rules: no invented metrics or client names.
- Romanian pages live under /ro and are written separately, not translated.

If a section of CLAUDE.md only matters for one kind of task, it probably belongs in a skill.

Skills: procedures loaded on demand

A skill is a folder containing a SKILL.md file, plus any scripts, templates or reference files it needs. Project skills live in .claude/skills/, personal ones in ~/.claude/skills/.

---
name: write-blog-post
description: Use when drafting or editing a post in src/content/posts. Covers frontmatter, structure and the answer-first format.
---

1. Start from the frontmatter schema in src/content/config.ts.
2. Write the `answer` field first: 2-4 sentences that fully answer the title.
3. Use H2s phrased the way people search.
4. Link to at least one related post and one service page.
5. Run `npm run build` and fix any schema errors.

The important part is the description. Claude sees every skill’s description up front and loads the body only when the task matches. A vague description means the skill never fires; a precise one (“Use when…”) means it fires at the right moment. Because only the description is loaded until needed, you can have many skills without crowding the context.

Skills are the best place for team know-how: how you release, how you write a migration, what your code review checks. Write it once, commit it, and everyone’s Claude follows the same process.

Hooks: rules the model cannot skip

Skills are advice. Claude might not load one, or might interpret it loosely. When something must happen every time, use a hook.

Hooks are shell commands configured in .claude/settings.json, tied to events such as PreToolUse (before a tool runs), PostToolUse (after it runs), UserPromptSubmit, SessionStart and Stop. The command receives details of the event as JSON on standard input.

Two hooks we use often. Format every file Claude edits:

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

And block a category of command before it runs. A PreToolUse hook that exits with code 2 blocks the tool call, and its error output is passed back to Claude as the reason:

#!/bin/bash
# .claude/hooks/no-force-push.sh — registered as a PreToolUse hook on Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -qE 'git push.*(--force|-f)'; then
  echo "Force-push is blocked in this repo. Push a new branch instead." >&2
  exit 2
fi

Hooks run with your user’s permissions, so treat them like any script you would add to a repository: review them, keep them small.

Subagents: keep the main thread clean

A subagent is a separate Claude instance with its own system prompt, its own tool list and, most importantly, its own context window. The main session hands it a task, the subagent does the reading and searching, and only its summary comes back.

Subagents are Markdown files in .claude/agents/ (or ~/.claude/agents/), and /agents helps you create them:

---
name: code-reviewer
description: Reviews a diff for bugs, missing tests and security issues. Use after a feature is implemented, before committing.
tools: Read, Grep, Glob, Bash
---

You are a strict reviewer. Read the diff with `git diff main...HEAD`.
Report only real problems, most severe first, each with file, line and a one-line fix.
Do not edit files.

Use subagents when the process is noisy but the result is small: finding where something is implemented across a large codebase, reviewing a change with fresh eyes, or researching a library. Don’t use them for small tasks; handing over context costs time, and the main agent only sees the summary, not the details.

MCP servers: connecting outside systems

The Model Context Protocol is how Claude Code talks to systems it doesn’t have built-in tools for. An MCP server exposes a set of tools, and Claude can call them like its own. You add one with claude mcp add, or commit a .mcp.json to the repository so the whole team shares it.

There are ready-made servers for databases, issue trackers, browsers and design tools. For internal systems, writing your own is a short job. We walk through one in How to build an MCP server for your ERP.

Putting it together

A setup we see work well on small teams:

• CLAUDE.md, under a page: stack, commands, the three conventions people keep breaking.
• Three to ten skills for the team’s recurring procedures, each with a precise “Use when…” description.
• Two or three hooks: formatting, a guard against destructive commands, maybe tests before the session ends.
• One or two subagents, usually a reviewer and a codebase explorer.
• MCP servers only for systems you actually use in the work.

Start smaller than that. Add a skill the second time you explain the same procedure, and a hook the first time something that should never happen happens anyway.

These are the same ideas we use when we build agents for operations teams: knowledge the agent loads when needed, rules enforced in code rather than in the prompt, narrow tools, and a clear trace of what it did. If you want the general version of that idea, read What is an agent harness?