Wow, someone has open-sourced their entire set of configurations for tuning Claude Code over six months. This reference repository has garnered over 9,700 stars on GitHub. It is a production-grade configuration refined by the author over 6 months using a real TypeScript microservice project. It specifically solves a pain point that many people face: Claude Code skills are written but don’t trigger automatically. The author uses hooks plus a skill-rules.json configuration to automatically activate the relevant skill when needed. Additionally, it features modular skill writing (500-line cap with progressive disclosure), specialized agents for handling complex tasks, and a development documentation system that survives context resets. This is not a ready-to-run application; it’s a reference library. You copy the parts you need into your own project. The author says integration takes about 15 to 30 minutes. Copy the lessons learned over six months into your workflow in one go.

GitHub: —

diet103/claude-code-infrastructure-showcase

Source: https://github.com/diet103/claude-code-infrastructure-showcase

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:

``bash

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)

``bash

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:

text 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 --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 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):

``bash

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:

bash 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:

Supported AI providers:

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 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!

👉 How agents work →

💬 Slash Commands (4)

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 (https://agentskills.io). 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 tw