claude-code-infrastructure-showcase: skills that load themselves

A reference library, not something you run

The README is direct about what this is. It calls itself a curated reference library of production-tested Claude Code infrastructure, and states in a callout that it is not a working application, but something you copy pieces of into your own projects. The claimed origin is six months of iteration on a complex TypeScript microservices project, with a stated integration cost of 15 to 30 minutes.

The repository tree is small enough to read in one pass: `.claude/` holds the actual infrastructure, `editor-config/` holds an optional Neovim configuration, `setup.ts` is the installer, `CLAUDE_INTEGRATION_GUIDE.md` is the path for letting Claude Code do the installation, `dev/` holds the project's own working material, and `.agents/` and `.codex/` sit alongside `.claude/` for the other two agent harnesses. There is a `.env.example` at the top level rather than buried in the hooks directory. No releases are published and the default branch `main` was last pushed on 2026-07-13. The licence is MIT.

Three terms carry most of the design, and the README says so. A skill is a markdown guide Claude loads when relevant. A hook is a script Claude Code runs automatically at key moments, described as every prompt and before or after edits. `skill-rules.json` is the config that tells hooks which prompts and files should trigger which skills. Everything else in the repository is an application of those three.

Running the setup wizard against your project

There are three install paths and the wizard is the one the README recommends. It runs on Node.js 18 or newer, on macOS, Linux or WSL2, and needs `jq` only if you enable the optional Stop hooks.

git clone https://github.com/diet103/claude-code-infrastructure-showcase.git
cd claude-code-infrastructure-showcase
npx tsx setup.ts ~/my-project

What the wizard claims to do is specific: copy `.claude/` including hooks, skills, agents and commands into your project, detect your tech stack, ask whether you want Classic regex-only mode or AI-enhanced mode, ask for a provider if you chose AI and validate that the API key is present, install the hook dependencies, make the scripts executable, and then run eight health checks before it declares success. For scripted use it takes a `--yes` flag.

The manual path is three commands, for people who would rather see what lands on disk:

cp -r claude-code-infrastructure-showcase/.claude ~/my-project/.claude
cd ~/my-project/.claude/hooks && npm install && chmod +x *.sh

The third path is the one with the most personality. You open Claude Code in your own project and paste a prompt telling it to clone the repository to a temp directory, read `CLAUDE_INTEGRATION_GUIDE.md`, run the wizard non-interactively with `--yes`, and show the verification results while fixing anything that failed. The repository is partly a demonstration of the thing it documents.

Eight checks that fire a real prompt through the hook

Verification is a script you can run at any time from your project root:

bash .claude/scripts/verify-setup.sh

The README lists what those eight checks cover: Node version, hook registration, executable bits, dependencies, config validity, and firing a test prompt through the actual activation hook. That last one is the check that matters, because a hook can be registered, executable and syntactically valid while matching nothing.

Each check comes with an exact fix command when it fails, which is a small detail that says something about how the author expects this to be used. There is also a `/verify-setup` command for the case where you would rather ask Claude to run it and fix the failures itself.

The upgrade path is worth knowing before your first install, because the answer is deliberately conservative. Re-running the wizard on a project that already has a `.claude/` directory copies no files at all. It re-chmods the hooks, updates settings in `skill-rules.json` and reinstalls dependencies, and the README states it will never overwrite a customised config or customised skills. To pick up new files from a newer version of the repository, you copy specific directories from a fresh clone, or delete a committed `.claude/`, re-run the wizard and port your changes back through a `git diff`.

Regex matching by default, an external model as an option

The default mode is worth separating from the optional one, because they differ in more than cost. The README states that no API key is needed by default: the standard mode uses regex and keyword matching, which is free, offline and makes zero API calls. AI classification is described as an upgrade that matches your intent instead of your keywords.

Enabling it takes three steps, and the middle one is the part with a security consequence:

cp .claude/hooks/.env.example .claude/hooks/.env

Then you uncomment a key in that file and flip `skill_activation_mode` in `.claude/skills/skill-rules.json` from `disabled` to `fallback`. The README notes you can export `GEMINI_API_KEY` in `~/.bashrc` instead, since the hooks read both.

The `.env.example` in the repository is more useful than a README note usually is. It names four providers you can force: gemini, openai, anthropic and ollama, with per-provider key variables and an optional `OPENAI_BASE_URL` for an Azure endpoint, and it points at Ollama as the local option that needs no key, with `Ollama pull llama3.2` as the example model. It also groups the remaining knobs: a conservativeness level of strict, balanced or aggressive, a `DEBUG_SKILLS` flag, and the PreToolUse guard settings, including soft blocking to block the first edit and allow later ones, and flags to skip mandatory skill enforcement or skip AI analysis in the guard.

That file is the honest description of what the system can be tuned to do, and it is worth reading before turning anything on. In AI mode your prompt text goes to whichever provider you configured. In regex mode it stays on your machine.

The `fallback` mode name is doing real work, by the way. The README describes it as always degrading gracefully: no key, a dead network or a slow provider gives you regex matching rather than a broken prompt.

Why the enforcement is a block rather than a suggestion

The problem the repository names is that skills do not activate automatically, and the fix is to make activation a gate rather than a hint. A PreToolUse hook runs before Claude edits a file, classifies the prompt, and if a skill is required it injects a mandatory activation notice naming the skills that have to be loaded, with the statement that edits will be blocked until they are, and that the first action must be a Skill tool call. The notice attributes the match to the regex classifier so you can see why it fired.

That design has an obvious tension, and the project addresses it directly. The soft-blocking setting defaults to false, meaning the guard suggests rather than blocks, and there is a `SKIP_MANDATORY_SKILLS` escape hatch. A system that interrupts every edit until a markdown file has been read will get switched off within a day if it fires on the wrong prompts, so the conservativeness levels and the skip flags are not decoration.

The README also describes a 500-line rule for skills with progressive disclosure, which is the standard shape for keeping context small: a short guide that points at more detail instead of inlining everything. Alongside that sit specialised agents for complex tasks and a dev docs system the README says survives context resets. The context reset point is the real motivation for all of it. If your notes live only in a conversation, they are gone when the conversation ends, and a docs directory in the repository is what makes the setup outlive a session.

Where this fits against doing nothing

The honest comparison is with the default state of Claude Code, where you write project instructions into `CLAUDE.md` and skills load when Claude decides they are relevant. If your team already writes disciplined prompts and remembers to name skills, this repository adds a moving part: bash hooks, a JSON config, an optional external API call and a verification script to keep in step.

The case for it is scale. The origin story is a complex TypeScript microservices project, and the pattern that breaks down first as a codebase grows is Claude working in a file with no project-specific guidance, which is exactly what an automatic activation rule prevents. A regex classifier that catches `create a React component` and pulls in frontend guidelines is doing something a prose instruction cannot do reliably.

The case against is platform and privacy. The hooks are bash scripts, so Windows without WSL2 is out, which the README states directly. And the AI mode sends prompt text to an external provider, which is a different proposition from a local documentation file, particularly in a company with rules about code leaving the network.

There is one more thing this repository is not. Despite the name, it does not demonstrate infrastructure as code, deployment pipelines or anything a platform team would call infrastructure. It is a curated set of agent configuration files, plus an editor config, plus a wizard. Judged as a reference library with a 15 to 30 minute integration claim, that is a reasonable thing to be.

Editorial conclusion

This repository is worth an afternoon if your problem is exactly the one it names, that Claude forgets to load a skill unless you remember to ask, because the mechanism is small and legible: a PreToolUse hook classifies the prompt, reads skill-rules.json, and injects a mandatory activation block that edits cannot proceed past. It is a poor fit if you want a finished application to run, since the README says outright it is a reference library, and a poor fit on Windows without WSL2 because the hooks are bash scripts. One claim deserves scrutiny before you adopt the AI mode: it routes your prompt text to an external provider, which is a different privacy decision from reading local documentation. Start with the default regex mode and no API key, run `bash .claude/scripts/verify-setup.sh`, and only turn on AI classification once the offline path is working and you accept where the prompt text goes.

Frequently asked questions

Official sources

1. diet103/claude-code-infrastructure-showcase on GitHub
2. Issues
3. License: MIT
4. README