The Customization Playbook

Introduction

The five layers of the customization harness — settings.json, hooks, skills, slash commands, and CLAUDE.md — each handle what the others cannot. Together, they form a coherent operating environment that makes Claude Code's behavior predictable, cost-efficient, and aligned with how you actually work.

This lesson is the assembly guide and the audit practice. First, how the layers fit together. Then, the monthly audit that keeps them healthy.

The Complete Harness Architecture

The layers are complementary, not redundant. Each handles a distinct concern:

• settings.json handles what Claude Code is mechanically allowed to do. It operates before Claude reads any context.
• Hooks handle event-driven enforcement. They intercept specific tool calls and apply deterministic rules.
• Skills handle complex workflows. They encapsulate domain knowledge and multi-step processes.
• Commands handle saved prompts. They version-control proven prompt patterns and share them with teams.
• CLAUDE.md handles semantic context. It tells Claude what the project is, how it works, and what conventions apply.

A rule that belongs in settings.json does not belong in CLAUDE.md, and vice versa. Conflating the layers produces a harness where mechanical rules fight semantic guidance and neither wins consistently.

The Assembly Sequence

Build the harness in this order — each layer depends on the previous:

Step 1 — Settings foundation Start with .claude/settings.json. Add a deny list for destructive operations (force push, rm -rf, sudo). Add the most commonly trusted Bash commands to the allowlist. Set acceptEdits as the default mode for development. This establishes the safety floor before you add any automation.

Step 2 — CLAUDE.md hierarchy Build the CLAUDE.md files: global (~/.claude/CLAUDE.md) for universal rules, project (repo/CLAUDE.md) for project context. Keep global Tier 1 under 80 lines. Import Tier 2 content with @ syntax. The CLAUDE.md hierarchy is the context Claude reads; every extra line has a token cost.

Step 3 — Hooks Add hooks for the rules that need to be mechanically enforced. Start with three: anti-main-branch guard (PreToolUse), secret scan (PreToolUse), and test gate (Stop). Test each in isolation before wiring to settings.json.

Step 4 — Commands Add project commands for workflows your team repeats. PR description, deploy check, component generation. Personal commands for your individual habits. Aim for 5-10 commands that cover the most common repetitive prompts.

Step 5 — Skills Add skills for complex, multi-step workflows. Build each using the TDD approach: failure scenario first, minimal skill, rationalization counters. Aim for coverage of your most important recurring workflows before building exotic ones.

The Monthly Audit Lab

The audit lab is the maintenance practice that keeps the harness calibrated. Without it, the harness drifts from the work — skills get stale, hooks stop being relevant, the allowlist grows too permissive.

The audit has four phases:

Settings audit — run /cc-audit first. It surfaces missing guards, duplicate permissions, and misconfigured model routing. Review the allowlist: are any entries broader than necessary? Review the denylist: did any pattern fire correctly this month, and are there patterns that should be added?

Hook audit — test each hook manually. Knox's test: for each PreToolUse hook, construct a sample input that should block and verify exit 2. For each Stop hook, introduce a failing state and verify exit 2. A hook that "seems to work" but has never been tested with a failing case is untested code.

Skills audit — check fire rates. Skills that fired 0 times in 30 days are archived. Skills that fired frequently get hardened — review their verification gates, check for trigger collisions with other skills, update WHEN NOT TO USE if the library has grown around them.

Commands audit — review project commands for currency. A command written six months ago may reference outdated file paths or stale conventions. Two minutes of review per command keeps the library current.

The Compound Effect

The harness compounds over time because each element improves through use:

• Skills that fire get hardened through real-world failures
• Hooks that block legitimate operations get made more precise
• Allowlist entries that prove trustworthy stay; entries that surprise you get moved to prompts
• CLAUDE.md rules that Claude consistently applies get promoted; rules that get violated go to hooks

A harness you've run for a year is qualitatively more reliable than one you've run for a week — not because more time has passed, but because more failures have been encountered and addressed. The compound learning loop in lessons.md captures these failures; the harness improvements encode them as mechanical guarantees.

Applying to Your Own Setup

The immediate next step after this track is not to build 60 skills — it's to build one. Take the workflow you repeat most often that you don't currently have a skill for. Write the failure scenario. Build the minimal skill. Verify the gate.

Then build one hook. The anti-main-branch guard is the highest-value hook for almost any developer. It takes 10 minutes to write, tests in five minutes, and prevents an error class that is permanently annoying.

Then run /cc-audit on what you have. Let the diagnostic tool tell you what the harness is missing rather than guessing from first principles.

The harness is not a one-time configuration — it's an ongoing engineering discipline, like the codebase it serves.

What's Next

You've completed the Skills, Hooks & Slash Commands track. The prerequisite track — Context Engineering — established the information architecture. This track established the enforcement and automation architecture. The next track in the batch, Production MCP Servers, covers extending Claude's reach with custom tools — the layer that sits beneath hooks and gives them real capabilities to invoke.