claude-code-infrastructure-showcase
Expert in Claude Code infrastructure patterns - auto-activating skills, hooks, agents, and dev docs systems
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill claude-code-infrastructure-showcaseIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
This skill provides a framework for auto-activating skills and automation hooks. It introduces security risks by encouraging the persistent execution of shell and Node.js scripts that process untrusted user prompts and filesystem paths without apparent sanitization.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 1 issue
What does this agent skill do?
Claude Code Infrastructure Showcase
Skill by 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:
// .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:
skill-activation-prompthook runs on every user prompt- Analyzes prompt text and open file paths
- Matches against
skill-rules.jsonpatterns - 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:
<!-- 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
# 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)
cd your-project/.claude/hooks
npm init -y
npm install fs path
Step 3: Update settings.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 APIsfrontend-dev-guidelines- React/MUI/TypeScriptskill-developer- Creating new skillsroute-tester- Testing authenticated routeserror-tracking- Sentry integration
Step 2: Copy skill directory
# Example: backend skill
cp -r .claude/skills/backend-dev-guidelines your-project/.claude/skills/
Step 3: Create/update skill-rules.json
# Copy base config
cp .claude/skills/skill-rules.json your-project/.claude/skills/
# Edit to match YOUR project structure
Step 4: Customize path patterns
{
"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
# 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
# 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:
.claude/skills/my-skill/
├── SKILL.md # Main entry point
└── resources/
├── topic-1.md
├── topic-2.md
└── topic-3.md
SKILL.md template:
---
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:
{
"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
#!/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:
{
"hooks": {
"PostToolUse": [
{
"command": ".claude/hooks/post-commit.sh",
"timeout": 3000
}
]
}
}
Pattern 4: Creating a Specialized Agent
Template:
---
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:
---
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:
# In Claude Code
/dev-docs "implement user authentication"
Generates:
# 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
{
"hooks": {
"UserPromptSubmit": [
{
"command": "node",
"args": [".claude/hooks/skill-activation-prompt.js"],
"timeout": 5000
}
],
"PostToolUse": [
{
"command": ".claude/hooks/post-tool-use-tracker.sh",
"timeout": 3000
}
],
"Stop": [
{
"command": ".claude/hooks/tsc-check.sh",
"timeout": 10000,
"continueOnError": true
}
]
},
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
}
}
}
skill-rules.json Schema
interface SkillRulesConfig {
skills: SkillRule[];
globalSettings?: {
maxConcurrentSkills?: number;
skillSuggestionMode?: 'auto' | 'manual';
};
}
interface SkillRule {
name: string;
activationRules: {
pathPatterns: string[]; // Glob patterns
promptKeywords: string[]; // Trigger words
autoActivate: boolean;
priority?: number; // Higher = preferred
};
}
Available Skills
backend-dev-guidelines
Purpose: Node.js/Express/Prisma/TypeScript API development
Resources:
routing-patterns.md- Route structure and conventionscontrollers.md- Controller layer patternsservices.md- Business logic organizationrepositories.md- Data access layererror-handling.md- Error managementvalidation.md- Input validation patternstesting.md- Testing strategiesauthentication.md- Auth patternsdatabase.md- Prisma best practiceslogging.md- Logging and monitoringmiddleware.md- Custom middlewareapi-design.md- REST API conventions
Activation:
{
"pathPatterns": [
"**/src/routes/**",
"**/src/controllers/**",
"**/src/services/**"
],
"promptKeywords": ["api", "endpoint", "route", "service"]
}
frontend-dev-guidelines
Purpose: React/TypeScript/MUI v7 development
Resources:
component-patterns.md- Component structurestate-management.md- State patternsmui-patterns.md- MUI v7 best practicesdatagrid-patterns.md- DataGrid usageform-patterns.md- Form handlinghooks-patterns.md- Custom hooksrouting.md- React Router patternstesting.md- Component testingperformance.md- Optimizationaccessibility.md- A11y guidelineserror-handling.md- Error boundaries
Activation:
{
"pathPatterns": [
"**/src/components/**",
"**/src/pages/**",
"**/src/hooks/**"
],
"promptKeywords": ["component", "react", "mui", "form"]
}
skill-developer
Purpose: Meta-skill for creating new skills
Resources:
skill-structure.md- Skill anatomyprogressive-disclosure.md- 500-line ruleskill-rules.md- Activation configurationresource-organization.md- Resource file patternstesting-skills.md- Skill testingmaintenance.md- Updating skillsexamples.md- Real skill examples
Use when: Creating new skills or modifying existing ones
Available Agents
code-architecture-reviewer
Reviews code for architectural consistency
Usage:
@code-architecture-reviewer Review the new user service for architectural issues
refactor-planner
Creates detailed refactoring strategies
Usage:
@refactor-planner Plan refactoring of the auth system to use dependency injection
frontend-error-fixer
Debugs frontend errors with React DevTools context
Usage:
@frontend-error-fixer Fix the "Cannot read property 'map' of undefined" error in UserList
documentation-architect
Generates comprehensive documentation
Usage:
@documentation-architect Generate API documentation for the user service
auth-route-tester
Tests authenticated API endpoints
Usage:
@auth-route-tester Test POST /api/users/register with sample data
auto-error-resolver
Automatically fixes TypeScript compilation errors
Usage:
@auto-error-resolver Fix type errors in src/services/userService.ts
Common Workflows
Workflow 1: Setting Up for a New Project
# 1. Copy essential hooks
mkdir -p .claude/hooks
cp showcase/.claude/hooks/skill-activation-prompt.* .claude/hooks/
cp showcase/.claude/hooks/post-tool-use-tracker.sh .claude/hooks/
chmod +x .claude/hooks/*.sh
# 2. Install dependencies
cd .claude/hooks && npm init -y && npm install fs path
# 3. Copy relevant skill
mkdir -p .claude/skills
cp -r showcase/.claude/skills/backend-dev-guidelines .claude/skills/
# 4. Create skill-rules.json
cat > .claude/skills/skill-rules.json << 'EOF'
{
"skills": [
{
"name": "backend-dev-guidelines",
"activationRules": {
"pathPatterns": ["**/src/**"],
"promptKeywords": ["api", "service"],
"autoActivate": true
}
}
]
}
EOF
# 5. Update settings.json
cat > .claude/settings.json << 'EOF'
{
"hooks": {
"UserPromptSubmit": [
{
"command": "node",
"args": [".claude/hooks/skill-activation-prompt.js"],
"timeout": 5000
}
],
"PostToolUse": [
{
"command": ".claude/hooks/post-tool-use-tracker.sh",
"timeout": 3000
}
]
}
}
EOF
Workflow 2: Creating a Custom Skill
# 1. Use skill-developer skill
# In Claude Code:
# "I want to create a new skill for GraphQL development"
# 2. Create structure
mkdir -p .claude/skills/graphql-guidelines/resources
# 3. Create SKILL.md
cat > .claude/skills/graphql-guidelines/SKILL.md << 'EOF'
---
name: graphql-guidelines
description: GraphQL API development patterns with Apollo Server
triggers:
- "graphql schema"
- "resolver implementation"
- "graphql query"
---
# GraphQL Guidelines
> Skill by [ara.so](https://ara.so)
## Overview
Patterns for GraphQL API development
## Resources
- [Schema Design](resources/schema-design.md)
- [Resolver Patterns](resources/resolvers.md)
EOF
# 4. Add to skill-rules.json
# Edit .claude/skills/skill-rules.json to add activation rules
Workflow 3: Using Dev Docs
# 1. Start new task
# In Claude Code:
/dev-docs "refactor authentication to use refresh tokens"
# 2. Claude creates:
# dev/active/auth-refactor/
# auth-refactor-plan.md
# auth-refactor-context.md
# auth-refactor-tasks.md
# 3. Work on task, update tasks.md as you go
# 4. Before context reset:
/dev-docs-update
# 5. After reset, load context:
# "Load dev/active/auth-refactor/ and continue"
Workflow 4: Adding a Hook
# 1. Create hook file
cat > .claude/hooks/pre-commit-check.sh << 'EOF'
#!/bin/bash
# Run linting before commits
echo "Running pre-commit checks..."
# Run eslint
npm run lint
if [ $? -ne 0 ]; then
echo "❌ Linting failed"
exit 1
fi
echo "✅ Pre-commit checks passed"
exit 0
EOF
# 2. Make executable
chmod +x .claude/hooks/pre-commit-check.sh
# 3. Add to settings.json
# Under "hooks" → "Stop" array
Troubleshooting
Skills Not Activating
Problem: Skills don't auto-suggest when expected
Check:
- Verify hook is registered in settings.json
- Check skill-rules.json path patterns match your structure
- Test hook manually:
node .claude/hooks/skill-activation-prompt.js - Review hook logs in
.claude/hooks/activation-log.json
Common issues:
- Path patterns too specific (use broader globs)
- Keywords not matching (add more trigger words)
- Hook timeout too short (increase to 5000ms)
Hooks Not Running
Problem: Hooks don't execute at all
Check:
- Hook files are executable:
chmod +x .claude/hooks/*.sh - settings.json syntax is valid (use JSON validator)
- Hook paths are relative to project root
- Node.js dependencies installed for .js hooks
Debug:
# Test hook directly
.claude/hooks/post-tool-use-tracker.sh
# Check for errors
echo $? # Should be 0
Context Limit Errors
Problem: "Context limit exceeded" when loading skill
Solution: Skill is too large, needs modularization
# 1. Check main SKILL.md line count
wc -l .claude/skills/my-skill/SKILL.md
# 2. If >500 lines, split into resources
mkdir -p .claude/skills/my-skill/resources
# 3. Move sections to resource files
# Keep only overview + navigation in SKILL.md
# 4. Update references
# Link to resources/topic.md instead of inline content
Dev Docs Not Persisting
Problem: Context still lost after using dev docs
Check:
- Files saved in
dev/active/[task-name]/ - All three files created (plan, context, tasks)
- Files committed to git (not in .gitignore)
Best practice:
# Explicitly load dev docs after reset
"Load all files in dev/active/auth-refactor/ and summarize the current state"
Hook Performance Issues
Problem: Hooks causing slowdowns
Solutions:
-
Optimize JavaScript hooks:
// Cache file reads const cache = new Map(); function readFileWithCache(path) { if (cache.has(path)) return cache.get(path); const content = fs.readFileSync(path, 'utf8'); cache.set(path, content); return content; } -
Set appropriate timeouts:
{ "timeout": 3000, // 3s for simple hooks "timeout": 10000 // 10s for complex hooks } -
Use
continueOnError:{ "command": ".claude/hooks/heavy-check.sh", "continueOnError": true // Don't block on failure }
Environment Variables
Hooks and skills reference these environment vars:
# Project paths
PROJECT_ROOT=/path/to/project
CLAUDE_CONFIG_DIR=/path/to/project/.claude
# Skill configuration
SKILL_RULES_PATH=$CLAUDE_CONFIG_DIR/skills/skill-rules.json
# Logging
HOOK_LOG_LEVEL=info # debug, info, warn, error
ACTIVATION_LOG=$CLAUDE_CONFIG_DIR/hooks/activation-log.json
# Optional: Custom tool paths
TSC_PATH=./node_modules/.bin/tsc
ESLINT_PATH=./node_modules/.bin/eslint
Best Practices
Skill Development
-
Keep main SKILL.md under 500 lines
- Use resources/ for deep dives
- Include navigation section
- Explain when to load each resource
-
Write clear activation rules
{ "pathPatterns": [ "**/specific/path/**", // Specific first "**/broad/path/**" // Broad as fallback ] } -
Use real code examples
- From your actual project
- Show before/after
- Include error cases
-
Version control skills
- Commit to git
- Document changes
- Tag releases
Hook Development
-
Keep hooks fast (<3 seconds)
- Cache expensive operations
- Use timeouts appropriately
- Fail gracefully
-
Handle errors explicitly
#!/bin/bash set -e # Exit on error if ! command -v node &> /dev/null; then echo "❌ Node.js not found" exit 1 fi -
Log useful information
console.error(JSON.stringify({ timestamp: new Date().toISOString(), hook: 'skill-activation', trigger: 'pathMatch', skill: 'backend-dev-guidelines' }));
Agent Usage
-
Be specific in requests
# Good @refactor-planner Create plan to extract email sending logic into a service # Too vague @refactor-planner Improve the code -
Provide context
- Load relevant files first
- Explain constraints
- Mention related issues
-
Review agent output
- Agents suggest, you decide
- Verify recommendations
- Adapt to your project
Integration Checklist
## Phase 1: Core Setup
- [ ] Copy skill-activation-prompt hook
- [ ] Copy post-tool-use-tracker hook
- [ ] Install Node.js dependencies in .claude/hooks
- [ ] Update settings.json with hooks
- [ ] Test hooks execute (check logs)
## Phase 2: First Skill
- [ ] Choose relevant skill
- [ ] Copy skill directory
- [ ] Create skill-rules.json
- [ ] Customize path patterns for your project
- [ ] Test skill activation (open matching file)
## Phase 3: Validation
- [ ] Skill auto-suggests on file open
- [ ] Skill auto-suggests on relevant prompt
- [ ] No performance degradation
- [ ] Hooks log properly
- [ ] Skills load resources correctly
## Phase 4: Enhancement (Optional)
- [ ] Add more skills as needed
- [ ] Copy useful agents
- [ ] Add slash commands
- [ ] Customize Stop hooks
- [ ] Set up dev docs pattern
Advanced Usage
Custom Skill Rules Logic
Extend skill-activation-prompt.js:
// .claude/hooks/skill-activation-prompt.js
// Add custom activation logic
function shouldActivateSkill(skill, context) {
const { filePath, promptText, timestamp } = context;
// Time-based activation
if (skill.activationRules.timeOfDay) {
const hour = new Date(timestamp).getHours();
if (hour < 9 || hour > 17) return false;
}
// Git branch-based activation
if (skill.activationRules.branches) {
const branch = getCurrentGitBranch();
if (!skill.activationRules.branches.includes(branch)) {
return false;
}
}
// File size-based activation
if (skill.activationRules.maxFileSize) {
const size = fs.statSync(filePath).size;
if (size > skill.activationRules.maxFileSize) {
return false;
}
}
return true;
}
Conditional Resource Loading
In SKILL.md, add logic for resource loading:
## Progressive Loading Strategy
**For small changes (<50 lines):**
Just use this main skill file.
**For new features:**
1. Load [architecture overview](resources/architecture.md)
2. Load relevant pattern resource
**For debugging:**
1. Load [error-handling](resources/error-handling.md)
2. Load [logging](resources/logging.md)
**For refactoring:**
Load ALL resources for comprehensive guidance.
Multi-Project Skill Sharing
Share skills across projects:
# 1. Create shared skills repository
mkdir ~/claude-skills
cp -r project1/.claude/skills/* ~/claude-skills/
# 2. Symlink in each project
ln -s ~/claude-skills project2/.claude/skills
# 3. Use environment-specific skill-rules.json
# project2/.claude/skills/skill-rules.json
{
"skills": [
{
"name": "backend-dev-guidelines",
"activationRules": {
"pathPatterns": [
"**/project2-specific/path/**"
]
}
}
]
}
Resources
- Main Repository: https://github.com/diet103/claude-code-infrastructure-showcase
- Original Reddit Post: Claude Code is a Beast
- Skills Guide:
.claude/skills/README.md - Hooks Guide:
.claude/hooks/README.md - Agents Guide:
.claude/agents/README.md - Integration Guide:
CLAUDE_INTEGRATION_GUIDE.md
License
MIT License - Use freely in personal or commercial projects.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/claude-code-infrastructure-showcase">View claude-code-infrastructure-showcase on skillZs</a>