{
  "pathPatterns": [
    "src/api/**/*.ts", // Single app with src/api
    "backend/**/*.ts", // Backend directory
    "services/*/src/**/*.ts" // Multi-service monorepo
  ]
}

View Skill →

How to Add a Skill to Your Project

Quick Integration

For Claude Code:

User: "Add the backend-dev-guidelines skill to my project"

Claude should:
1. Ask about project structure
2. Copy skill directory
3. Update skill-rules.json with their paths
4. Verify integration

See CLAUDE_INTEGRATION_GUIDE.md for complete instructions.

Manual Integration

Step 1: Copy the skill directory

cp -r claude-code-infrastructure-showcase/.claude/skills/backend-dev-guidelines \\
      your-project/.claude/skills/

Step 2: Update skill-rules.json

If you don't have one, create it:

cp claude-code-infrastructure-showcase/.claude/skills/skill-rules.json \\
   your-project/.claude/skills/

Then customize the

pathPatterns

for your project:

{
  "skills": {
    "backend-dev-guidelines": {
      "fileTriggers": {
        "pathPatterns": [
          "YOUR_BACKEND_PATH/**/*.ts" // ← Update this!
        ]
      }
    }
  }
}

Step 3: Test

Edit a file in your backend directory
The skill should activate automatically

skill-rules.json Configuration

What It Does

Defines when skills should activate based on:

Keywords in user prompts ("backend", "API", "route")
Intent patterns (regex matching user intent)
File path patterns (editing backend files)
Content patterns (code contains Prisma queries)

Configuration Format

{
  "skill-name": {
    "type": "domain" | "guardrail",
    "enforcement": "suggest" | "block",
    "priority": "high" | "medium" | "low",
    "promptTriggers": {
      "keywords": ["list", "of", "keywords"],
      "intentPatterns": ["regex patterns"]
    },
    "fileTriggers": {
      "pathPatterns": ["path/to/files/**/*.ts"],
      "contentPatterns": ["import.*Prisma"]
    }
  }
}

Enforcement Levels

suggest: Skill appears as suggestion, doesn't block
block: Must use skill before proceeding (guardrail)

Use "block" for:

Preventing breaking changes (MUI v6→v7)
Critical database operations
Security-sensitive code

Use "suggest" for:

General best practices
Domain guidance
Code organization

Creating Your Own Skills

See the skill-developer skill for complete guide on:

Skill YAML frontmatter structure
Resource file organization
Trigger pattern design
Testing skill activation

Quick template:

---
name: my-skill
description: What this skill does
---

# My Skill Title

## Purpose

[Why this skill exists]

## When to Use This Skill

[Auto-activation scenarios]

## Quick Reference

[Key patterns and examples]

## Resource Files

- [topic-1.md](resources/topic-1.md)
- [topic-2.md](resources/topic-2.md)

Troubleshooting

Skill isn't activating

Check:

Is skill directory in
```
.claude/skills/
```
?
Is skill listed in
```
skill-rules.json
```
?
Do
```
pathPatterns
```
match your files?
Are hooks installed and working?
Is settings.json configured correctly?

Debug:

# Check skill exists
ls -la .claude/skills/

# Validate skill-rules.json
cat .claude/skills/skill-rules.json | jq .

# Check hooks are executable
ls -la .claude/hooks/*.sh

# Test hook manually
./.claude/hooks/skill-activation-prompt.sh

Skill activates too often

Update skill-rules.json:

Make keywords more specific
Narrow
```
pathPatterns
```
Increase specificity of
```
intentPatterns
```

Skill never activates

Update skill-rules.json:

Add more keywords
Broaden
```
pathPatterns
```
Add more
```
intentPatterns
```

For Claude Code

When integrating a skill for a user:

Read CLAUDE_INTEGRATION_GUIDE.md first
Ask about their project structure
Customize
```
pathPatterns
```
in skill-rules.json
Verify the skill file has no hardcoded paths
Test activation after integration

Common mistakes:

Keeping example paths (blog-api/, frontend/)
Not asking about monorepo vs single-app
Copying skill-rules.json without customization

Next Steps

Start simple: Add one skill that matches your work
Verify activation: Edit a relevant file, skill should suggest
Add more: Once first skill works, add others
Customize: Adjust triggers based on your workflow

Questions? See CLAUDE_INTEGRATION_GUIDE.md for comprehensive integration instructions.

Skills

Production-tested skills for Claude Code that auto-activate based on context.

What Are Skills?

Skills are modular knowledge bases that Claude loads when needed. They provide:

Domain-specific guidelines
Best practices
Code examples
Anti-patterns to avoid

Problem: Skills don't activate automatically by default.

Solution: This showcase includes the hooks + configuration to make them activate.

Available Skills

skill-developer (Meta-Skill)

Purpose: Creating and managing Claude Code skills

Files: 7 resource files (426 lines total)

Use when:

Creating new skills
Understanding skill structure
Working with skill-rules.json
Debugging skill activation

Customization: ✅ None - copy as-is

View Skill →

backend-dev-guidelines

Purpose: Node.js/Express/TypeScript development patterns

Files: 12 resource files (304 lines main + resources)

Covers:

Layered architecture (Routes → Controllers → Services → Repositories)
BaseController pattern
Prisma database access
Sentry error tracking
Zod validation
UnifiedConfig pattern
Dependency injection
Testing strategies

Use when:

Creating/modifying API routes
Building controllers or services
Database operations with Prisma
Setting up error tracking

Customization: ⚠️ Update

pathPatterns

in skill-rules.json to match your backend directories

Example pathPatterns:

{
  "pathPatterns": [
    "src/api/**/*.ts", // Single app with src/api
    "backend/**/*.ts", // Backend directory
    "services/*/src/**/*.ts" // Multi-service monorepo
  ]
}

View Skill →

How to Add a Skill to Your Project

Quick Integration

For Claude Code:

User: "Add the backend-dev-guidelines skill to my project"

Claude should:
1. Ask about project structure
2. Copy skill directory
3. Update skill-rules.json with their paths
4. Verify integration

See CLAUDE_INTEGRATION_GUIDE.md for complete instructions.

Manual Integration

Step 1: Copy the skill directory

cp -r claude-code-infrastructure-showcase/.claude/skills/backend-dev-guidelines \\
      your-project/.claude/skills/

Step 2: Update skill-rules.json

If you don't have one, create it:

cp claude-code-infrastructure-showcase/.claude/skills/skill-rules.json \\
   your-project/.claude/skills/

Then customize the

pathPatterns

for your project:

{
  "skills": {
    "backend-dev-guidelines": {
      "fileTriggers": {
        "pathPatterns": [
          "YOUR_BACKEND_PATH/**/*.ts" // ← Update this!
        ]
      }
    }
  }
}

Step 3: Test

Edit a file in your backend directory
The skill should activate automatically

skill-rules.json Configuration

What It Does

Defines when skills should activate based on:

Keywords in user prompts ("backend", "API", "route")
Intent patterns (regex matching user intent)
File path patterns (editing backend files)
Content patterns (code contains Prisma queries)

Configuration Format

{
  "skill-name": {
    "type": "domain" | "guardrail",
    "enforcement": "suggest" | "block",
    "priority": "high" | "medium" | "low",
    "promptTriggers": {
      "keywords": ["list", "of", "keywords"],
      "intentPatterns": ["regex patterns"]
    },
    "fileTriggers": {
      "pathPatterns": ["path/to/files/**/*.ts"],
      "contentPatterns": ["import.*Prisma"]
    }
  }
}

Enforcement Levels

suggest: Skill appears as suggestion, doesn't block
block: Must use skill before proceeding (guardrail)

Use "block" for:

Preventing breaking changes (MUI v6→v7)
Critical database operations
Security-sensitive code

Use "suggest" for:

General best practices
Domain guidance
Code organization

Creating Your Own Skills

See the skill-developer skill for complete guide on:

Skill YAML frontmatter structure
Resource file organization
Trigger pattern design
Testing skill activation

Quick template:

---
name: my-skill
description: What this skill does
---

# My Skill Title

## Purpose

[Why this skill exists]

## When to Use This Skill

[Auto-activation scenarios]

## Quick Reference

[Key patterns and examples]

## Resource Files

- [topic-1.md](resources/topic-1.md)
- [topic-2.md](resources/topic-2.md)

Troubleshooting

Skill isn't activating

Check:

Is skill directory in
```
.claude/skills/
```
?
Is skill listed in
```
skill-rules.json
```
?
Do
```
pathPatterns
```
match your files?
Are hooks installed and working?
Is settings.json configured correctly?

Debug:

# Check skill exists
ls -la .claude/skills/

# Validate skill-rules.json
cat .claude/skills/skill-rules.json | jq .

# Check hooks are executable
ls -la .claude/hooks/*.sh

# Test hook manually
./.claude/hooks/skill-activation-prompt.sh