Claude Code: Hooks, Subagents, and Skills — Complete Guide

TL;DR — Claude Code is more than a chat interface. Hooks let you intercept and control every lifecycle event with deterministic scripts. Subagents spin up isolated workers for parallel tasks without polluting your main context. Skills package reusable prompts and workflows into invocable commands. Together, they turn Claude Code from a conversational tool into a programmable AI engineering platform.

What This Guide Covers

Claude Code ships with three extensibility layers that most users never touch: hooks for lifecycle automation, subagents for parallel task delegation, and skills for reusable prompt templates. This guide explains what each does, when to use which, and how to combine them.

If you are new to Claude Code, start with our configuration guide for installation and provider setup. For model selection, see best AI model for coding 2026.

Hooks: Deterministic Control Over Claude Code

Hooks are event-driven scripts that run when something happens in Claude Code. Unlike prompts, which rely on the model’s interpretation, hooks execute deterministic code. They cannot hallucinate.

Why Hooks Matter

Without hooks, every safeguard depends on the model understanding your instructions. With hooks, you enforce rules at the system level. Block rm -rf before it runs. Inject project context automatically. Log every tool call for audit.

Hook Types and What They Do

Claude Code supports five handler types:

The 25 Lifecycle Events

Hooks fire at 25 distinct lifecycle points. Here are the ones you will actually use:

Blocking-capable events (can stop execution):

• UserPromptSubmit — Fires when you submit a prompt. Can block or modify the prompt before Claude sees it.
• PreToolUse — Fires before any tool executes. The primary security checkpoint.
• PermissionRequest — Fires when Claude asks for permission. Can auto-approve or deny.
• Stop / SubagentStop — Fires when Claude or a subagent finishes. Can force continuation.
• PreCompact — Fires before context compaction. Can back up transcripts.

Informational events (cannot block, but can log or notify):

• SessionStart / SessionEnd — Session lifecycle. Load context on start, clean up on end.
• PostToolUse / PostToolUseFailure — Tool completion or failure. Log results, run linters.
• SubagentStart — Subagent spawned. Track agent orchestration.
• Notification — Claude sends a notification. Route to Slack, trigger TTS.

Exit Code Behavior

Hooks communicate through exit codes:

Example: Block Dangerous Commands with PreToolUse

Create .claude/hooks/block-rm.sh:

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
  exit 2
else
  exit 0
fi

Configure in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Now any rm -rf command is blocked before execution, with the denial reason shown to Claude.

Example: Auto-Inject Project Context on SessionStart

#!/bin/bash
# .claude/hooks/session-start.sh
if [ -f "$PWD/CLAUDE.md" ]; then
  echo "Loaded project context from CLAUDE.md"
fi
if [ -f "$PWD/.env.example" ]; then
  echo "Environment template available at .env.example"
fi
exit 0

This runs every time Claude Code starts in a directory, surfacing relevant context automatically.

Hook Scopes

Hooks can be defined at multiple levels with priority:

Project-level hooks are ideal for team-shared policies. Personal hooks in ~/.claude/ apply everywhere.

Subagents: Parallel Workers with Isolated Context

Subagents are specialized AI instances that handle tasks in their own context window. When a subagent runs, its verbose output — file searches, log dumps, multi-step reasoning — stays isolated. Only the summary returns to your main conversation.

Built-in Subagents

Claude Code includes three built-in subagents:

Claude delegates automatically based on task type. You can also invoke explicitly with @agent-name or claude --agent <name>.

When to Use Subagents

Use subagents when:

• A task produces verbose output you do not need in main context
• You want to enforce tool restrictions (e.g., read-only review)
• You need parallel research on independent topics
• The work is self-contained and can return a summary

Use the main conversation when:

• The task needs frequent back-and-forth refinement
• Multiple phases share significant context
• Latency matters (subagents start fresh)

Creating a Custom Subagent

Subagents are Markdown files with YAML frontmatter. Save to .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Invoke with: Use the code-reviewer agent to review my auth changes

Or guarantee delegation with @-mention: @"code-reviewer (agent)" look at the auth changes

Subagent Configuration Options

Preloading Skills into Subagents

Subagents do not inherit parent skills. Preload explicitly:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

The full skill content is injected at startup, not just made available.

Forked Subagents (Experimental)

Forks inherit the full conversation history instead of starting fresh. Use them when a named subagent would need too much background context.

Enable: CLAUDE_CODE_FORK_SUBAGENT=1

Spawn: /fork draft unit tests for the parser changes

Forks run in the background while you continue working. Results arrive as messages when complete.

Parallel Research Pattern

Research the authentication, database, and API modules in parallel using separate subagents

Each subagent explores independently. Claude synthesizes the findings. This works best when research paths do not depend on each other.

Skills: Reusable Prompts and Workflows

Skills extend what Claude can do by packaging instructions into invocable commands. Create a skill when you keep pasting the same playbook into chat.

Skills vs. CLAUDE.md

Unlike CLAUDE.md content, a skill’s body loads only when invoked, so long reference material costs almost nothing until needed.

Creating Your First Skill

mkdir -p ~/.claude/skills/explain-code

Create ~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

Invoke automatically: How does this code work?

Invoke directly: /explain-code src/auth/login.ts

Skill Frontmatter Reference

Dynamic Context Injection

The !`command` syntax runs shell commands before the skill content is sent to Claude:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

Commands execute immediately; Claude receives only the output. For multi-line commands, use ```! fenced blocks.

Skill Directory Structure

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output
└── scripts/
    └── validate.sh    # Script Claude can execute

Reference supporting files from SKILL.md so Claude knows what they contain and when to load them.

Where Skills Live

Higher-priority locations win: enterprise > personal > project. Plugin skills use plugin-name:skill-name namespace.

Bundled Skills

Claude Code includes built-in skills available in every session:

• /simplify — Simplify complex code or explanations
• /debug — Systematic debugging workflow
• /batch — Process multiple items efficiently
• /loop — Iterate on a task until complete
• /claude-api — Reference for Claude API patterns

These are prompt-based, not hardcoded. They give Claude a detailed playbook and let it orchestrate the work.

Combining Hooks, Subagents, and Skills

The three features compose together. Here is a production-ready setup:

Example: Secure Code Review Pipeline

Skill (~/.claude/skills/secure-review/SKILL.md):

---
name: secure-review
description: Security-focused code review. Use when reviewing authentication, authorization, or data handling code.
context: fork
agent: Explore
disable-model-invocation: true
---

Perform a security-focused code review:

1. Check for hardcoded secrets, API keys, or credentials
2. Verify input validation and sanitization
3. Review authentication and authorization logic
4. Check for SQL injection, XSS, and injection vulnerabilities
5. Verify error handling does not leak sensitive information
6. Check file upload and path traversal protections

Report findings with severity levels and specific file references.

Hook (.claude/settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/run-security-linter.sh"
          }
        ]
      }
    ]
  }
}

Subagent (.claude/agents/security-reviewer.md):

---
name: security-reviewer
description: Security review specialist for auth and data handling code
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
---

You are a security-focused code reviewer. Focus on:
- Authentication and authorization flaws
- Input validation gaps
- Secret leakage
- Injection vulnerabilities

Never modify code. Only report findings.

Usage: After editing auth code, run /secure-review or ask Claude to Have the security-reviewer agent check these changes. The PostToolUse hook runs the security linter on every file edit automatically.

Practical Patterns

Pattern 1: Context Preservation

Use subagents for operations that produce large outputs:

Use a subagent to run the test suite and report only the failing tests with their error messages

The full test output stays in the subagent’s context. You get only the actionable summary.

Pattern 2: Tool Restriction

Limit what subagents can do for safety:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

The hook blocks any SQL write operation before it executes.

Pattern 3: Model Routing

Route different tasks to different models for cost optimization:

---
name: quick-classifier
description: Classify incoming requests by type and complexity
model: haiku
---

Classify this request as: simple, complex, or research-heavy.

Haiku is fast and cheap for classification. Route complex tasks to Sonnet or Opus.

Pattern 4: Persistent Memory

Enable cross-session learning for subagents:

---
name: codebase-architect
description: Maintains architectural knowledge of the codebase
memory: project
---

Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions.

The subagent accumulates knowledge in .claude/agent-memory/codebase-architect/ across conversations.

Accessing Claude Code Through OfoxAI

Claude Code works with any Anthropic-compatible API endpoint. OfoxAI provides full protocol support including extended thinking and cache_control.

Configuration:

• Request URL: https://api.ofox.ai/anthropic
• API Key: Your OfoxAI key from app.ofox.ai

For setup instructions, see our Claude Code configuration guide. For model comparisons, see Claude Opus 4.7 API review and best AI model for agents 2026.

Summary

Start with skills — they are the easiest to create and provide immediate value. Add hooks when you need deterministic enforcement. Use subagents when parallel work or context isolation matters.

The teams getting the most from Claude Code treat it as a programmable platform, not just a chat interface. Hooks, subagents, and skills are the tools that make that transition possible.

---

Related: Claude Code configuration guide — step-by-step setup with custom API providers. Claude Code source leak analysis — what 512K lines of TypeScript reveal about Claude Code’s architecture. Best AI model for agents 2026 — which models work best for agent workloads.