Skip to content

diet103/claude-code-infrastructure-showcase

BranchesTags

Repository files navigation

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)

Skill Lines Purpose Best For
skill-developer 426 Creating and managing skills Meta-development
backend-dev-guidelines 304 Express/Prisma/Sentry patterns Backend APIs
frontend-dev-guidelines 398 React/MUI v7/TypeScript React frontends
error-tracking ~250 Sentry integration Error monitoring

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:

  1. skill-activation-prompt hook runs on every user prompt
  2. Checks skill-rules.json for trigger patterns
  3. Suggests relevant skills automatically
  4. 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:

  1. 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.
  2. 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).
  3. 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)

  1. Copy all essential hooks (skill-activation-prompt, skill-verification-guard, skill-activation-tracker, post-tool-use-tracker)
  2. Update settings.json with hook registrations
  3. Install hook dependencies: cd .claude/hooks && npm install
  4. Make shell scripts executable: chmod +x .claude/hooks/*.sh

Phase 2: Add First Skill (10 min)

  1. Pick ONE relevant skill
  2. Copy skill directory
  3. Create/update skill-rules.json
  4. Customize path patterns

Phase 3: Enable AI (Optional, 5 min)

  1. Edit .claude/skills/skill-rules.json
  2. Change "skill_activation_mode" to "fallback"
  3. Set your API key: export GEMINI_API_KEY=your-key in ~/.bashrc
  4. Restart Claude Code

Phase 4: Test & Iterate (5 min)

  1. Edit a file - skill should activate
  2. Ask a question - skill should be suggested
  3. Add more skills as needed

Phase 5: Optional Enhancements

  • Add agents you find useful
  • Add slash commands
  • Customize Stop hooks (advanced)
  • Tune conservativeness level

Environment Variables

# AI Provider (optional - only for AI mode)
SKILL_AI_PROVIDER=gemini         # Force: gemini|openai|anthropic|ollama
GEMINI_API_KEY=                  # Auto-detect Gemini
OPENAI_API_KEY=                  # Auto-detect OpenAI
ANTHROPIC_API_KEY=               # Auto-detect Anthropic
OLLAMA_MODEL=llama3.2            # Default Ollama model
OLLAMA_BASE_URL=http://localhost:11434

# Behavior
SKILL_CONSERVATIVENESS=balanced  # strict|balanced|aggressive
DEBUG_SKILLS=0                   # 1 for debug output

# PreToolUse Guard
PRETOOLUSE_SOFT_BLOCK=false      # true for soft-blocking
SKIP_MANDATORY_SKILLS=false      # true to bypass enforcement

See .env.example for full documentation.

Getting Help

Troubleshooting / Disabling

Something not working? Run the health check first - it tells you exactly what to fix:

bash .claude/scripts/verify-setup.sh

Or ask Claude to run /verify-setup and it fixes the failures itself.

Need everything off fast? Remove the "hooks" block from .claude/settings.json - all hooks stop running immediately.

Per-feature kill switches (set in your shell or before launching Claude Code):

  • SESSION_DOCS_ENABLED=false - disable session doc updates
  • SKIP_MANDATORY_SKILLS=true - bypass mandatory skill enforcement
  • DEBUG_SKILLS=1 - verbose logging for skill activation

Where logs live: .claude/hooks/*.log and .claude/hooks/data/

For Users

Issues with integration?

  1. Check CLAUDE_INTEGRATION_GUIDE.md
  2. Ask Claude: "Why isn't [skill] activating?"
  3. Open an issue with your project structure

For Claude Code

When helping users integrate:

  1. Read CLAUDE_INTEGRATION_GUIDE.md FIRST
  2. Ask about their project structure
  3. Customize, don't blindly copy
  4. Verify after integration

What This Solves

Before This Infrastructure

❌ Skills don't activate automatically ❌ Have to remember which skill to use ❌ Large skills hit context limits ❌ Context resets lose project knowledge ❌ No consistency across development ❌ Manual agent invocation every time

After This Infrastructure

✅ Skills suggest themselves based on context ✅ Hooks trigger skills at the right time ✅ Modular skills stay under context limits ✅ Dev docs preserve knowledge across resets ✅ Consistent patterns via guardrails ✅ Agents streamline complex tasks

Community

Found this useful?

  • ⭐ Star this repo
  • 🐛 Report issues or suggest improvements
  • 💬 Share your own skills/hooks/agents
  • 📝 Contribute examples from your domain

Background: This infrastructure was detailed in a post I made to Reddit "Claude Code is a Beast – Tips from 6 Months of Hardcore Use". After hundreds of requests, this showcase was created to help the community implement these patterns.

License

MIT License - Use freely in your projects, commercial or personal.

Quick Links

Start here: Copy the two essential hooks, add one skill, and see the auto-activation magic happen.

About

Examples of my Claude Code infrastructure with skill auto-activation, hooks, and agents

Resources

Readme

License

MIT license
Activity

Stars

10k stars

Watchers

103 watching

Forks

1.2k forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages