Customization
Reshaping Claude Code to your repo and team — custom slash commands, sub-agents, hooks, the Agent SDK, status line, and permission rules.
Out of the box Claude Code is opinionated but generic. The customization surface is where you make it your team's tool: shared slash commands for the workflows you do every day, sub-agents for the specialised tasks that show up repeatedly, hooks for the safety and audit rules you can't afford to forget, the Agent SDK for the cases where the CLI isn't the right shape.
The principle here is the same as for any developer tooling: don't customise prematurely. Use the defaults until the friction is observable, then customise the smallest piece that removes it. A team that writes one shared `/release-notes` slash command beats a team that built a full Agent SDK pipeline that nobody understands.
Key concepts
- Customise the friction, not the framework — start from a real pain point, not from a tour of features
- Slash commands are the cheapest customisation — markdown file, immediate value
- Sub-agents trade configuration for isolation — use them when you want a different system prompt or tool allowlist
- Hooks are observers and gatekeepers — keep them fast, deterministic, and exit-coded
- The Agent SDK is for when the CLI loop doesn't fit — programmatic, headless, deeply integrated cases
Reference template
// Customisation surface, in order of cost
1. CLAUDE.md edits (just write the instruction down)
2. Slash command (markdown file in .claude/commands)
3. Permission rule (allowlist or denylist a Bash pattern)
4. PreToolUse / PostToolUse (shell hook on tool events)
5. UserPromptSubmit hook (shell hook on user input)
6. Custom sub-agent (markdown file with system prompt + tools)
7. Custom status line (script that emits a one-line summary)
8. Agent SDK program (full programmatic agent, headless)Adapt to your problem; the structure is the load-bearing part.
Common pitfalls
- Customising before observing — building a hook for a problem you've never actually hit
- Slow hooks — a 500 ms hook on every tool call makes the session feel broken
- Permission allowlists that drift — added once, never reviewed, eventually waving through risky commands
- Sub-agents with overlapping scope — two custom agents that both kind of do the same thing become a pick-one-at-random anti-pattern
Related topics
Items (8)
- Writing Custom Slash Commands
Authoring a slash command from a markdown file. Argument handling, model selection, and team-shared command libraries.
Feature Intermediate - Custom Sub-Agents
Defining a sub-agent with a tool allowlist, a system prompt, and an invocation pattern. When a sub-agent beats a slash command.
Feature Intermediate - PreToolUse and PostToolUse Hooks
Intercepting and reacting to tool calls. Common patterns: linting after edits, logging Bash commands, blocking dangerous operations.
Feature Intermediate - UserPromptSubmit Hooks
Hooks that fire when the user submits a prompt. Use cases: redaction, secret-scrubbing, injecting context, audit logging.
Feature Intermediate - Building a Security Hook
End-to-end recipe for a hook that blocks dangerous commands and writes an audit log. The threat model and the test plan.
Workflow Advanced - The Claude Agent SDK
Programmatic Claude agents from Python or TypeScript. When the SDK beats the CLI, and how it shares conventions with Claude Code.
Feature Advanced - Custom Status Line
Authoring a status-line script. Reading session metadata, formatting output, and the refresh cadence.
Feature Intermediate - Permission Rules and Allowlists
Auto-approving safe Bash commands, denying risky ones, and the project-scoped allowlist file.
Feature Intermediate