Claude Code Infrastructure Showcase
A curated reference library of production-tested Claude Code infrastructure.
Born from 6 months of real-world use managing a complex TypeScript microservices project, this showcase provides the patterns and systems that solved the "skills don't activate automatically" problem and scaled Claude Code for enterprise development.
This is NOT a working application - it's a reference library. Copy what you need into your own projects.
New to Claude Code infrastructure? Three terms cover 90% of this README:
- Skill - a markdown guide (patterns, conventions, examples) that Claude loads when relevant
- Hook - a script Claude Code runs automatically at key moments (every prompt, before/after edits)
- skill-rules.json - the config that tells hooks which prompts/files should trigger which skills
Full explanations in Key Concepts.
What's Inside
Production-tested infrastructure for:
- ✅ Auto-activating skills via hooks
- ✅ Modular skill pattern (500-line rule with progressive disclosure)
- ✅ Specialized agents for complex tasks
- ✅ Dev docs system that survives context resets
- ✅ Comprehensive examples using generic blog domain
Time investment to build: 6 months of iteration
Time to integrate into your project: 15-30 minutes
Quick Start
Requirements
- Node.js 18+ (20+ recommended) and npm
- macOS, Linux, or WSL2 - the hooks are bash scripts and won't run in plain cmd/PowerShell (Windows users: use WSL2)
- jq - only needed if you enable the optional Stop hooks
Note: the first npx tsx run may ask to install tsx - say yes.
Option A: Setup Wizard (Recommended)
The wizard copies everything, installs dependencies, and configures your mode:
# 1. Clone this repo
git clone https://github.com/diet103/claude-code-infrastructure-showcase.git
# 2. Run the setup wizard, pointing to YOUR project
cd claude-code-infrastructure-showcase
npx tsx setup.ts ~/my-project
The wizard will:
- Copy
.claude/ (hooks, skills, agents, commands) into your project
- Detect your tech stack (React, Express, Prisma, etc.)
- Ask: Classic (regex-only) or AI-Enhanced mode?
- If AI: which provider? Validates API key availability
- Install hook dependencies and make scripts executable
- Verify its own work - 8 health checks before it declares success
Scripting it, or letting Claude Code run it? Add --yes:
npx tsx setup.ts ~/my-project --yes (see --help for all flags)
Option B: Manual (3 Commands)
# 1. Clone this repo
git clone https://github.com/diet103/claude-code-infrastructure-showcase.git
# 2. Copy .claude/ into YOUR project
cp -r claude-code-infrastructure-showcase/.claude ~/my-project/.claude
# 3. Install hook dependencies
cd ~/my-project/.claude/hooks && npm install && chmod +x *.sh
Option C: Let Claude Code Do It (Easiest)
Don't want to touch the terminal? Open Claude Code in your project and paste this:
Clone https://github.com/diet103/claude-code-infrastructure-showcase to a temp
directory and read its CLAUDE_INTEGRATION_GUIDE.md. Then install the
infrastructure into this project by running the setup wizard non-interactively
(npx tsx setup.ts <this project's absolute path> --yes). When it finishes, show
me the verification results and fix anything that failed.
Claude clones the repo, runs the wizard (which verifies its own work), and reports back.
Verify It Works (30 Seconds)
Any time, from your project root:
bash .claude/scripts/verify-setup.sh
Eight checks - Node version, hook registration, executable bits, dependencies, config validity, even firing a test prompt through the real activation hook - each with an exact fix command if it fails. Or ask Claude to run /verify-setup and it fixes failures itself.
Enable AI-Powered Classification (Optional)
No API key needed by default. The standard mode uses regex/keyword matching - free, offline, zero API calls. AI classification is an optional upgrade that matches your intent instead of your keywords.
To enable it (Gemini's free tier easily covers this use case):
# 1. Get a free Gemini API key: https://aistudio.google.com/apikey
# 2. Put it in the hooks .env file:
cp .claude/hooks/.env.example .claude/hooks/.env
# then open .claude/hooks/.env and uncomment: GEMINI_API_KEY=your-key-here
# (add .env to your project's .gitignore so you never commit it)
# 3. Enable AI mode - edit .claude/skills/skill-rules.json and change:
# "skill_activation_mode": "disabled" → "skill_activation_mode": "fallback"
Prefer environment variables? export GEMINI_API_KEY=your-key in ~/.bashrc works too - the hooks read both. (fallback mode always degrades gracefully: no key, dead network, slow provider - you get regex matching, never a broken prompt.)
Upgrading an Existing Install
Re-running the wizard on a project that already has .claude/ deliberately copies no files - it only re-chmods hooks, updates skill-rules.json settings, and reinstalls dependencies. It will never clobber your customized skill-rules.json or skills.
To pick up new files from a newer version of this repo:
- Copy specific pieces from a fresh clone (e.g.
cp -r showcase/.claude/scripts ~/my-project/.claude/), or
- If your
.claude/ is committed to git: delete it, re-run the wizard, then git diff to port your customizations back.
Editor Setup (Optional)
The repo includes a NeoVim configuration optimized for Claude Code's prompt editing mode (Ctrl+G):
- Relative line numbers for easy jumping (
5j = down 5 lines)
- Word-boundary wrapping for long prompts
- System clipboard integration (yank = Cmd+C)
- Space+w to save and submit, Space+q to cancel
The setup wizard can install this automatically, or manually:
mkdir -p ~/.config/nvim
cp editor-config/init.lua ~/.config/nvim/init.lua
cp editor-config/vimrc ~/.vimrc
echo 'export EDITOR=nvim' >> ~/.bashrc && source ~/.bashrc
See editor-config/README.md for full keybinding reference.
What You'll See
After setup, when you type "create a React component" in Claude Code:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⛔ MANDATORY SKILL ACTIVATION REQUIRED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You MUST activate these skills BEFORE any action:
→ frontend-dev-guidelines
⚠️ EDITS WILL BE BLOCKED until mandatory skills are activated.
Your FIRST action must be: Skill tool calls.
[via regex]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skills auto-activate based on your prompts. No more forgetting to load them.
Pick Your Path
🤖 Using Claude Code to Integrate?
Claude: Read CLAUDE_INTEGRATION_GUIDE.md for step-by-step integration instructions tailored for AI-assisted setup.
📚 Browse the Skills Catalog
Available skills (full catalog):
- backend-dev-guidelines - Node.js/Express/TypeScript patterns
- frontend-dev-guidelines - React/TypeScript/MUI v7 patterns
- skill-developer - Meta-skill for creating skills
- error-tracking - Sentry integration patterns
🤖 Specialized Agents
8 production-tested agents for complex tasks (full list):
- Code architecture review, refactoring, documentation, error debugging, and more
What Makes This Different?
The Auto-Activation Breakthrough
Problem: Claude Code skills just sit there. You have to remember to use them.
Solution: UserPromptSubmit hook that:
- Analyzes your prompts
- Checks file context
- Automatically suggests relevant skills
- Works via
skill-rules.json configuration
Result: Skills activate when you need them, not when you remember them.
AI-Powered Classification (NEW in v2.0)
Choose your activation mode:
| Mode |
How It Works |
Cost |
Offline |
disabled (default) |
Regex/keyword matching only |
Free |
Yes |
fallback |
AI first, regex on failure |
Low |
Graceful |
ai-only |
Pure AI classification |
Low |
No |
Supported AI providers:
| Provider |
Model |
API Key |
Free Tier |
| Gemini |
gemini-3-flash-preview |
GEMINI_API_KEY |
Yes (generous) |
| OpenAI |
gpt-4o-mini |
OPENAI_API_KEY |
No |
| Anthropic |
claude-haiku-4-5 |
ANTHROPIC_API_KEY |
No |
| Ollama |
llama3.2 (local) |
None needed |
Yes (local) |
Auto-detection tries providers in order: Gemini > OpenAI > Anthropic > Ollama. Override with SKILL_AI_PROVIDER=gemini.
Conservativeness levels control suggestion aggressiveness:
strict - Minimize false positives. Only suggest when clear intent.balanced (default) - Standard behavior.aggressive - Catch everything. Suggest liberally.
Production-Tested Patterns
These aren't theoretical examples - they're extracted from:
- ✅ 6 microservices in production
- ✅ 50,000+ lines of TypeScript
- ✅ React frontend with complex data grids
- ✅ Sophisticated workflow engine
- ✅ 6 months of daily Claude Code use
The patterns work because they solved real problems.
Modular Skills (500-Line Rule)
Large skills hit context limits. The solution:
skill-name/
SKILL.md # <500 lines, high-level guide
resources/
topic-1.md # aim for <500 lines each
topic-2.md
topic-3.md
Progressive disclosure: Claude loads main skill first, loads resources only when needed.
Repository Structure
.claude/
├── skills/ # 4 production skills
│ ├── backend-dev-guidelines/ (11 resource files)
│ ├── frontend-dev-guidelines/ (10 resource files)
│ ├── skill-developer/ (6 resource files)
│ ├── error-tracking/
│ └── skill-rules.json # Skill activation configuration
├── hooks/ # 9 hooks for automation
│ ├── skill-activation-prompt.* (ESSENTIAL)
│ ├── skill-verification-guard.* (ESSENTIAL, v2.0)
│ ├── skill-activation-tracker.* (ESSENTIAL, v2.0)
│ ├── post-tool-use-tracker.sh (ESSENTIAL)
│ ├── session-doc-updater.* (optional, installed by default)
│ ├── error-handling-reminder.* (optional)
│ ├── stop-build-check-enhanced.sh (optional)
│ ├── tsc-check.sh (optional, needs customization)
│ └── trigger-build-resolver.sh (optional)
├── agents/ # 8 specialized agents
│ ├── code-architecture-reviewer.md
│ ├── refactor-planner.md
│ ├── frontend-error-fixer.md
│ └── ... 5 more
├── commands/ # 4 slash commands
│ ├── dev-docs.md
│ ├── verify-setup.md
│ └── ...
└── scripts/
└── verify-setup.sh # One-command health check
dev/
└── active/ # Dev docs pattern examples
└── showcase-ai-upgrade/
Component Catalog
🎨 Skills (4)
All skills follow the modular pattern - main file + resource files for progressive disclosure.
👉 How to integrate skills →
🪝 Hooks (9)
| Hook |
Type |
Essential? |
Customization |
| skill-activation-prompt |
UserPromptSubmit |
✅ YES |
✅ None needed |
| skill-verification-guard |
PreToolUse |
✅ YES (v2.0) |
✅ None needed |
| skill-activation-tracker |
PostToolUse (Skill) |
✅ YES (v2.0) |
✅ None needed |
| post-tool-use-tracker |
PostToolUse (Edit) |
✅ YES |
✅ None needed |
| tsc-check |
Stop |
⚠️ Optional |
⚠️ Heavy - monorepo only |
| trigger-build-resolver |
Stop |
⚠️ Optional |
⚠️ Heavy - monorepo only |
| error-handling-reminder |
Stop |
⚠️ Optional |
⚠️ Moderate |
| stop-build-check-enhanced |
Stop |
⚠️ Optional |
⚠️ Moderate |
| session-doc-updater |
Stop |
⚠️ Optional (installed by default) |
✅ None - no-ops until session indexing is configured (CONFIG.md) |
Hook types: UserPromptSubmit fires on every prompt you send; PreToolUse fires before each Edit/Write; PostToolUse fires after; Stop fires when Claude finishes responding.
New in v2.0:
- skill-verification-guard - PreToolUse hook that analyzes code being written and enforces mandatory skill activation (two-try blocking model)
- skill-activation-tracker - Clears skills from mandatory_pending after they're activated via the Skill tool
Start with the essential hooks - they enable skill auto-activation and work out of the box.
👉 Hook setup guide →
🤖 Agents (8)
Standalone - just copy and use!
| Agent |
Purpose |
| code-architecture-reviewer |
Review code for architectural consistency |
| code-refactor-master |
Plan and execute refactoring |
| documentation-architect |
Generate comprehensive documentation |
| frontend-error-fixer |
Debug frontend errors |
| plan-reviewer |
Review development plans |
| refactor-planner |
Create refactoring strategies |
| web-research-specialist |
Research technical issues online |
| auto-error-resolver |
Auto-fix TypeScript errors |
👉 How agents work →
💬 Slash Commands (4)
| Command |
Purpose |
| /dev-docs |
Create structured dev documentation |
| /dev-docs-update |
Update docs before context reset |
| /verify-setup |
Run the infrastructure health check and fix failures |
| /route-research-for-testing |
Research route patterns for testing |
Key Concepts
Hooks + skill-rules.json = Auto-Activation
The system:
- skill-activation-prompt hook runs on every user prompt
- Checks skill-rules.json for trigger patterns
- Suggests relevant skills automatically
- Skills load only when needed
This solves the #1 problem with Claude Code skills: they don't activate on their own.
Progressive Disclosure (500-Line Rule)
Problem: Large skills hit context limits
Solution: Modular structure
- Main SKILL.md <500 lines (overview + navigation)
- Resource files aim for <500 lines each (full disclosure: a few deep-dives currently run 500-871 lines - kept whole for coherence, splitting them is on the list)
- Claude loads incrementally as needed
Example: backend-dev-guidelines has 11 resource files covering routing, controllers, services, repositories, testing, etc.
Dev Docs Pattern
Problem: Context resets lose project context
Solution: Three-file structure
[task]-plan.md - Strategic plan[task]-context.md - Key decisions and files[task]-tasks.md - Checklist format
Works with: /dev-docs slash command to generate these automatically
Works with Codex Too (Cross-Agent Support)
Codex CLI's hooks system uses the same events, stdin schema, and exit-code semantics as Claude Code, and skills follow the cross-agent Agent Skills standard. This repo ships both wired up — one canonical codebase, zero forked scripts:
.agents/skills/ — a synced mirror of .claude/skills/ in the standard location Codex (and 30+ other tools) reads natively. Keep it fresh with .claude/scripts/sync-agent-skills.sh; verify-setup warns on drift..codex/hooks.json — registers the same four lifecycle hooks for Codex..codex/hooks/_codex-adapter.sh — a thin shim that closes the two real gaps: it sets CLAUDE_PROJECT_DIR (Codex runs hooks at the session cwd) and translates Codex's native apply_patch tool into per-file events the verification guard understands. Everything else passes through untouched to .claude/hooks/.
Setup:
- Install Codex natively in your shell environment (
npm i -g @openai/codex). If you're on WSL, don't use a Windows-side install through the interop layer — hooks would run as Windows processes with UNC paths.
- Launch
codex from the repo root. On first run Codex asks you to trust this project's hooks — accept (trust is hash-persisted in ~/.codex/config.toml, and re-prompted if the hook config changes).
- That's it. Prompt-time skill suggestions, edit blocking for
block-enforced skills (two-try model included), file tracking, session-state, and the activation telemetry (state/metrics.jsonl) all run identically under both agents — same state directory, same metrics, one skill-rules.json.
Known parity gap: Codex has no Skill tool event, so the PostToolUse tracker that clears mandatory_pending early never fires there; the two-try model bounds the cost at one advisory block per skill per session. .codex/agents/ is an experimental subagent port and not wired into any of this.
⚠️ Important: What Won't Work As-Is
settings.json
The included settings.json works out of the box for the essential hooks (UserPromptSubmit, PreToolUse, PostToolUse). If you add optional Stop hooks (tsc-check, build-check), those need customization for your project structure. Note that the shipped settings.json contains hook registrations only - permissions are yours to manage (e.g. via /permissions in Claude Code).
Blog Domain Examples
Skills use generic blog examples (Post/Comment/User):
- These are teaching examples, not requirements
- Patterns work for any domain (e-commerce, SaaS, etc.)
- Adapt the patterns to your business logic
Hook Directory Structures
Some hooks expect specific structures:
tsc-check.sh expects service directories- Customize based on YOUR project layout
Integration Workflow
Recommended approach:
Option A: Setup Wizard (Fastest)
npx tsx setup.ts ~/my-project # interactive
npx tsx setup.ts ~/my-project --yes # non-interactive (what Claude Code uses)
The wizard handles everything: tech detection, mode selection, provider config, dependency install, and a self-verification pass at the end.
Option B: Manual Setup
Phase 1: Skill Activation (15 min)
- Copy all essential hooks (skill-activation-prompt, skill-verification-guard, skill-activation-tracker, post-tool-use-tracker)
- Update settings.json with hook registrations
- Install hook dependencies:
cd .claude/hooks && npm install
- Make shell scripts executable:
chmod +x .claude/hooks/*.sh
Phase 2: Add First Skill (10 min)
- Pick ONE relevant skill
- Copy skill directory
- Create/update skill-rules.json
- Customize path patterns
Phase 3: Enable AI (Optional, 5 min)
- Edit `.clau
A curated reference library of production-tested Claude Code infrastructure — hooks, skills and agents extracted from 6 months of daily use on a real TypeScript microservices project. It fixes the problem that skills do not activate automatically and shows patterns that scale Claude Code for enterprise development.