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

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

Claude Code offers three extensibility layers: hooks for lifecycle automation, subagents for parallel task delegation, and skills for reusable prompt templates. This guide explains each mechanism, when to apply which, and how to combine them effectively.

What This Guide Covers

Hooks, subagents, and skills transform Claude Code from a conversational tool into a programmable AI engineering platform. For foundational setup, reference the configuration guide and model selection documentation.

Hooks: Deterministic Control Over Claude Code

Hooks are event-driven scripts executing when something happens in Claude Code. Unlike prompts relying on model interpretation, hooks run deterministic code incapable of hallucination.

Why Hooks Matter

Without hooks, every safeguard depends on the model understanding instructions. With hooks, rules enforce at the system level. Block dangerous commands before execution. Inject project context automatically. Log every tool call for audit purposes.

Hook Types and What They Do

Type	What It Runs	Best For
command	Shell script receiving JSON on stdin	Blocking dangerous commands, local validation
http	HTTP POST endpoint	Centralized policy enforcement, remote logging
mcp_tool	Connected MCP server tool	Integration with external security scanners
prompt	Single-turn LLM evaluation	Semantic validation ("does this look like a secret?")
agent	Subagent using tools to verify	Complex multi-step validation before approval

The 25 Lifecycle Events

Hooks fire at 25 distinct lifecycle points. Blocking-capable events include:

• 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

Exit Code	Meaning
0	Success. stdout parsed for JSON decisions.
2	Blocking error. stderr fed to Claude; action blocked.
1 or other	Non-blocking error. First line of stderr shown; execution continues.

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

Location	Scope
~/.claude/settings.json	All projects
.claude/settings.json	Single project
.claude/settings.local.json	Single project, not shared
Skill/agent frontmatter	Component lifetime

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 handling 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

Subagent	Model	Tools	Purpose
Explore	Haiku	Read-only	Fast codebase search and analysis
Plan	Inherits	Read-only	Research for plan mode
General-purpose	Inherits	All tools	Complex multi-step tasks

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

Field	Purpose
tools	Allowlist of tools the subagent can use
disallowedTools	Denylist (e.g., Write, Edit for read-only agents)
model	sonnet, opus, haiku, inherit, or full model ID
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan
skills	Preload skill content into subagent context
mcpServers	MCP servers scoped to this subagent
hooks	Lifecycle hooks scoped to this subagent
memory	Persistent memory: user, project, or local
isolation	worktree for git branch isolation
maxTurns	Maximum agentic turns before stopping

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

Request: "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

Aspect	CLAUDE.md	Skills
Loads	Automatically on session start	Only when invoked
Best for	Project conventions, permanent context	Procedures, playbooks, workflows
Cost	Always in context	Only when used

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

Field	Purpose
name	Display name; becomes the /slash-command
description	When Claude should use the skill automatically
disable-model-invocation	Set true to prevent auto-loading (for dangerous ops like deploy)
user-invocable	Set false to hide from / menu (background knowledge only)
allowed-tools	Tools Claude can use without asking permission when skill is active
context	Set fork to run in isolated subagent
agent	Which subagent type to use with context: fork
model / effort	Override model or effort level when skill is active
paths	Glob patterns limiting when skill auto-activates

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

`plaintext
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

Location	Path	Scope
Enterprise	Managed settings	Organization-wide
Personal	~/.claude/skills/<name>/SKILL.md	All your projects
Project	.claude/skills/<name>/SKILL.md	This project only
Plugin	<plugin>/skills/<name>/SKILL.md	Where plugin is enabled

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):

`markdown

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):

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

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

`markdown

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 producing 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:

`markdown

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:

`markdown

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:

`markdown

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 the Claude Code configuration guide. For model comparisons, see Claude Opus 4.7 API review and best AI model for agents 2026.

Summary

Feature	What It Does	Use When
Hooks	Deterministic lifecycle scripts	Security, logging, context injection, blocking
Subagents	Isolated AI workers	Parallel tasks, verbose output isolation, tool restriction
Skills	Reusable prompt templates	Repeatable workflows, conventions, team knowledge

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.

---

Originally published on ofox.ai/blog.