Advanced AI agent setup: skills, hooks, subagents, MCP

After the first setup the agent is already useful. But soon you see what is missing: it forgets some instructions, you have to explain recurring procedures again, long searches clutter the context, and it can't reach your tracker or database. Claude Code has a separate mechanism for each of these problems. Below is when you need which one, with working examples from the official documentation.

#The map: what handles what

An important caveat from the documentation: the agent treats CLAUDE.md and rules as context, not as enforced configuration. If an action must be blocked regardless of what the model decides, that is a job for a hook.

#Path-scoped rules

When CLAUDE.md grows, some instructions move to .claude/rules/. Each file covers one topic. A rule with a paths field loads only when the agent works with matching files:

---
paths:
  - "src/api/**/*.ts"
---
- Every handler validates input with zod
- Errors are returned in the format { error: { code, message } }

#Skills: procedures on demand

A skill is a folder with a SKILL.md file. The frontmatter describes when to use it; the body holds the instructions. The agent loads a skill on its own if the request matches the description, or you invoke it with /name. The main difference from CLAUDE.md: a skill's body loads only when it is needed.

Where to store them:

• ~/.claude/skills/<name>/SKILL.md: your personal skills, in all projects;
• .claude/skills/<name>/SKILL.md: shared for the project, in git.

An example from the documentation is a skill that injects a live diff into the instructions:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks.

The line with ! is a dynamic substitution: Claude Code runs the command and inserts its output before the model reads the skill. Old commands in .claude/commands/ still work, but skills are now the recommended format. Skills follow the open Agent Skills standard, which other tools support as well.

#Hooks: rules with no exceptions

A hook is a command (or an HTTP request, a prompt, a subagent) that fires at a specific point in the lifecycle. The main events:

• PreToolUse: before a tool call; can block it;
• PostToolUse: after a successful call;
• UserPromptSubmit: when a prompt is submitted;
• Stop: when the agent finishes its turn;
• SessionStart: a session starts or resumes;
• SubagentStart / SubagentStop, PreCompact, Notification and others.

Hooks are configured in settings.json. An example from the hooks guide: format every edited file and send a notification when the agent needs an answer:

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

If a hook exits with code 2, the action is blocked: for PreToolUse this cancels the tool call, and the agent sees the stderr text as the reason. This is how you build a guard for protected files, such as migrations or .env.

A Stop hook as a check. The Claude Code best practices describe a technique: a Stop hook runs your check (tests, a build) and doesn't let the agent end its turn until the check passes. It is a deterministic version of “check yourself” that works even without you watching.

You can see what is configured with the /hooks command.

#Subagents: context isolation

A subagent works in its own context window, with its own system prompt, tools and permissions, and returns only the result to the main conversation. Built-in ones: Explore (fast search, read-only), Plan (research for plan mode) and general-purpose.

Your own subagent is a file in .claude/agents/:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

According to the documentation, a subagent fits when a task produces a lot of noise you don't need in the main context, when you need separate permissions or tool restrictions, and when the work is self-contained and boils down to a result. The main conversation is better when you need frequent feedback, when stages share context, or when speed matters. The isolation: worktree field gives the subagent a separate copy of the repository.

A separate model for review is a strong technique: the agent that did the work shouldn't be the one to accept it. A read-only reviewer subagent looks at the result with fresh eyes.

#MCP: connecting external systems

MCP is an open protocol through which the agent gets tools, data and prompt templates from external systems. Adding a server:

# remote server over HTTP
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# local server: everything after -- runs as the server command
claude mcp add playwright -- npx -y @playwright/mcp@latest

Scopes: the default is local, just you and just this project; --scope user is you in all projects (~/.claude.json); --scope project is the whole team via .mcp.json at the repository root. A server from .mcp.json has to be approved on first launch. Inside a session, the /mcp command manages servers. More on a fully connected stack and its risks in the seventh post.

#Plugins

Once your set of skills, hooks, subagents and MCP servers has settled, you can package it into a plugin and distribute it to your team through a marketplace. A plugin's skills get a plugin:skill namespace, so several plugins can coexist.

#Sandbox

Permission modes answer the question “should it ask me.” A sandbox answers the question “what can commands physically reach.” It is a boundary enforced by the operating system: you specify which files and network domains are available to the agent's shell commands. Set it up with the /sandbox command. The sandbox works on macOS, Linux and WSL2 and covers only shell commands: the agent's file tools, MCP servers and hooks run outside it.

#Running without a human: scripts and CI

The -p flag runs a single task and exits:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

--output-format json returns a structured result, including a cost estimate in total_cost_usd. --bare skips auto-loading hooks, skills, MCP and CLAUDE.md, so the result is the same on any machine. For GitHub there is Claude Code GitHub Actions: the /install-github-app command installs the app and prepares a workflow, after which the agent responds to @claude mentions in issues and pull requests.

#Equivalents in Codex and Cursor

• Codex: custom agents are defined in .codex/agents/*.toml with the name, description and developer_instructions fields; there you can also set sandbox_mode = "read-only" for a research agent. MCP servers are added with codex mcp add. For CI, use codex exec.
• Cursor: hooks are defined in hooks.json (events such as beforeShellExecution and afterFileEdit), MCP in the project's .cursor/mcp.json or in ~/.cursor/mcp.json.

#Rollout order

1. First, tidy up CLAUDE.md and move narrow rules into .claude/rules/.
2. A formatting hook and a guard for protected files are the cheapest guarantees.
3. A skill for a procedure you explain more than once a week.
4. A read-only reviewer subagent.
5. One or two MCP servers for real tasks, not “just in case.”

Next: types of AI agents, and how agents in chat, the IDE, the terminal, the cloud and CI differ.