claude-code-infrastructure-showcase

# Claude Code Infrastructure Showcase > Skill by [ara.so](https://ara.so) — Claude Code Skills collection. Expert guidance for implementing production-tested Claude Code infrastructure including auto-activating skills, hooks, agents, and dev docs systems extracted from 6 months of real-world TypeScript microservices development. ## What This Project Provides The claude-code-infrastructure-showcase is a **reference library** (not a working application) providing: - **Auto-activating skills** via hook-based triggers - **Modular skill pattern** following 500-line rule with progressive disclosure - **Specialized agents** for complex development tasks - **Dev docs system** that preserves context across resets - **Production-tested patterns** from real enterprise development **Key Philosophy:** Copy what you need into your own projects. Everything is designed to be extracted and customized. ## Repository Structure ``` .claude/ ├── skills/ # Production skills │ ├── backend-dev-guidelines/ # Node.js/Express/Prisma patterns │ ├── frontend-dev-guidelines/ # React/TypeScript/MUI v7 │ ├── skill-developer/ # Meta-skill for creating skills │ ├── route-tester/ # API route testing │ ├── error-tracking/ # Sentry integration │ └── skill-rules.json # Skill activation config ├── hooks/ # Automation hooks │ ├── skill-activation-prompt.* # Auto-suggest skills (ESSENTIAL) │ ├── post-tool-use-tracker.sh # Track file operations (ESSENTIAL) │ ├── tsc-check.sh # TypeScript validation (optional) │ └── trigger-build-resolver.sh # Build error resolution (optional) ├── agents/ # Specialized agents │ ├── code-architecture-reviewer.md │ ├── refactor-planner.md │ └── ... 8 more agents └── commands/ # Slash commands └── dev-docs.md dev/active/ # Dev docs examples ``` ## Core Concepts ### 1. Auto-Activation System **Problem:** Skills don't activate automatically - you must remember to use them. **Solution:** Hook + configuration system: ```json // .claude/skills/skill-rules.json { "skills": [ { "name": "backend-dev-guidelines", "activationRules": { "pathPatterns": [ "**/src/routes/**", "**/src/controllers/**", "**/src/services/**" ], "promptKeywords": [ "api", "endpoint", "route", "controller", "service", "repository", "database" ], "autoActivate": true } } ] } ``` **How it works:** 1. `skill-activation-prompt` hook runs on every user prompt 2. Analyzes prompt text and open file paths 3. Matches against `skill-rules.json` patterns 4. Auto-suggests relevant skills ### 2. Modular Skills (500-Line Rule) Large skills hit context limits. Use progressive disclosure: ``` skill-name/ ├── SKILL.md # <500 lines - overview + navigation └── resources/ ├── routing-patterns.md # <500 lines each ├── testing-guide.md └── error-handling.md ``` **Example from backend-dev-guidelines:** ```markdown <!-- SKILL.md --> # Backend Development Guidelines ## Quick Navigation - [Routing Patterns](resources/routing-patterns.md) - [Controller Layer](resources/controllers.md) - [Service Layer](resources/services.md) ## When to Load Resources - Working on routes? → Load routing-patterns.md - Writing business logic? → Load services.md ``` ### 3. Dev Docs Pattern Preserve context across Claude Code resets: ``` dev/active/[task-name]/ ├── [task]-plan.md # Strategic overview ├── [task]-context.md # Key decisions & files └── [task]-tasks.md # Checklist format ``` ## Installation & Setup ### Phase 1: Essential Hooks (15 minutes) **Step 1: Copy hook files** ```bash # Copy to your project cp .claude/hooks/skill-activation-prompt.* your-project/.claude/hooks/ cp .claude/hooks/post-tool-use-tracker.sh your-project/.claude/hooks/ chmod +x your-project/.claude/hooks/*.sh ``` **Step 2: Install Node.js dependencies (for skill-activation-prompt)** ```bash cd your-project/.claude/hooks npm init -y npm install fs path ``` **Step 3: Update settings.json** ```json { "hooks": { "UserPromptSubmit": [ { "command": "node", "args": [".claude/hooks/skill-activation-prompt.js"], "timeout": 5000 } ], "PostToolUse": [ { "command": ".claude/hooks/post-tool-use-tracker.sh", "timeout": 3000 } ] } } ``` ### Phase 2: Add Your First Skill (10 minutes) **Step 1: Choose a skill** Available skills: - `backend-dev-guidelines` - Express/Prisma/TypeScript APIs - `frontend-dev-guidelines` - React/MUI/TypeScript - `skill-developer` - Creating new skills - `route-tester` - Testing authenticated routes - `error-tracking` - Sentry integration **Step 2: Copy skill directory** ```bash # Example: backend skill cp -r .claude/skills/backend-dev-guidelines your-project/.claude/skills/ ``` **Step 3: Create/update skill-rules.json** ```bash # Copy base config cp .claude/skills/skill-rules.json your-project/.claude/skills/ # Edit to match YOUR project structure ``` **Step 4: Customize path patterns** ```json { "skills": [ { "name": "backend-dev-guidelines", "activationRules": { "pathPatterns": [ // Customize these to YOUR project structure "**/api/routes/**", // Your routes directory "**/api/controllers/**", // Your controllers "**/services/**" // Your services ], "promptKeywords": [ "api", "endpoint", "route" ], "autoActivate": true } } ] } ``` ### Phase 3: Test Activation (5 minutes) **Test 1: Path-based activation** ```bash # Open a file matching your pathPatterns code your-project/api/routes/users.ts # Ask Claude a question - skill should auto-suggest "How should I structure this route?" ``` **Test 2: Keyword-based activation** ```bash # Ask with trigger keywords "I need to create a new API endpoint for user registration" # Should suggest backend-dev-guidelines ``` ## Key Patterns & Examples ### Pattern 1: Creating a Modular Skill **Structure:** ```bash .claude/skills/my-skill/ ├── SKILL.md # Main entry point └── resources/ ├── topic-1.md ├── topic-2.md └── topic-3.md ``` **SKILL.md template:** ```markdown --- name: my-skill description: Brief one-line description triggers: - "trigger phrase 1" - "trigger phrase 2" --- # My Skill > Skill by [ara.so](https://ara.so) ## Overview High-level guidance (keep under 500 lines) ## Quick Navigation - [Topic 1](resources/topic-1.md) - Use when... - [Topic 2](resources/topic-2.md) - Use when... ## When to Load Resources **Working on X?** → Load topic-1.md **Debugging Y?** → Load topic-2.md ``` ### Pattern 2: Skill Rules Configuration **Full example:** ```json { "skills": [ { "name": "backend-dev-guidelines", "activationRules": { "pathPatterns": [ "**/src/routes/**", "**/src/controllers/**", "**/src/services/**", "**/src/repositories/**", "**/prisma/**" ], "promptKeywords": [ "api", "endpoint", "route", "controller", "service", "repository", "database", "prisma", "validation", "error handling", "middleware" ], "autoActivate": true, "priority": 1 } }, { "name": "frontend-dev-guidelines", "activationRules": { "pathPatterns": [ "**/src/components/**", "**/src/pages/**", "**/src/hooks/**", "**/src/contexts/**" ], "promptKeywords": [ "component", "react", "mui", "datagrid", "form", "validation", "state", "hook" ], "autoActivate": true, "priority": 1 } } ], "globalSettings": { "maxConcurrentSkills": 2, "skillSuggestionMode": "auto" } } ``` ### Pattern 3: Creating a Hook **Example: Simple post-commit hook** ```bash #!/bin/bash # .claude/hooks/post-commit.sh # Log commit info echo "Commit completed: $(git log -1 --oneline)" # Update dev docs if [ -f "dev/active/current-task/tasks.md" ]; then echo "✓ Remember to update dev/active/current-task/tasks.md" fi exit 0 ``` **Register in settings.json:** ```json { "hooks": { "PostToolUse": [ { "command": ".claude/hooks/post-commit.sh", "timeout": 3000 } ] } } ``` ### Pattern 4: Creating a Specialized Agent **Template:** ```markdown --- name: my-agent description: Agent for [specific task] --- # My Agent ## Purpose [What this agent does] ## When to Use - [Scenario 1] - [Scenario 2] ## Capabilities - [Capability 1] - [Capability 2] ## Workflow ### Step 1: [Phase Name] [Instructions] ### Step 2: [Phase Name] [Instructions] ## Output Format [Expected deliverables] ## Example Usage [Concrete example] ``` **Real example from showcase:** ```markdown --- name: code-architecture-reviewer description: Reviews code for architectural consistency and best practices --- # Code Architecture Reviewer ## Purpose Analyze code against established architectural patterns and provide actionable improvement recommendations. ## When to Use - Before merging large features - After major refactoring - When onboarding new patterns ## Workflow ### Step 1: Load Context - Read architecture documentation - Review relevant skills (backend-dev-guidelines, etc.) - Understand project structure ### Step 2: Analyze Code - Check layer separation (routes → controllers → services) - Verify error handling patterns - Review naming conventions ### Step 3: Generate Report - Inconsistencies found - Recommended changes - Priority ranking ``` ### Pattern 5: Dev Docs Workflow **Create with slash command:** ```bash # In Claude Code /dev-docs "implement user authentication" ``` **Generates:** ```markdown # dev/active/user-authentication/ ## user-authentication-plan.md ### Overview Implement JWT-based authentication with refresh tokens ### Success Criteria - Users can register/login - Tokens expire after 15 minutes - Refresh tokens work ## user-authentication-context.md ### Key Files - src/routes/auth.ts - src/services/authService.ts - src/middleware/authenticate.ts ### Important Decisions - Using JWT (not sessions) for scalability - Refresh tokens stored in httpOnly cookies ## user-authentication-tasks.md - [ ] Create auth routes - [ ] Implement JWT generation - [ ] Add middleware - [ ] Write tests ``` ## Configuration Reference ### settings.json Structure ```json { "hooks": { "UserPromptSubmit": [ { "command": "node",