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. 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 are event-driven scripts executing when something happens in Claude Code. Unlike prompts relying on model interpretation, hooks run deterministic code incapable of hallucination. 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. 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 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 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. 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. #!/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. 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 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. 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 . 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) 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 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 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. 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. 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 extend what Claude can do by packaging instructions into invocable commands. Create a skill when you keep pasting the same playbook into chat. 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. 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 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 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. `plaintext Reference supporting files from SKILL.md so Claude knows what they contain and when to load them. Location Path Scope Enterprise Managed settings Organization-wide Personal ~/.claude/skills//SKILL.md All your projects Project .claude/skills//SKILL.md This project only Plugin /skills//SKILL.md Where plugin is enabled Higher-priority locations win: enterprise > personal > project. Plugin skills use plugin-name:skill-name namespace. 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. The three features compose together. Here is a production-ready setup: Skill (~/.claude/skills/secure-review/SKILL.md): markdown name: secure-review Perform a security-focused code review: Check for hardcoded secrets, API keys, or credentials Verify input validation and sanitization Review authentication and authorization logic Check for SQL injection, XSS, and injection vulnerabilities Verify error handling does not leak sensitive information Check file upload and path traversal protections Report findings with severity levels and specific file references. ` Hook (.claude/settings.json): `json Subagent (.claude/agents/security-reviewer.md): markdown name: security-reviewer 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. 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. Limit what subagents can do for safety: markdown name: db-reader ` The hook blocks any SQL write operation before it executes. Route different tasks to different models for cost optimization: markdown name: quick-classifier Classify this request as: simple, complex, or research-heavy. ` Haiku is fast and cheap for classification. Route complex tasks to Sonnet or Opus. Enable cross-session learning for subagents: markdown name: codebase-architect 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. 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. 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.