A personal configuration for Claude Code — Anthropic's command-line tool for working with Claude. This repo customises how Claude behaves: what it knows, how it writes code, what it checks before pushing, and how it helps manage tasks.
Note
This setup is specific to one developer's workflow (and brain). It's shared as a working example, not a template to copy wholesale. If you're building your own, the process is what's transferable — the specifics should be yours.
For the full story on how and why this was built, see How to Use This Repo.
- What's In Here
- Quick Start
- Directory Guide
- How It All Fits Together
- Key Concepts
- Documentation Index
At a glance:
| Component | Count | What it does |
|---|---|---|
| Commands | 50+ | Slash commands you type (e.g. /git:commit:one:delta) |
| Skills | 12 | Knowledge packs that load automatically when relevant |
| Agents | 3 | Autonomous sub-processes for multi-step work |
| Hooks | 4 | Shell scripts that run on git events (push, commit) |
| Docs | 18 files | Guides, references, and workflow documentation |
If you've cloned this and want to understand what you're looking at:
- Read CLAUDE.md — this is the main behaviour file. It tells Claude how to write code, format commits, and communicate.
- Browse commands/README.md — the full index of slash commands, organised by category.
- Read How to Use This Repo — the comprehensive guide that explains every directory and the thinking behind each one.
If you're new to Claude Code customisation entirely, start with the How to Use This Repo guide. It assumes no prior knowledge of configuration beyond basic Claude Code usage.
The single most important file. This is loaded into every Claude Code session and defines:
- Technical profile — languages, frameworks, preferred tools
- Communication rules — British English, no sycophancy, direct answers
- Code conventions — tabs for indentation, naming patterns, TypeScript strict mode
- Git workflow — conventional commits, branch naming, PR structure
- Security defaults — no committed secrets, input validation, RLS
Think of it as "if I had to brief a new developer on how I work, what would I say?"
Commands are workflows you invoke explicitly by typing /command-name in Claude Code. There are 50+ of them across 8 categories:
- Codebase — analyse, critique, investigate a project
- Documentation — create READMEs, roadmaps, ADRs, work records
- Git — commits, PRs, branch management, rebasing
- Linear — issue creation, task management, dependency tracking
- Suggest — "what should I work on next?"
- Do — "just do this thing, minimally"
Each command filename ends with a model tier (delta, gamma, omega) that signals which Claude model it's designed for:
| Tier | Model | Best for |
|---|---|---|
delta |
Haiku | Fast, routine tasks |
gamma |
Sonnet | Balanced reasoning |
omega |
Opus | Complex analysis |
Full reference: commands/README.md
Skills are passive — you don't invoke them directly. Claude loads them automatically when it detects relevant keywords in your conversation. For example, mentioning "Svelte" triggers the svelte-ninja skill, which loads Svelte 5 patterns and SvelteKit conventions.
Current skills cover: Svelte, Git, API design, CSS/styling, debugging, databases (SQL + graph), testing, and a few others.
Only the skill's short description loads at session start (cheap on context). The full knowledge pack loads on demand.
Agents are sub-processes that Claude spawns to handle multi-step work independently:
| Agent | Purpose |
|---|---|
project-context-loader |
Rebuilds mental context when switching between projects |
implementation-planner |
Breaks vague feature requests into actionable plans |
roadmap-maintainer |
Keeps documentation and roadmaps in sync with code changes |
They run in their own context window, so they don't clutter your main conversation.
Shell scripts that run automatically on git events:
| Hook | Trigger | What it does |
|---|---|---|
pre-push.zsh |
Before push | Routes to other hooks; guards which repos run the full chain |
pre-push-tests.zsh |
Before push | Detects untested files; runs test suite |
pre-push-evidence.zsh |
Before push | Extracts apprenticeship portfolio evidence from commits |
post-commit-docs.zsh |
After commit | Checks if changed files need documentation updates |
These are specific to an apprenticeship workflow — they enforce habits that are easy to forget (running tests, tracking evidence, updating docs).
Guides, references, and workflow documentation. See the full index below.
You type something in Claude Code
│
├─ Keywords detected? ──→ Skill loads automatically
│
├─ You type /command? ──→ Command runs a defined workflow
│
├─ Command spawns agent? ──→ Agent works autonomously
│
└─ You push code? ──→ Hooks run checks and extraction
Meanwhile, CLAUDE.md shapes every response throughout.
The key insight: CLAUDE.md is always active, skills activate on context, commands activate on demand, and hooks activate on git events. Each layer has a different trigger and a different cost to your context window.
Context window cost — Everything Claude reads uses up its working memory. This setup is designed to be efficient: only descriptions load upfront, full content loads on demand. If you're building your own, this matters more than you'd think.
Model tiers — Not every task needs the most powerful model. Haiku is fast and cheap for routine work. Opus is thorough but slower and more expensive. The tier system makes this choice explicit.
Organic growth — None of this was planned upfront. Every command, skill, and hook traces back to a specific problem that came up during actual work. If you're building your own setup, start with one friction point and go from there.
For more on these ideas: How to Use This Repo
| File | Description |
|---|---|
| How to Use This Repo | Comprehensive guide to the entire setup — start here |
| File | Description |
|---|---|
| CLI Tools Quick Reference | Single-page cheat sheet for daily workflows |
| CLI Tools Usage Guide | Detailed guide for CLI tools |
| Doc Commands Reference | Quick reference for /doc/* commands |
| Git Branch Naming | Branch naming prefix guide |
| Git Configuration | Git setup documentation |
| Claude Config Analysis | Complete audit of the ~/.claude/ structure |
| iTerm2 Setup | iTerm2 terminal configuration |
| Terminal Setup | Terminal setup and configuration |
| File | Description |
|---|---|
| Debugging Patterns | Systematic debugging approaches |
| Documentation Strategy | Documentation creation and maintenance workflow |
| File | Description |
|---|---|
| Evidence Tracker | KSB evidence tracking for apprenticeship |
| Weekly Review Template | Structured weekly portfolio documentation |
| Dev Environment Audit | Systematic review of development environment |
| Audit Overview | Environment audit formatted for manager review |
| Audit Demo Script | 15-minute demo script for environment audit |
| File | Description |
|---|---|
| Iris Development Tracker | Development tasks for the Iris project |