Claude Code Mastery

Claude Code Mastery

Expert skill for Claude Code CLI -- CLAUDE.md optimization, skill authoring, subagent creation, hooks automation, and context engineering.

Keywords

claude-code, claude-cli, CLAUDE.md, skill-authoring, subagents, hooks, context-window, token-budget, MCP-servers, worktrees, permission-modes, prompt-engineering, context-engineering, slash-commands

---

Quick Start

# Scaffold a new skill package
python scripts/skill_scaffolder.py my-new-skill --domain engineering --description "Brief description"

# Analyze and optimize an existing CLAUDE.md
python scripts/claudemd_optimizer.py path/to/CLAUDE.md

# Estimate context window usage across a project
python scripts/context_analyzer.py /path/to/project

# All tools support JSON output
python scripts/claudemd_optimizer.py CLAUDE.md --json

---

Tools

Skill Scaffolder

Generates a skill directory with SKILL.md template, scripts/, references/, assets/ directories, and YAML frontmatter.

python scripts/skill_scaffolder.py my-skill --domain engineering --description "Does X"

CLAUDE.md Optimizer

Analyzes a CLAUDE.md file and produces optimization recommendations.

python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000 --json

Output includes: line count, token estimate, section completeness, redundancy detection, missing sections, scored recommendations.

Context Analyzer

Scans a project to estimate context window consumption by file category.

python scripts/context_analyzer.py /path/to/project --max-depth 4 --json

Output includes: token estimates per category, percentage of context consumed, largest files, budget breakdown, reduction recommendations.

---

Workflow 1: Optimize a CLAUDE.md

1. Audit -- Run python scripts/claudemd_optimizer.py CLAUDE.md and capture the score. 2. Structure -- Reorganize into these sections:

   ## Project Purpose         -- What the project is
   ## Architecture Overview   -- Directory structure, key patterns
   ## Development Environment -- Build, test, setup commands
   ## Key Principles          -- 3-7 non-obvious rules
   ## Anti-Patterns to Avoid  -- Things that look right but are wrong
   ## Git Workflow            -- Branch strategy, commit conventions

3. Compress -- Convert paragraphs to bullets (saves ~30% tokens). Use code blocks for commands. Remove generic advice Claude already knows. 4. Hierarchize -- Move domain details to child CLAUDE.md files:

   project/
   ├── CLAUDE.md              # Global: purpose, architecture, principles
   ├── frontend/CLAUDE.md     # Frontend-specific: React patterns, styling
   ├── backend/CLAUDE.md      # Backend-specific: API patterns, DB conventions
   └── .claude/CLAUDE.md      # User-specific overrides (gitignored)

5. Validate -- Run python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000 and confirm score improved.

Workflow 2: Author a New Skill

1. Scaffold -- python scripts/skill_scaffolder.py my-skill -d engineering --description "..." 2. Write SKILL.md in this order:

• YAML frontmatter (name, description with trigger phrases, license, metadata)
• Title and one-line summary
• Quick Start (3-5 copy-pasteable commands)
• Tools (each script with usage and parameters table)
• Workflows (numbered step-by-step sequences)
• Reference links

3. Optimize the description for auto-discovery:

   description: >-
     This skill should be used when the user asks to "analyze performance",
     "optimize queries", "profile memory", or "benchmark endpoints".
     Use for performance engineering and capacity planning.

4. Build Python tools -- standard library only, argparse CLI, --json flag, module docstring, error handling. 5. Verify -- Confirm the skill triggers on expected prompts and tools run without errors.

Workflow 3: Create a Subagent

1. Define scope -- One narrow responsibility per agent. 2. Create agent YAML at .claude/agents/agent-name.yaml:

   name: security-reviewer
   description: Reviews code for security vulnerabilities
   model: claude-sonnet-4-20250514
   allowed-tools:
     - Read
     - Glob
     - Grep
     - Bash(git diff*)
   custom-instructions: |
     For every change:
     1. Check for hardcoded secrets
     2. Identify injection vulnerabilities
     3. Verify auth patterns
     4. Flag insecure dependencies
     Output a structured report with severity levels.

3. Set tool access -- read-only (Read, Glob, Grep), read+commands (+ Bash(npm test*)), or write-capable (+ Edit, Write). 4. Invoke -- /agents/security-reviewer Review the last 3 commits 5. Validate -- Confirm the agent stays within scope and produces structured output.

Workflow 4: Configure Hooks

Hooks run custom scripts at lifecycle events without user approval.

1. Add hook config to .claude/settings.json:

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [{ "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" }]
         }
       ],
       "PreToolUse": [
         {
           "matcher": "Bash",
           "hooks": [{ "type": "command", "command": "bash .claude/hooks/validate.sh" }]
         }
       ]
     }
   }

2. Test -- Trigger the relevant tool and confirm the hook fires. 3. Iterate -- Add matchers for additional tools as needed.

Workflow 5: Manage Context Budget

1. Audit -- python scripts/context_analyzer.py /path/to/project 2. Apply budget targets:

3. Reduce overhead -- Keep root CLAUDE.md under 4000 tokens. Use hierarchical loading. Avoid reading entire large files. Use /compact after completing subtasks. 4. Validate -- Re-run context analyzer and confirm overhead dropped.

---

Quick Reference

Slash Commands

Permission Modes

{ "permissions": { "allow": ["Read", "Glob", "Grep", "Bash(npm test*)"],
                    "deny": ["Bash(rm -rf*)", "Bash(git push*)"] } }

CLAUDE.md Loading Order

1. ~/.claude/CLAUDE.md -- user global, always loaded 2. /project/CLAUDE.md -- project root, always loaded 3. /project/.claude/CLAUDE.md -- project config, always loaded 4. /project/subdir/CLAUDE.md -- subdirectory, loaded when files accessed

MCP Servers

---

Reference Documentation

---

Troubleshooting

Success Criteria

• CLAUDE.md optimizer score of 80+ on all project CLAUDE.md files
• Root CLAUDE.md stays under 4000 tokens (verified by claudemd_optimizer.py --token-limit 4000)
• Auto-loaded configuration (all CLAUDE.md files combined) consumes less than 10% of the context window
• Every new skill scaffolded passes the optimizer with zero "critical" missing sections
• Subagents stay within their declared allowed-tools scope during testing
• Hooks execute in under 500ms to avoid perceptible delay on tool use
• Context analyzer shows 50%+ of the context window available for source code and reasoning

Scope & Limitations

This skill covers:

• Authoring, structuring, and optimizing CLAUDE.md files for any project
• Scaffolding new skill packages with correct directory layout and frontmatter
• Creating and configuring Claude Code subagents with scoped tool access
• Analyzing and managing context window token budgets across a codebase

This skill does NOT cover:

• Writing application source code or implementing business logic (see senior-fullstack, senior-backend)
• MCP server development or custom transport protocols (see mcp-server-builder)
• Advanced prompt engineering techniques for LLM applications (see senior-prompt-engineer)
• CI/CD pipeline configuration or deployment automation (see senior-devops, ci-cd-pipeline-builder)

Integration Points

Tool Reference

1. Skill Scaffolder (scripts/skill_scaffolder.py)

Purpose: Generate a complete skill package directory with SKILL.md template, starter Python script, reference document, and proper YAML frontmatter.

Usage:

python scripts/skill_scaffolder.py <skill_name> [options]

Parameters:

Example:

python scripts/skill_scaffolder.py api-analyzer -d engineering --description "API analysis and optimization" --json

Output Formats:

• Human-readable (default): Prints skill name, domain, version, location, directory tree, and next-steps checklist.
• JSON (`--json`): Returns { success, path, name, domain, version, directories_created, files_created }.

---

2. CLAUDE.md Optimizer (scripts/claudemd_optimizer.py)

Purpose: Analyze a CLAUDE.md file for structure completeness, token efficiency, redundancy, and verbosity. Produces a scored report with prioritized optimization recommendations.

Usage:

python scripts/claudemd_optimizer.py <file_path> [options]

Parameters:

Example:

python scripts/claudemd_optimizer.py path/to/CLAUDE.md --token-limit 4000

Output Formats:

• Human-readable (default): Displays score (0-100), file metrics (lines, words, tokens), section breakdown with per-section token estimates, section completeness checklist (critical/high/medium), redundancy issues, and prioritized recommendations (HIGH/MEDIUM/LOW).
• JSON (`--json`): Returns { success, file, metrics, sections, completeness, redundancies, recommendations, score }.

---

3. Context Analyzer (scripts/context_analyzer.py)

Purpose: Scan a project directory to estimate how much of Claude Code's context window is consumed by CLAUDE.md files, skill definitions, source code, and configuration. Produces a token budget breakdown with reduction recommendations.

Usage:

python scripts/context_analyzer.py <project_path> [options]

Parameters:

Example:

python scripts/context_analyzer.py /path/to/project --max-depth 3 --context-window 200000 --json

Output Formats:

• Human-readable (default): Displays project summary (files scanned, total tokens, auto-loaded tokens), context budget breakdown with visual bar chart, per-category breakdown (Claude Configuration, Skill Definitions, Reference Documents, Source Code, Config & Build, Documentation) with largest files listed, top 20 largest files, and prioritized recommendations.
• JSON (`--json`): Returns { success, project_path, context_window, summary, categories, budget, largest_files, recommendations }.

<!-- USAGE: Save this file to .claude/agents/your-agent-name.md Invoke with: /agents/your-agent-name <your instructions>

EXAMPLES: /agents/your-agent-name Review the authentication module /agents/your-agent-name Analyze the last 5 commits for issues /agents/your-agent-name Check all API endpoints for problems

CUSTOMIZATION GUIDE: 1. Replace [role], [domain], [scope] with your specifics 2. Adjust allowed-tools to match what the agent needs 3. Customize the Protocol steps for your workflow 4. Modify the Report format if a different structure fits better 5. Add/remove Rules based on your requirements

MODEL OPTIONS: claude-opus-4-20250514 - Complex analysis, architecture decisions claude-sonnet-4-20250514 - General coding, standard review (recommended default) claude-haiku-3-5-20241022 - Simple checks, formatting, quick tasks

TOOL ACCESS PATTERNS: Read-only (review): Read, Glob, Grep Read + git: Read, Glob, Grep, Bash(git diff), Bash(git log) Read + test: Read, Glob, Grep, Bash(npm test), Bash(pytest) Write (generation): Read, Write, Edit, Glob, Grep Full access: (omit allowed-tools entirely) -->

Your Skill Title

One-line summary of what this skill provides and who benefits from it.

Keywords

keyword1, keyword2, keyword3, keyword4, keyword5, action-verb1, action-verb2, domain-term1, domain-term2

---

Table of Contents

• Quick Start
• Tools Overview
• Tool One
• Tool Two
• Workflows
• Primary Workflow
• Secondary Workflow
• Reference Documentation
• Quick Reference

---

Quick Start

# Primary tool - basic usage
python scripts/tool_one.py input_file.txt

# Primary tool - with options
python scripts/tool_one.py input_file.txt --option value --json

# Secondary tool
python scripts/tool_two.py /path/to/dir --format table

---

Tools Overview

1. Tool One

Brief description of what this tool does and when to use it.

# Basic usage
python scripts/tool_one.py input

# With options
python scripts/tool_one.py input --option value

# JSON output for piping
python scripts/tool_one.py input --json

Example output:

Tool One Report
================
  Input:   example.txt
  Status:  Analyzed
  Score:   85/100

Findings:
  1. Finding description (severity)
  2. Finding description (severity)

2. Tool Two

Brief description of what this tool does and when to use it.

python scripts/tool_two.py /path/to/dir
python scripts/tool_two.py /path/to/dir --depth 3 --json

---

Workflows

Workflow 1: Primary Workflow

Description of when and why to use this workflow.

Step 1: Analyze the Current State

python scripts/tool_one.py target --json > analysis.json

Review the output and identify areas that need attention.

Step 2: Apply Changes

Based on the analysis, take the following actions:

• Action based on finding type A
• Action based on finding type B
• Action based on finding type C

Step 3: Validate

python scripts/tool_one.py target --json

Verify the score has improved and no regressions were introduced.

Workflow 2: Secondary Workflow

Description of the secondary use case.

Step 1: Setup

python scripts/tool_two.py /path/to/project

Step 2: Execute

Follow the recommendations from the tool output.

Step 3: Verify

Re-run the tool and confirm improvements.

---

Reference Documentation

---

Quick Reference

Common Commands

Decision Matrix

---

Last Updated: Month Year Version: 1.0.0

Hooks Cookbook

Practical hook recipes for automating code quality, security enforcement, workflow optimization, and developer experience with Claude Code.

---

Table of Contents

• Hook Architecture
• Lifecycle Events
• Hook Types
• Environment Variables
• Recipes: Code Quality
• Recipes: Security
• Recipes: Workflow
• Recipes: Notifications
• Recipes: Context Management
• Recipes: Logging and Audit
• Recipes: Advanced Patterns
• Best Practices
• Troubleshooting

---

Hook Architecture

Hooks are configured in .claude/settings.json (project-level, committed) or ~/.claude/settings.json (user-level, global). Project-level hooks apply to everyone working on the project. User-level hooks apply to all projects.

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolNameRegex",
        "hooks": [
          {
            "type": "command",
            "command": "your-shell-command"
          }
        ]
      }
    ]
  }
}

---

Lifecycle Events

Blocking behavior: Only PreToolUse hooks can prevent an action. If the hook script exits with code 1, the tool call is blocked. All other events are informational -- the hook runs but cannot stop the action.

---

Hook Types

Command Hooks

Run a shell command. Fast, deterministic, no LLM cost.

{
  "type": "command",
  "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}

Prompt Hooks

Send a single-turn prompt to a fast model (Haiku by default). Useful for content evaluation that requires judgment.

{
  "type": "prompt",
  "prompt": "Check if this change introduces security issues. Output WARNING if yes, nothing if no.",
  "model": "haiku"
}

Agent Hooks

Launch a multi-turn agent with tool access. Most powerful but slowest and most expensive. Use sparingly.

{
  "type": "agent",
  "prompt": "Review the changed file for security vulnerabilities and report findings.",
  "model": "sonnet",
  "tools": ["Read", "Grep"]
}

---

Environment Variables

These variables are available in hook commands:

stdin: Hook commands also receive a JSON payload on stdin with the full tool input and context.

---

Recipes: Code Quality

Recipe 1: Auto-Format Python with Black

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then python3 -m black --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi"
          }
        ]
      }
    ]
  }
}

Recipe 2: Auto-Format JavaScript/TypeScript with Prettier

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.(js|jsx|ts|tsx|css|json|md)$ ]]; then npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

Recipe 3: Run ESLint Auto-Fix

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.(ts|tsx|js|jsx)$ ]]; then npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

Recipe 4: Type-Check After TypeScript Edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.tsx?$ ]]; then npx tsc --noEmit --pretty 2>&1 | head -20 || true; fi"
          }
        ]
      }
    ]
  }
}

Recipe 5: Run Ruff Linter on Python Files

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then ruff check --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null && ruff format \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi"
          }
        ]
      }
    ]
  }
}

Recipe 6: Validate JSON After Edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.json ]]; then python3 -c \"import json; json.load(open('$CLAUDE_FILE_PATH'))\" 2>&1 || echo 'WARNING: Invalid JSON in $CLAUDE_FILE_PATH' >&2; fi"
          }
        ]
      }
    ]
  }
}

---

Recipes: Security

Recipe 7: Protect Sensitive Files

Block modifications to files containing secrets or credentials.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_FILE_PATH\" | grep -qiE '(\\.env$|\\.env\\.|credentials|secrets?|private.key|id_rsa)'; then echo 'BLOCKED: Cannot modify sensitive files' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Recipe 8: Block Dangerous Bash Commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_COMMAND\" | grep -qE '(rm -rf /|rm -rf \\*|DROP TABLE|DROP DATABASE|--force push|git push.*(--force|-f)|> /dev/sd|mkfs\\.|dd if=)'; then echo 'BLOCKED: Potentially destructive command' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Recipe 9: Block Production Environment Access

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_COMMAND\" | grep -qiE '(production|prod\\.|prod-|PROD_|--prod)'; then echo 'BLOCKED: Production commands not allowed in development' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Recipe 10: Prevent Editing Generated/Vendored Files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_FILE_PATH\" | grep -qE '(generated|dist/|build/|\\.min\\.|vendor/|node_modules/)'; then echo 'BLOCKED: Cannot edit generated or vendored files' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Recipe 11: AI-Powered Security Review (Prompt Hook)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this file change introduces security vulnerabilities (injection, XSS, hardcoded secrets, insecure crypto). If yes, output a brief WARNING with the issue. If clean, output nothing.",
            "model": "haiku"
          }
        ]
      }
    ]
  }
}

---

Recipes: Workflow

Recipe 12: Enforce Conventional Commits

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_COMMAND\" | grep -q 'git commit'; then if ! echo \"$CLAUDE_TOOL_ARG_COMMAND\" | grep -qE '(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(|:)'; then echo 'BLOCKED: Commit must use conventional commits (feat|fix|docs|...)' >&2; exit 1; fi; fi"
          }
        ]
      }
    ]
  }
}

Recipe 13: Auto-Stage Written Files

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "git add \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Recipe 14: Remind About Barrel Exports

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.(ts|tsx)$ ]] && [[ ! \"$CLAUDE_FILE_PATH\" =~ index\\.ts ]]; then DIR=$(dirname \"$CLAUDE_FILE_PATH\"); if [ -f \"$DIR/index.ts\" ]; then echo \"Note: Consider updating $DIR/index.ts with the new export\" >&2; fi; fi"
          }
        ]
      }
    ]
  }
}

Recipe 15: Run Related Tests After Edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" =~ \\.py$ ]] && [[ ! \"$CLAUDE_FILE_PATH\" =~ test_ ]]; then TESTFILE=$(echo \"$CLAUDE_FILE_PATH\" | sed 's/\\(.*\\)\\/\\(.*\\)\\.py/\\1\\/test_\\2.py/'); if [ -f \"$TESTFILE\" ]; then python3 -m pytest \"$TESTFILE\" -x -q 2>&1 | tail -5; fi; fi"
          }
        ]
      }
    ]
  }
}

Recipe 16: Restrict Bash to Read-Only Commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_ARG_COMMAND\" | grep -qE '^(rm |mv |cp |chmod|chown|kill|pkill|mkdir|touch|tee |>|>>)'; then echo 'BLOCKED: Only read commands allowed in this mode' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

---

Recipes: Notifications

Recipe 17: macOS Desktop Notification on Task Complete

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code finished\" with title \"Claude Code\" sound name \"Glass\"' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Recipe 18: Linux Desktop Notification

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send --app-name='Claude Code' 'Task Complete' 'Claude Code finished its response' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Recipe 19: Play Sound on Completion

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

---

Recipes: Context Management

Recipe 20: Inject Context on Session Start

Re-inject critical context after compaction or at session start.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Project: MyApp v2.1 | Stack: Next.js 14, PostgreSQL, Redis | Testing: Jest + Playwright | Deploy: Vercel + AWS\""
          }
        ]
      }
    ]
  }
}

Recipe 21: Load Session Notes on Start

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f .claude/session-notes.md ]; then echo '--- Session Notes ---'; cat .claude/session-notes.md; echo '---'; fi"
          }
        ]
      }
    ]
  }
}

Recipe 22: Inject Git Branch Context

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "BRANCH=$(git branch --show-current 2>/dev/null); if [ -n \"$BRANCH\" ]; then echo \"Current branch: $BRANCH\"; BEHIND=$(git rev-list --count HEAD..origin/$BRANCH 2>/dev/null || echo 0); if [ \"$BEHIND\" -gt 0 ]; then echo \"WARNING: Branch is $BEHIND commits behind remote\"; fi; fi"
          }
        ]
      }
    ]
  }
}

---

Recipes: Logging and Audit

Recipe 23: Log All Tool Usage

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date -Iseconds) | $CLAUDE_TOOL_NAME | ${CLAUDE_FILE_PATH:-${CLAUDE_TOOL_ARG_COMMAND:-n/a}}\" >> .claude/tool-usage.log 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Recipe 24: Log Session Duration

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"SESSION_START $(date -Iseconds) $CLAUDE_SESSION_ID\" >> .claude/sessions.log 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"SESSION_STOP $(date -Iseconds) $CLAUDE_SESSION_ID\" >> .claude/sessions.log 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

---

Recipes: Advanced Patterns

Recipe 25: Combine Multiple Hooks on One Event

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then python3 -m black --quiet \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi"
          },
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.py ]]; then ruff check --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null; fi"
          },
          {
            "type": "command",
            "command": "echo \"$(date -Iseconds) | FORMAT | $CLAUDE_FILE_PATH\" >> .claude/tool-usage.log 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Recipe 26: Conditional Hook with External Script

Create a reusable hook script for complex logic:

`.claude/hooks/validate-edit.sh`:

#!/bin/bash
# Validate file edits with multiple checks

FILE="$CLAUDE_TOOL_ARG_FILE_PATH"

# Check 1: Not a lock file
if [[ "$FILE" =~ (lock|\.lock)$ ]]; then
    echo "BLOCKED: Cannot edit lock files" >&2
    exit 1
fi

# Check 2: Not in node_modules
if [[ "$FILE" =~ node_modules/ ]]; then
    echo "BLOCKED: Cannot edit node_modules" >&2
    exit 1
fi

# Check 3: File size limit (prevent editing huge files)
if [ -f "$FILE" ]; then
    SIZE=$(wc -c < "$FILE")
    if [ "$SIZE" -gt 100000 ]; then
        echo "WARNING: File is $(( SIZE / 1024 ))KB - consider editing specific sections" >&2
    fi
fi

exit 0

`.claude/settings.json`:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-edit.sh"
          }
        ]
      }
    ]
  }
}

---

Best Practices

1. Always fail safe -- Use 2>/dev/null || true for non-critical hooks. A failing PostToolUse hook should not break the workflow.

2. Keep hooks fast -- Command hooks should complete in under 2 seconds. Slow hooks degrade the interactive experience.

3. Use exit codes correctly -- Exit 1 in PreToolUse blocks the action. Exit 0 (or any code) in PostToolUse is informational only.

4. Write messages to stderr -- Hook output on stderr is shown to the user. Output on stdout may be captured differently.

5. Test in local settings first -- Use .claude/settings.local.json for personal hooks. Only commit to .claude/settings.json when proven stable.

6. Use prompt hooks sparingly -- They add latency (1-3 seconds) and cost money. Reserve them for security-critical checks.

7. Log for debugging -- Add a logging hook during development and remove it when everything works.

8. Document your hooks -- Add a comment (as a separate echo to /dev/null) or maintain a README explaining what each hook does.

9. Keep matchers specific -- "Edit|Write" is better than "" (which matches everything). Specific matchers reduce unnecessary hook executions.

10. Combine related hooks -- Use the hooks array to run multiple commands on the same event/matcher rather than creating separate entries.

---

Troubleshooting

Hook Not Firing

• Verify the event name is spelled correctly (case-sensitive)
• Check that the matcher regex matches the tool name
• Ensure the settings file is valid JSON (python3 -c "import json; json.load(open('.claude/settings.json'))")
• Check that the command exists and is executable

Hook Blocking Unexpectedly

• Add echo debugging: echo "DEBUG: PATH=$CLAUDE_TOOL_ARG_FILE_PATH" >&2
• Check that your grep patterns are not too broad
• Verify that exit codes are correct (exit 0 = allow, exit 1 = block)

Hook Running Too Slowly

• Profile the command: time your-command
• Use || true to skip slow operations that fail
• Move complex logic to a compiled script
• Consider if the hook can run asynchronously (PostToolUse only)

Hook Errors in Logs

• Check stderr output: hooks log errors to the Claude Code console
• Verify file paths are properly quoted (spaces in paths)
• Ensure external tools (prettier, eslint, black) are installed

---

Last Updated: February 2026

Skill Authoring Guide

Comprehensive reference for writing effective Claude Code skills -- from YAML frontmatter to progressive disclosure, tool restrictions, and context optimization.

---

Table of Contents

• Skill Package Structure
• YAML Frontmatter
• Description Optimization
• SKILL.md Anatomy
• Progressive Disclosure
• Python Tool Standards
• Reference Document Standards
• Context Modes and Loading
• Model Selection Guidance
• Testing Your Skill

---

Skill Package Structure

Every skill follows this directory layout:

skill-name/
├── SKILL.md              # Master documentation (always the entry point)
├── scripts/              # Python CLI tools
│   ├── tool_one.py
│   └── tool_two.py
├── references/           # Deep-dive knowledge bases
│   ├── guide_one.md
│   └── guide_two.md
└── assets/               # User-facing templates and examples
    ├── template.md
    └── checklist.md

Design rules:

1. Self-contained -- Every skill must work independently. No cross-skill imports. 2. SKILL.md is the interface -- Claude reads this first and decides what to use. 3. Scripts are tools, not libraries -- Each script is a CLI tool, not a shared module. 4. References are on-demand -- Only loaded when Claude needs deep knowledge. 5. Assets are for users -- Templates the user copies and customizes.

---

YAML Frontmatter

The frontmatter at the top of SKILL.md determines how Claude discovers and activates the skill.

Required Fields

---
name: skill-name
description: >-
  This skill should be used when the user asks to "do X", "analyze Y",
  "generate Z", or "optimize W". Use for domain expertise, workflow
  automation, and analysis.
---

`name` -- Kebab-case identifier matching the directory name. Used for referencing and logging.

`description` -- The most important field. This is what Claude reads to decide whether to activate the skill. Write it in third person and load it with trigger phrases.

Optional Fields

---
name: skill-name
description: >-
  Description text...
license: MIT
metadata:
  version: 1.0.0
  category: engineering
  domain: development-tools
  author: Team Name
  tags: [cli, automation, analysis]
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(python*)
---

`license` -- License type (MIT, Apache-2.0, proprietary, etc.).

`metadata` -- Structured metadata for categorization and versioning.

• version -- Semantic version (major.minor.patch)
• category -- Broad category (engineering, marketing, product, etc.)
• domain -- Specific domain (development-tools, seo, compliance, etc.)
• author -- Creator or team name
• tags -- Array of discovery keywords

`allowed-tools` -- Restricts which tools the skill can use. Useful for creating read-only analysis skills or skills that should never write files.

---

Description Optimization

The description field is the skill's discovery mechanism. Claude scans descriptions to match user requests to relevant skills.

Writing Effective Descriptions

Pattern: Third person, trigger phrases in quotes, use cases at the end.

# GOOD -- Packed with trigger phrases, specific use cases
description: >-
  This skill should be used when the user asks to "analyze API performance",
  "benchmark endpoints", "profile response times", "identify bottlenecks",
  or "optimize throughput". Use for REST API performance analysis, load
  testing configuration, latency profiling, and capacity planning.

# BAD -- Vague, no trigger phrases
description: >-
  A skill for working with APIs and performance.

# BAD -- First person, narrative style
description: >-
  I help users analyze their API performance and find issues.

Trigger Phrase Rules

1. Use verb phrases users actually say: "analyze X", "create Y", "optimize Z" 2. Include 5-10 trigger phrases minimum 3. Cover synonyms: "benchmark" and "profile" and "measure" 4. Include the domain: "REST API", "database queries", "frontend rendering" 5. End with a summary of use cases

Testing Discovery

Ask Claude: "I need to optimize my API response times." If your skill is not activated, add more trigger phrases related to that phrasing.

---

SKILL.md Anatomy

A well-structured SKILL.md follows this order:

1. YAML Frontmatter

See above.

2. Title and One-Line Summary

# API Performance Analyzer

Identify bottlenecks, benchmark endpoints, and optimize API throughput.

3. Keywords

A comma-separated list of discovery terms that supplements the description.

## Keywords

api, performance, latency, throughput, benchmarking, profiling, bottleneck,
response-time, load-testing, capacity-planning

4. Table of Contents

Link to all major sections for quick navigation.

5. Quick Start

Three to five commands that demonstrate the skill immediately. A user should be able to copy-paste these and see results.

6. Tools Overview

Each script with usage examples, parameter tables, and sample output.

7. Workflows

Step-by-step sequences that combine tools, knowledge, and judgment. Workflows are the most valuable part of a skill because they encode expertise.

8. Reference Documentation

Table linking to files in references/.

9. Quick Reference

Tables, cheat sheets, and at-a-glance summaries for common operations.

---

Progressive Disclosure

Structure skills so Claude loads only what it needs for the current task.

Layer 1: SKILL.md (Always Loaded When Active)

Contains the skill overview, tool descriptions, and workflow summaries. Keep under 400 lines if possible.

Layer 2: Reference Documents (Loaded on Demand)

Deep knowledge bases that Claude reads when it needs specific expertise. These are NOT loaded automatically.

## Reference Documentation

| Document | Path | When to Use |
|----------|------|-------------|
| API Patterns | references/api-patterns.md | Designing new API endpoints |
| Error Handling | references/error-handling.md | Implementing error responses |
| Caching Guide | references/caching-guide.md | Optimizing response times |

Layer 3: Assets (User-Facing)

Templates and examples the user copies. Claude references these when helping users fill them out.

Loading Control

Use clear indicators in SKILL.md to tell Claude when to load reference docs:

> For detailed caching strategies, see [references/caching-guide.md](references/caching-guide.md)

This is better than including all caching knowledge directly in SKILL.md.

---

Python Tool Standards

Every Python script in a skill must follow these standards:

Structure Template

#!/usr/bin/env python3
"""
Tool Name - One line description

Detailed description of what the tool does, what input it expects,
and what output it produces.

Usage:
    python tool_name.py input_arg
    python tool_name.py input_arg --option value
    python tool_name.py input_arg --json
"""

import argparse
import json
import sys
from pathlib import Path

def main():
    parser = argparse.ArgumentParser(
        description="Tool description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("input", help="Input to process")
    parser.add_argument("--json", action="store_true", help="Output in JSON format")
    args = parser.parse_args()

    result = {"key": "value"}

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_human_readable(result)

if __name__ == "__main__":
    main()

Rules

1. Standard library only -- No pip dependencies. Scripts must run anywhere. 2. argparse with --help -- Every script must have useful help text. 3. --json flag -- Support machine-readable JSON output. 4. Module docstring -- Include usage examples in the docstring. 5. Error handling -- Catch exceptions, print useful messages, exit with non-zero. 6. No LLM calls -- Scripts must be deterministic and fast. 7. No network calls -- Unless the skill explicitly requires it (and documents it). 8. Executable -- Set chmod +x and include the shebang line.

Output Conventions

• Human-readable: Clear labels, aligned columns, section headers
• JSON: Flat structure preferred, always include a success boolean
• Errors: Print to stderr, exit code 1
• Progress: Use stderr for progress messages so stdout stays clean for piping

---

Reference Document Standards

Structure

# Document Title

## Overview
One paragraph context.

## Section 1
Content with examples.

## Section 2
Content with examples.

## Quick Reference
Tables and cheat sheets.

---
**Last Updated:** Month Year

Rules

1. Single topic per file -- "Caching Strategies" not "Caching and Performance" 2. Actionable content -- Every section should tell the reader what to DO 3. Code examples -- Show, don't just tell 4. Tables for comparisons -- Use tables when comparing options 5. Under 500 lines -- Split longer guides into multiple files 6. No redundancy with SKILL.md -- Reference docs go deeper, not wider

---

Context Modes and Loading

Understanding how Claude Code loads files helps you structure skills efficiently.

Fork vs Main Context Modes

The context field in YAML frontmatter controls how the skill's conversation context relates to the main conversation.

Fork Mode (context: fork):

• Creates an isolated context branch for the skill
• Skill runs in its own conversation thread
• Does not pollute the main conversation history with file reads
• Results are summarized back to the main thread
• Best for: long-running analyses, tasks that read many files, heavy output

Main Mode (context: main, default):

• Skill runs in the current conversation context
• Has access to full conversation history
• Results stay in the main thread
• Best for: quick operations, tasks that build on recent conversation

Automatic Loading

These files load for EVERY conversation:

• ~/.claude/CLAUDE.md (user global)
• <project>/CLAUDE.md (project root)
• <project>/.claude/CLAUDE.md (project config)

On-Demand Loading

These load when Claude accesses files in the directory:

• <project>/subdir/CLAUDE.md (subdirectory-specific)

Skill Loading

SKILL.md files load when:

• The user's request matches the skill description
• Claude determines the skill is relevant
• The user explicitly invokes the skill

Reference Loading

Reference files load when:

• Claude reads them with the Read tool
• They are referenced in a workflow Claude is executing
• The user asks Claude to consult them

Optimization Strategy

1. Put project-wide rules in root CLAUDE.md (auto-loaded, keep small) 2. Put domain rules in subdirectory CLAUDE.md files (on-demand) 3. Put workflow knowledge in SKILL.md (skill-triggered) 4. Put deep expertise in references/ (explicit read)

---

String Substitutions

Skills support special string substitutions that are replaced at invocation time. These allow skills to be parameterized and dynamic.

Available Substitutions

Using Substitutions in SKILL.md

## Quick Start

Analyzing: $ARGUMENTS

\```bash
python scripts/analyzer.py $PROJECT_DIR $1
\```

When the user invokes the skill with arguments, the variables are replaced before the skill content is processed.

Using Substitutions in Frontmatter

custom-instructions: |
  Analyze the following request: $ARGUMENTS
  Focus on the project at: $PROJECT_DIR
  Currently active file: $FILE

Practical Examples

Skill invoked with: /skill my-skill review src/auth/

Best Practices for Substitutions

1. Always provide defaults -- Do not assume $ARGUMENTS is non-empty. 2. Document expected arguments -- In the Quick Start section, show what arguments the skill expects. 3. Use `$PROJECT_DIR` for scripts -- Ensures paths resolve correctly regardless of where the skill is invoked from. 4. Avoid `$FILE` in mandatory flows -- It may be empty if no file is active.

---

Model Selection Guidance

When creating agents or suggesting configurations, choose models based on the task:

For agent definitions that specify a model:

# Complex analysis agent
model: claude-opus-4-20250514

# General-purpose coding agent
model: claude-sonnet-4-20250514

# Quick formatting/linting agent
model: claude-haiku-3-5-20241022

---

Testing Your Skill

Functional Testing

1. Run every script with --help and verify output 2. Run every script with sample input and verify results 3. Run every script with --json and verify valid JSON 4. Run every script with invalid input and verify error handling

Integration Testing

1. Start a Claude Code session in a test project 2. Ask a question that should trigger your skill 3. Verify Claude finds and uses the correct tool 4. Verify the workflow produces expected results

Discovery Testing

1. Ask Claude variations of questions your skill should handle 2. Note which phrasings do NOT trigger the skill 3. Add those phrasings as trigger phrases in the description

Quality Checklist

• [ ] SKILL.md has valid YAML frontmatter
• [ ] Description contains 5+ trigger phrases
• [ ] Quick Start has 3+ copy-pasteable commands
• [ ] All scripts run with --help
• [ ] All scripts support --json
• [ ] All scripts handle errors gracefully
• [ ] Reference docs are single-topic and under 500 lines
• [ ] No dependencies beyond Python standard library
• [ ] No cross-skill imports or dependencies

---

Last Updated: February 2026

Subagent Patterns

Comprehensive guide to creating and using Claude Code subagents for parallel work, specialized review, automated workflows, and task delegation.

---

Table of Contents

• What Are Subagents
• Built-in Agent Support
• Custom Agent Creation
• Agent File Anatomy
• Tool Access Patterns
• Delegation Patterns
• Memory and State
• Isolation Modes
• Hooks Integration
• Production Recipes

---

What Are Subagents

Subagents are specialized Claude Code instances that run with their own system prompts, tool restrictions, and behavioral instructions. They operate in isolation from the main conversation but can return results.

Key properties:

• Run with a separate system prompt (custom-instructions)
• Can be restricted to specific tools (allowed-tools)
• Execute in the same project directory
• Return their output to the calling conversation
• Do not share conversation history with the main session

When to use subagents:

• Specialized review tasks (security, performance, accessibility)
• Parallel research across multiple files
• Automated generation with strict constraints
• Tasks that benefit from a fresh context window

---

Built-in Agent Support

Claude Code ships with several built-in agents that are always available without custom configuration.

Explore Agent

Purpose: Read-only codebase exploration and analysis.

Capabilities:

• Read files, search with Glob and Grep
• Navigate directory structures
• Cannot modify any files

When to use:

• Understanding unfamiliar codebases
• Finding where a feature is implemented
• Tracing data flow across files
• Answering "where is X defined" questions

Invocation:

/agents/explore How is authentication implemented in this project?

Plan Agent

Purpose: Generate implementation plans without making changes.

Capabilities:

• Full read access to the codebase
• Produces structured plans with file lists and step-by-step instructions
• Cannot modify any files

When to use:

• Before starting a large refactor
• Planning a new feature across multiple files
• Estimating scope of a change

Invocation:

/agents/plan Plan the migration from REST to GraphQL for the user service

General-Purpose Subagent

Purpose: A delegated Claude Code instance with full capabilities.

Capabilities:

• All tools available (same as main session)
• Runs in an isolated context
• Results summarized back to parent

When to use:

• Parallel task execution
• Tasks that would flood the main context
• Work that benefits from a clean context slate

Custom Agents Directory

Custom agents live in .claude/agents/:

.claude/
└── agents/
    ├── security-reviewer.md
    ├── test-writer.md
    ├── doc-generator.md
    └── migration-helper.md

Invocation:

/agents/security-reviewer Review the authentication module for vulnerabilities
/agents/test-writer Write unit tests for src/services/payment.ts
/agents/doc-generator Generate API documentation for the REST endpoints

---

Custom Agent Creation

Step 1: Define the Agent's Purpose

Every agent needs a narrow, well-defined scope. Good agents do one thing well.

Good scopes:

• "Reviews code changes for security vulnerabilities"
• "Writes comprehensive test suites for TypeScript modules"
• "Generates OpenAPI documentation from route handlers"
• "Analyzes database queries for N+1 problems"

Bad scopes:

• "Helps with coding" (too broad)
• "Does everything" (defeats the purpose of specialization)
• "Reviews and fixes code" (conflates review and modification)

Step 2: Create the Agent File

Agent files use YAML frontmatter followed by optional markdown content.

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities and compliance issues
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff*)
  - Bash(git log*)
custom-instructions: |
  You are a security-focused code reviewer. For every change you review:

  1. Check for hardcoded secrets, credentials, API keys, or tokens
  2. Identify injection vulnerabilities (SQL, XSS, command injection)
  3. Verify authentication and authorization patterns
  4. Flag insecure dependencies or deprecated crypto functions
  5. Check for information disclosure in error messages

  Output Format:
  ## Security Review Summary
  - **Risk Level:** HIGH / MEDIUM / LOW / CLEAN
  - **Issues Found:** N

  ## Issues
  For each issue:
  - File and line number
  - Severity (Critical / High / Medium / Low / Info)
  - Description
  - Recommended fix

  ## Recommendations
  Prioritized list of actions.
---

Step 3: Test the Agent

/agents/security-reviewer Review the changes in the last commit

Verify that:

• The agent activates correctly
• Tool restrictions are enforced
• Output follows the specified format
• It stays within its defined scope

---

Agent File Anatomy

Required Fields

name: agent-name           # Kebab-case identifier
description: What it does  # Brief description for discovery

Optional Fields

model: claude-sonnet-4-20250514   # Model override (default: session model)
allowed-tools:                     # Tool whitelist (default: all tools)
  - Read
  - Glob
custom-instructions: |             # System prompt for the agent
  Your behavioral instructions here.

Field Details

`name` -- Used for invocation: /agents/<name>. Must be unique within the agents directory.

`description` -- Helps Claude decide when to suggest this agent. Also shown when listing agents with /agents.

`model` -- Override the model for this agent. Use cheaper/faster models for simple tasks:

• claude-opus-4-20250514 -- Complex analysis, architecture review
• claude-sonnet-4-20250514 -- General coding, standard review
• claude-haiku-3-5-20241022 -- Simple formatting, quick checks

`allowed-tools` -- Whitelist of tools the agent can use. Supports glob patterns for Bash commands:

• Read -- Read files
• Glob -- Find files
• Grep -- Search content
• Edit -- Modify files
• Write -- Create files
• Bash(pattern*) -- Run matching bash commands
• WebFetch -- Fetch URLs
• WebSearch -- Search the web

`custom-instructions` -- The system prompt. This is where you define the agent's personality, workflow, output format, and constraints.

---

Tool Access Patterns

Read-Only Agent (Safe for Review)

allowed-tools:
  - Read
  - Glob
  - Grep

Best for: Code review, security audit, documentation analysis, architecture review.

Read + Specific Commands

allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff*)
  - Bash(git log*)
  - Bash(npm test*)
  - Bash(npm run lint*)

Best for: Review tasks that need git context or test results.

Write-Capable Agent

allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(mkdir*)

Best for: Code generation, test writing, documentation generation.

Full Access Agent

# Omit allowed-tools entirely for full access
# Or explicitly:
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - WebFetch
  - WebSearch

Best for: Complex multi-step tasks that need all capabilities.

Restricted Bash Patterns

allowed-tools:
  - Bash(python scripts/*)      # Only run project scripts
  - Bash(npm run *)             # Only run npm scripts
  - Bash(docker compose *)      # Only docker commands
  - Bash(git status)            # Specific git commands (no glob)
  - Bash(git diff*)             # Git diff with any arguments

---

Delegation Patterns

Pattern 1: Review Then Act

Use a read-only agent to review, then act on the findings yourself.

# Step 1: Agent reviews
/agents/security-reviewer Review all files changed in the last 5 commits

# Step 2: Human or main session acts on findings
Fix the SQL injection vulnerability identified in src/db/queries.ts line 45

Pattern 2: Generate Then Review

Use a write agent to generate code, then a review agent to check it.

# Step 1: Generate
/agents/test-writer Write comprehensive tests for src/services/auth.ts

# Step 2: Review
/agents/security-reviewer Review the newly generated test file for any security issues

Pattern 3: Parallel Research

Use multiple agents to research different aspects simultaneously.

# Research architecture patterns
/agents/architecture-analyst Analyze the data flow in the payment processing module

# Research performance characteristics
/agents/performance-profiler Identify potential bottlenecks in the checkout flow

Pattern 4: Specialized Transformation

Use agents for specific, repeatable transformations.

# Convert JavaScript to TypeScript
/agents/ts-migrator Convert src/utils/helpers.js to TypeScript with strict mode

# Generate API docs from code
/agents/doc-generator Create OpenAPI spec from src/routes/*.ts

Pattern 5: Guardrail Agent

Use a pre-check agent before making changes.

# Check if change is safe
/agents/impact-analyzer What files and tests would be affected by renaming the User model to Account?

# Then proceed with the change
Rename the User model to Account across the entire codebase

---

Memory and State

Agent Memory Scope

Subagents do NOT have access to:

• The main conversation history
• Previous agent invocation results
• Other agents' outputs

Subagents DO have access to:

• All project files (subject to allowed-tools)
• CLAUDE.md files (loaded automatically)
• The current git state

Persisting Agent Output

Agent output appears in the main conversation. To preserve findings:

1. Ask the agent to write to a file: Include in custom-instructions: "Write your findings to a file."

2. Capture in conversation: The agent's output is visible in the main session's context.

3. Use a handoff document:

   /agents/analyzer Analyze the codebase and write a summary to .claude/analysis.md

Cross-Agent Communication

Agents cannot communicate directly. Use files as the communication channel:

# Agent A writes findings
/agents/security-reviewer Review code and write findings to /tmp/security-review.md

# Agent B reads findings
/agents/fix-planner Read /tmp/security-review.md and create a prioritized fix plan

---

Isolation Modes

Default Isolation

Agents run in the same project directory but with a fresh conversation context. They share the filesystem but not conversation state.

Worktree Isolation

For agents that modify files, consider using git worktrees for true isolation:

# Create isolated worktree
git worktree add .claude/worktrees/agent-work agent-branch

# Agent works in the worktree (configure in custom-instructions)

Permission Isolation

Use allowed-tools to create hard boundaries:

# Agent cannot modify anything
allowed-tools:
  - Read
  - Glob
  - Grep

# Agent can only modify test files
allowed-tools:
  - Read
  - Glob
  - Grep
  - Edit    # But custom-instructions say: "Only edit files in __tests__/"
  - Write   # But custom-instructions say: "Only write to __tests__/"

Note: allowed-tools enforces tool-level restrictions. For path-level restrictions, use custom-instructions (advisory, not enforced by the system).

---

Hooks Integration

Hooks can enhance agent workflows by running scripts before or after tool use.

Pre-Agent Validation Hook

Validate that an agent is appropriate for the current context:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Agent",
        "command": "/path/to/validate-agent-context.sh"
      }
    ]
  }
}

Post-Agent Logging Hook

Log all agent invocations for audit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Agent",
        "command": "echo \"$(date) Agent invoked: $CLAUDE_TOOL_INPUT\" >> .claude/agent-log.txt"
      }
    ]
  }
}

Auto-Format After Agent Writes

Ensure agent-generated code matches project style:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

---

Production Recipes

Recipe 1: Security Review Agent

---
name: security-reviewer
description: Reviews code for security vulnerabilities, secrets, and compliance issues
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff*)
  - Bash(git log*)
  - Bash(git show*)
custom-instructions: |
  You are a senior security engineer performing code review.

  Review Checklist:
  1. Hardcoded secrets (API keys, passwords, tokens, connection strings)
  2. Injection vulnerabilities (SQL, XSS, command, LDAP, template)
  3. Authentication flaws (broken auth, missing checks, weak tokens)
  4. Authorization gaps (IDOR, privilege escalation, missing RBAC)
  5. Cryptographic issues (weak algorithms, missing encryption, bad RNG)
  6. Information disclosure (verbose errors, stack traces, debug endpoints)
  7. Dependency vulnerabilities (known CVEs, outdated packages)

  Output a structured markdown report with severity levels.
  Always end with a risk score: CRITICAL / HIGH / MEDIUM / LOW / CLEAN.
---

Recipe 2: Test Writer Agent

---
name: test-writer
description: Generates comprehensive test suites with edge cases and mocking
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(npm test*)
  - Bash(npx jest*)
custom-instructions: |
  You write comprehensive test suites. For every module you test:

  1. Read the source code thoroughly
  2. Identify all public functions and methods
  3. Write tests covering:
     - Happy path for each function
     - Edge cases (null, empty, boundary values)
     - Error cases (invalid input, network failures)
     - Integration points (mocked external dependencies)
  4. Use the project's existing test framework and patterns
  5. Run the tests to verify they pass

  Naming: describe("ModuleName", () => { it("should verb when condition", ...) })
  Target: 90%+ line coverage for the tested module.
---

Recipe 3: Documentation Generator

---
name: doc-generator
description: Generates API documentation, code comments, and README files
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
custom-instructions: |
  You generate clear, accurate documentation from source code.

  Documentation Types:
  - API docs: Extract routes, parameters, response shapes from code
  - Code comments: Add JSDoc/docstrings to undocumented functions
  - README: Generate project overview from codebase analysis

  Rules:
  - Never invent features that don't exist in the code
  - Include realistic examples based on actual code paths
  - Use the project's existing documentation style
  - Mark any assumptions with [ASSUMPTION] tag
---

Recipe 4: Database Migration Agent

---
name: migration-helper
description: Generates database migration scripts and validates schema changes
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash(npx prisma*)
  - Bash(npm run migrate*)
custom-instructions: |
  You create safe database migration scripts.

  Safety Rules:
  1. NEVER drop columns or tables without explicit user confirmation
  2. Always create reversible migrations (up AND down)
  3. Add NOT NULL constraints in two steps (add nullable, backfill, alter)
  4. Create indexes CONCURRENTLY when possible
  5. Estimate data migration time for large tables

  Output: Migration file + summary of changes + rollback plan.
---

Recipe 5: Performance Profiler Agent

---
name: performance-profiler
description: Analyzes code for performance bottlenecks, N+1 queries, and memory leaks
model: claude-sonnet-4-20250514
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(git log*)
custom-instructions: |
  You are a performance engineering specialist.

  Analysis Areas:
  1. N+1 query patterns in ORM usage
  2. Missing database indexes for common queries
  3. Unbounded list operations (no pagination)
  4. Memory leaks (event listeners, closures, caches without eviction)
  5. Synchronous operations that should be async
  6. Missing caching opportunities
  7. Large payload responses without pagination

  Severity Levels:
  - P0: Will cause outage under load
  - P1: Significant performance degradation
  - P2: Noticeable slowdown
  - P3: Optimization opportunity

  Output a prioritized list with file:line references and fix suggestions.
---

---

When to Use Subagents vs Skills

Rules of thumb:

1. Knowledge + tools + templates -> Make it a skill. 2. Focused task + persona + restrictions -> Make it an agent. 3. Reads many files, want clean context -> Agent in fork mode. 4. Quick question using conversation history -> Skill or inline prompt. 5. Repeatable specialized review -> Agent (security-reviewer, test-runner). 6. Domain expertise for multiple workflows -> Skill (covers broader scope).

---

Last Updated: February 2026