Claude Code Extensibility

Create and configure the six Claude Code extension points: agents, commands, hooks, skills, rules, and configuration.

Component Map

Scope Hierarchy

Routing

Agents

Specialized subagents with focused expertise, invoked via the Task tool.

Frontmatter

---
name: security-reviewer       # Required: kebab-case, matches filename
description: |                 # Required: triggers + examples
  Use this agent for security vulnerability detection.
  Triggers on security audits, OWASP, injection, XSS.

  <example>
  Context: User wants security review.
  user: "Review auth code for vulnerabilities"
  assistant: "I'll use the security-reviewer agent."
  </example>
model: inherit                 # Optional: inherit(default)|haiku|sonnet|opus
tools: Glob, Grep, Read       # Optional: comma-separated (default: inherit all)
disallowedTools: Write, Edit   # Optional: deny specific tools
skills: tdd-fieldguide, debugging  # Optional: auto-load skills (NOT inherited)
maxTurns: 50                   # Optional: max agentic turns
memory: user                   # Optional: user|project|local — persistent memory
hooks:                         # Optional: lifecycle hooks scoped to this agent
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
---

See agents/frontmatter.md for complete schema.

Archetypes

See agents/types.md for details.

Model Selection

Tool Configuration

Baseline (always include when restricting):

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

Only restrict tools when there's a specific safety reason. See agents/tools.md.

Agent Body Structure

# Agent Name

You are a [role] specializing in [expertise].

## Process

### Step 1: [Stage]
- Action items

## Output Format

Structured output spec.

## Constraints

**Always:** Required behaviors
**Never:** Prohibited actions

Validation Checklist

• name matches filename (kebab-case, 1-3 words)
• description has WHAT, WHEN, triggers, 2-3 examples
• tools uses comma-separated valid names (case-sensitive)
• Body has clear role, process, output format, constraints

References

Commands

Custom slash commands — reusable prompts invoked by users.

Frontmatter

---
description: Deploy to environment with validation   # Required
argument-hint: <environment> [--skip-tests]          # Shown in autocomplete
allowed-tools: Bash(*), Read                          # Restrict tool access
model: claude-3-5-haiku-20241022                     # Override model
---

See commands/frontmatter.md for complete schema.

Core Features

Quick Example

---
description: Fix a specific GitHub issue
argument-hint: <issue-number>
---

Fix issue #$1 following our coding standards.
Review the issue, implement a fix, add tests, and create a commit.

Usage: /fix-issue 123

Argument Patterns

• Positional: $1, $2, $3 — /compare old.ts new.ts
• All arguments: $ARGUMENTS — /fix memory leak in auth
• With file refs: @$1 — /analyze src/main.ts

See commands/arguments.md for advanced patterns.

Scopes

Subdirectories create namespaces: commands/frontend/component.md → /component.

Validation Checklist

• Filename is kebab-case .md (verb-noun pattern preferred)
• description is action-oriented, under 80 chars
• argument-hint uses <required> and [optional] syntax
• allowed-tools uses correct case-sensitive names
• Bash commands tested in terminal first

References

Hooks

Event handlers that automate workflows, validate operations, and respond to Claude Code events.

Hook Types

Prompt hooks: Send prompt + hook input to a Claude model (Haiku by default, override with model field). Return {"ok": true} to proceed or {"ok": false, "reason": "..."} to block.

Agent hooks: Spawn a subagent with tool access (allowedTools) for multi-step verification. Same ok/reason response format as prompt hooks.

Events

See hooks/hook-types.md for detailed per-event documentation.

Configuration Format

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit(*.ts|*.tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "biome check --write \"$file\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Matchers

{"matcher": "Write"}                    // Exact match
{"matcher": "Edit|Write"}               // Multiple tools (OR)
{"matcher": "*"}                        // All tools
{"matcher": "Write(*.py)"}              // File pattern
{"matcher": "Write|Edit(*.ts|*.tsx)"}   // Multiple + pattern
{"matcher": "mcp__memory__.*"}          // MCP server tools

Lifecycle event matchers:

• SessionStart: startup, resume, clear, compact
• SessionEnd: clear, logout, prompt_input_exit, bypass_permissions_disabled, other
• Notification: permission_prompt, idle_prompt, auth_success, elicitation_dialog
• SubagentStart/Stop: Agent type name (e.g., Explore, Plan, db-agent)
• PreCompact: manual, auto

See hooks/matchers.md for advanced patterns.

Exit Codes

JSON Output (Advanced)

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Context for Claude",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Explanation",
    "updatedInput": {"modified": "field"}
  }
}

Execution Model

All matching hooks run in parallel (not sequentially). Identical handlers are automatically deduplicated. Design hooks to be independent — they cannot see each other's output.

Hot-swap: Hooks added via /hooks menu take effect immediately. Manual edits to settings files require a session restart or /hooks menu visit.

Stop hooks: Fire whenever Claude finishes responding, not only at task completion. Do NOT fire on user interrupts. To prevent infinite loops, check stop_hook_active in the input JSON and exit early if true.

Component-Scoped Hooks

Skills, agents, and commands can define hooks in frontmatter. All hook events are supported. Stop hooks in agent/skill frontmatter are automatically converted to SubagentStop events at runtime.

---
name: my-skill
hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: prompt
          prompt: "Validate this write operation..."
  Stop:  # Converted to SubagentStop at runtime
    - hooks:
        - type: command
          command: "./scripts/on-complete.sh"
---

Environment Variables

Validation Checklist

• Hook scripts are executable (chmod +x)
• Matchers use correct case-sensitive tool names
• Timeouts set (default: 600s command, 30s prompt, 60s agent; max: 10 minutes)
• Scripts use set -euo pipefail and quote variables
• Plugin hooks use ${CLAUDE_PLUGIN_ROOT} for paths

References

Skills (Claude-Specific)

Claude Code extends the base Agent Skills specification with additional features. For the cross-platform spec, load skillcraft.

Frontmatter Extensions

Tool Restrictions

# Space-separated list
allowed-tools: Read Grep Glob

# With Bash patterns
allowed-tools: Read Write Bash(git *) Bash(npm run *)

# MCP tools (double underscore format)
allowed-tools: Read mcp__linear__create_issue

Tool names are case-sensitive. See skills/integration.md for patterns.

String Substitutions

Context Modes

• inherit (default): Runs in main conversation with full history access
• fork: Runs in isolated subagent context; prevents context pollution

context: fork
agent: analyst
model: haiku

See skills/context-modes.md for patterns.

References

Preprocessing

Claude Code preprocesses <bang>`command` syntax — executing shell commands and injecting output before content reaches Claude. This powers live context in commands (git state, PR details, environment info).

Critical: Preprocessing runs in both command files AND SKILL.md files, including inside markdown code fences. There is no escape mechanism.

Where preprocessing runs

Writing SKILL.md files

When documenting or referencing the preprocessing syntax in a SKILL.md, use <bang> as a stand-in for !. Agents interpret <bang> as !.

Add an HTML comment explaining the convention:

<!-- <bang> = exclamation mark; used as stand-in to avoid triggering preprocessing -->

Then use <bang> for any inline references:

• <bang>`git status` — injects current git status
• <bang>`gh pr view --json title` — injects PR details

Move real copy-paste examples with literal ! to reference files — those are not preprocessed.

Writing reference files

Reference files (references/, EXAMPLES.md) are not preprocessed. Use literal ! freely — these serve as copy-paste sources for command authors:

See commands/bash-execution.md for the full reference with real ! syntax.

Intentional preprocessing in skills

Skills that genuinely run commands at load time should declare it in frontmatter:

metadata:
  preprocess: true

Validation

Run /skillcheck to scan SKILL.md files for unintentional preprocessing patterns. The linter respects metadata.preprocess: true and skips intentional uses.

See skills/preprocessing-safety.md for detailed examples, common mistakes, and the full convention.

Rules

Reusable convention files in .claude/rules/ for project patterns.

Rules vs CLAUDE.md

CLAUDE.md: One-off instructions, project commands, key file locations. rules/: Formatting conventions, architecture patterns, workflow guidelines.

File Conventions

• UPPERCASE.md — All caps with .md extension
• Topic-focused — One concern per file
• Kebab-case for multi-word: API-PATTERNS.md, CODE-REVIEW.md

Path-Specific Rules

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# API Development Rules

Referencing Rules

Rules are NOT auto-loaded. Reference from CLAUDE.md:

# CLAUDE.md
Follow `.claude/rules/FORMATTING.md` for all code conventions.

Or use @ syntax: @./project-specific/FORMATTING.md

See rules.md for detailed patterns and anti-patterns.

Configuration

File Locations

Precedence (highest first): Managed > CLI args > Local > Project > User.

MCP Server Setup

Project MCP (.mcp.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    }
  }
}

Personal MCP (~/.claude.json):

{
  "mcp_servers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Key Settings

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  },
  "hooks": {},
  "enabledPlugins": {"plugin@marketplace": true},
  "model": "claude-sonnet-4-5-20250929"
}

See config/mcp-patterns.md, config/workflows.md, and config/troubleshooting.md for details.

Testing & Debugging

# Debug mode — shows skill/agent/hook loading details
claude --debug

# Force reload after changes
/clear

# Test hook manually
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.ts"}}' | ./hooks/my-hook.sh

# Verify commands appear
/help

External Resources

• Claude Code Docs — Hooks
• Claude Code Docs — Memory
• Claude Code Docs — Settings
• Hooks Guide
• Agent Skills Spec