Guide · Open source

How to use claude-code-infrastructure-showcase: setup and skill auto-activation

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

claude-code-infrastructure-showcase is an MIT-licensed reference library of Claude Code configuration: hook scripts, markdown skills, specialized agents and a skill-rules.json file that decides which skills load for a given prompt or file. It is not a working application, so you copy the pieces you need into your own project. This guide walks through the requirements, the setup options, verification, optional AI classification and how to read the activation output, so you can adapt it to a larger TypeScript or Node.js codebase.

Claude Code Infrastructure Showcasediet103/claude-code-infrastructure-showcase · ★ 10k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm Node.js 18+ and npm are installed and that you are on macOS, Linux or WSL2.
2Clone the repository. Run git clone on the diet103 showcase repo into a folder outside your project.
3Run the setup wizard. Run npx tsx setup.ts with your project path, answering the mode question or adding --yes.
4Verify the install. Run bash .claude/scripts/verify-setup.sh from the project root and fix any failed check using the suggested command.
5Edit skill-rules.json. Adjust which prompts and files trigger each skill so they match your project's conventions.
6Optionally enable AI mode. Add a provider key to the hooks .env file and set skill_activation_mode to fallback.

What you need before you start

The README lists Node.js 18+ (20+ recommended) with npm, and macOS, Linux or WSL2. The hooks are bash scripts and will not run in plain cmd or PowerShell, so Windows users should work inside WSL2.

Node.js 18+ (20+ recommended) and npm
macOS, Linux, or WSL2
jq, only if you enable the optional Stop hooks

Install the showcase with the setup wizard

The recommended route clones the repo and runs the wizard against your project. The wizard copies .claude/ (hooks, skills, agents, commands), detects your tech stack, asks whether you want Classic (regex-only) or AI-Enhanced mode, installs hook dependencies and makes scripts executable. The first npx tsx run may ask to install tsx; say yes.

If you prefer manual copying, the README's Option B copies .claude/ into your project and runs npm install inside .claude/hooks, then chmod +x on the shell scripts.

Clone the repository
Run the wizard with your project path
Add --yes for non-interactive runs; see --help for all flags

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

Verify the setup works

Run the verification script from your project root. The README describes eight checks, including Node version, hook registration, executable bits, dependencies, config validity and a test prompt through the real activation hook. Each failed check comes with a fix command. You can also ask Claude to run /verify-setup.

bash .claude/scripts/verify-setup.sh

Understand how skill auto-activation works

A skill is a markdown guide Claude loads when relevant. A hook is a script Claude Code runs at key moments, such as every prompt or before and after edits. skill-rules.json maps prompts and files to skills. The UserPromptSubmit hook analyzes your prompt, checks file context and suggests matching skills, so you do not have to remember to load them.

The README's example shows the output when you type a request to create a React component: a mandatory skill activation banner naming frontend-dev-guidelines, and a note that edits are blocked until the skill is activated. Treat that as the behaviour the example config produces, and tune skill-rules.json to match your project.

Skills: markdown guides such as backend-dev-guidelines and frontend-dev-guidelines
Hooks: scripts that run automatically
skill-rules.json: the config linking prompts and files to skills

Optional: turn on AI classification

The default mode uses regex and keyword matching and makes no API calls. AI classification is optional and tries to match intent rather than keywords. The README's modes are disabled (default), fallback (AI first, regex on failure) and ai-only. Supported providers listed are Gemini, OpenAI, Anthropic and Ollama. Auto-detection tries them in the order Gemini, OpenAI, Anthropic, Ollama, and SKILL_AI_PROVIDER overrides it.

To enable Gemini, copy the hooks .env.example to .env, uncomment the key line, add .env to .gitignore, and change skill_activation_mode from disabled to fallback in skill-rules.json. Environment variables such as GEMINI_API_KEY also work.

disabled: regex/keyword only, free, offline
fallback: AI first, regex if AI fails
ai-only: pure AI classification, needs network

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

Upgrade an existing install safely

Re-running the wizard on a project that already has .claude/ copies no files. It re-chmods hooks, updates skill-rules.json settings and reinstalls dependencies, and it does not overwrite your customized skill-rules.json or skills.

To bring in new files, copy specific folders from a fresh clone, or if .claude/ is in git, delete it, re-run the wizard and use git diff to port your changes back.

cp -r showcase/.claude/scripts ~/my-project/.claude/

What people use it for

Adding auto-activated frontend or backend guidelines to a React or Express project
Studying hook scripts and skill-rules.json as examples before writing your own
Adapting the specialized agents for code review, refactoring or documentation tasks
Keeping project conventions loaded in long Claude Code sessions with a dev docs pattern the README describes

Frequently asked questions

Does claude-code-infrastructure-showcase work on Windows?

The README says the hooks are bash scripts that will not run in plain cmd or PowerShell. Windows users should install and run it inside WSL2.

Is claude-code-infrastructure-showcase free to use?

The repository is licensed under MIT. The default regex mode makes no API calls. The optional AI modes need a provider key, and the README notes Gemini's free tier covers this use case while OpenAI and Anthropic are listed without a free tier.

Do I need an API key to use it?

No. The standard disabled mode uses regex and keyword matching and needs no key. You only need one if you enable fallback or ai-only classification.

Is this a ready-made app I can run?

No. The README states it is not a working application. It is a reference library, and you copy the configuration, hooks, skills and agents you want into your own project.

What do I need to know before installing?

Familiarity with Claude Code hooks and config files helps, because the README's setup assumes it. Its Key Concepts section defines skills, hooks and skill-rules.json.

Are there alternatives to this showcase?

Our analysis lists no directly comparable projects. You can build your own hooks and skill-rules.json from the examples in this repo.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This suits developers already using Claude Code on a larger TypeScript or Node.js project who want working examples of hooks, skill-rules.json and agents to adapt, on macOS, Linux or WSL2. Beginners, Windows users outside WSL2, and anyone wanting a ready-to-run app should choose something else.

Install options & downloads