Claude Code extensibility — agents, commands, hooks, skills, rules, and configuration. Use when creating, configuring, or troubleshooting Claude Code components, or when agent.md, /command, hooks.json, SKILL.md, .claude/rules, settings.json, MCP server, PreToolUse, or create agent/command/hook are mentioned.
Claude Code extensibility — agents, commands, hooks, skills, rules, and configuration. Use when creating, configuring, or troubleshooting Claude Code components, or when agent.md, /command, hooks.json, SKILL.md, .claude/rules, settings.json, MCP server, PreToolUse, or create agent/command/hook are mentioned.
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
---
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
Event handlers that automate workflows, validate operations, and respond to Claude Code events.
Hook Types
Type
Best For
Response Format
Default Timeout
command
Deterministic checks, external tools
Exit codes + JSON
600s
prompt
Complex reasoning, context-aware validation
{"ok": bool, "reason": "..."}
30s
agent
Multi-step verification requiring tool access
{"ok": bool, "reason": "..."} (up to 50 turns)
60s
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.
Block operation (PreToolUse only), stderr shown to Claude
Other
Warning, stderr shown to user, continues
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-skillhooks:PreToolUse:-matcher:"Write|Edit"hooks:-type:promptprompt:"Validate this write operation..."Stop:# Converted to SubagentStop at runtime-hooks:-type:commandcommand:"./scripts/on-complete.sh"---
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
Context
Preprocessed
Safe to use literal !?
Command files (commands/*.md)
Yes
Yes — intentional
SKILL.md
Yes
No — use <bang> instead
References, EXAMPLES.md
No
Yes — great for copy-paste demos
Rules, CLAUDE.md, agents
No
Yes
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 -->
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.
{"$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"}
