Claude Integration Guide

FOR CLAUDE CODE: When a user asks you to integrate components from this showcase repository into their project, follow these instructions carefully.

---

Overview

This repository is a reference library of Claude Code infrastructure components. Users will ask you to help integrate specific pieces into their projects. Your role is to:

1. Ask clarifying questions about their project structure
2. Copy the appropriate files
3. Customize configurations for their setup
4. Verify the integration works correctly

Key Principle: ALWAYS ask before assuming project structure. What works for one project won't work for another.

---

Tech Stack Compatibility Check

CRITICAL: Before integrating a skill, verify the user's tech stack matches the skill requirements.

Frontend Skills

frontend-dev-guidelines requires:

• React (18+)
• MUI v7
• TanStack Query
• TanStack Router
• TypeScript

Before integrating, ask: "Do you use React with MUI v7?"

If NO:

The frontend-dev-guidelines skill is designed specifically for React + MUI v7. I can:
1. Help you create a similar skill adapted for [their stack] using this as a template
2. Extract the framework-agnostic patterns (file organization, performance, etc.)
3. Skip this skill if not relevant

Which would you prefer?

Backend Skills

backend-dev-guidelines requires:

• Node.js/Express
• TypeScript
• Prisma ORM
• Sentry

Before integrating, ask: "Do you use Node.js with Express and Prisma?"

If NO:

The backend-dev-guidelines skill is designed for Express/Prisma. I can:
1. Help you create similar guidelines adapted for [their stack] using this as a template
2. Extract the architecture patterns (layered architecture works for any framework)
3. Skip this skill

Which would you prefer?

Skills That Are Tech-Agnostic

These work for ANY tech stack:

• ✅ skill-developer - Meta-skill, no tech requirements
• ✅ route-tester - Only requires JWT cookie auth (framework agnostic)
• ✅ error-tracking - Sentry works with most stacks

---

General Integration Pattern

When user says: "Add [component] to my project"

1. Identify component type (skill/hook/agent/command)
2. CHECK TECH STACK COMPATIBILITY (for frontend/backend skills)
3. Ask about their project structure
4. Copy files OR adapt for their stack
5. Customize for their setup
6. Verify integration
7. Provide next steps

---

Integrating Skills

Step-by-Step Process

When user requests a skill (e.g., "add backend-dev-guidelines"):

1. Understand Their Project

ASK THESE QUESTIONS:

• "What's your project structure? Single app, monorepo, or multi-service?"
• "Where is your [backend/frontend] code located?"
• "What frameworks/technologies do you use?"

2. Copy the Skill

cp -r /path/to/showcase/.claude/skills/[skill-name] \\\\
      $CLAUDE_PROJECT_DIR/.claude/skills/

3. Handle skill-rules.json

Check if it exists:

ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json

If NO (doesn't exist):

• Copy the template from showcase
• Remove skills user doesn't want
• Customize for their project

If YES (exists):

• Read their current skill-rules.json
• Add the new skill entry
• Merge carefully to avoid breaking existing skills

4. Customize Path Patterns

CRITICAL: Update pathPatterns in skill-rules.json to match THEIR structure:

Example - User has monorepo:

{
  "backend-dev-guidelines": {
    "fileTriggers": {
      "pathPatterns": [
        "packages/api/src/**/*.ts",
        "packages/server/src/**/*.ts",
        "apps/backend/**/*.ts"
      ]
    }
  }
}

Example - User has single backend:

{
  "backend-dev-guidelines": {
    "fileTriggers": {
      "pathPatterns": [
        "src/**/*.ts",
        "backend/**/*.ts"
      ]
    }
  }
}

Safe Generic Patterns (when unsure):

{
  "pathPatterns": [
    "**/*.ts",          // All TypeScript files
    "src/**/*.ts",      // Common src directory
    "backend/**/*.ts"   // Common backend directory
  ]
}

5. Verify Integration

# Check skill was copied
ls -la $CLAUDE_PROJECT_DIR/.claude/skills/[skill-name]

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

Tell user: "Try editing a file in [their-backend-path] and the skill should activate."

---

Skill-Specific Notes

backend-dev-guidelines

• Tech Requirements: Node.js/Express, Prisma, TypeScript, Sentry
• Ask: "Do you use Express with Prisma?" "Where's your backend code?"
• If different stack: Offer to adapt using this as template
• Customize: pathPatterns
• Example paths: api/, server/, backend/, services/*/src/
• Adaptation tip: Architecture patterns (Routes→Controllers→Services) transfer to most frameworks

frontend-dev-guidelines

• Tech Requirements: React 18+, MUI v7, TanStack Query/Router, TypeScript
• Ask: "Do you use React with MUI v7?" "Where's your frontend code?"
• If different stack: Offer to create adapted version (Vue, Angular, etc.)
• Customize: pathPatterns + all framework-specific examples
• Example paths: frontend/, client/, web/, apps/web/src/
• Adaptation tip: File organization and performance patterns transfer, component code doesn't

route-tester

• Tech Requirements: JWT cookie-based authentication (framework agnostic)
• Ask: "Do you use JWT cookie-based authentication?"
• If NO: "This skill is designed for JWT cookies. Want me to adapt it for [their auth type] or skip it?"
• Customize: Service URLs, auth patterns
• Works with: Any backend framework using JWT cookies

error-tracking

• Tech Requirements: Sentry (works with most backends)
• Ask: "Do you use Sentry?" "Where's your backend code?"
• If NO Sentry: "Want to use this as template for [their error tracking]?"
• Customize: pathPatterns
• Adaptation tip: Error tracking philosophy transfers to other tools (Rollbar, Bugsnag, etc.)

skill-developer

• Tech Requirements: None!
• Copy as-is - meta-skill, fully generic, teaches skill creation for ANY tech stack

---

Adapting Skills for Different Tech Stacks

When user's tech stack differs from skill requirements, you have options:

Option 1: Adapt Existing Skill (Recommended)

When to use: User wants similar guidelines but for different tech

Process:

1. Copy the skill as a starting point:

   cp -r showcase/.claude/skills/frontend-dev-guidelines \\\\
         $CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines
   

2. Identify what needs changing:

   • Framework-specific code examples (React → Vue)
   • Library APIs (MUI → Vuetify/PrimeVue)
   • Import statements
   • Component patterns

3. Keep what transfers:

   • File organization principles
   • Performance optimization strategies
   • TypeScript standards
   • General best practices

4. Replace examples systematically:

   • Ask user for equivalent patterns in their stack
   • Update code examples to their framework
   • Keep the overall structure and sections

5. Update skill name and triggers:

   • Rename skill appropriately
   • Update skill-rules.json triggers for their stack
   • Test activation

Example - Adapting frontend-dev-guidelines for Vue:

I'll create vue-dev-guidelines based on the React skill structure:
- Replace React.FC → Vue defineComponent
- Replace useSuspenseQuery → Vue composables
- Replace MUI components → [their component library]
- Keep: File organization, performance patterns, TypeScript guidelines

This will take a few minutes. Sound good?

Option 2: Extract Framework-Agnostic Patterns

When to use: Stacks are very different, but core principles apply

Process:

1. Read through the existing skill

2. Identify framework-agnostic patterns:

   • Layered architecture (backend)
   • File organization strategies
   • Performance optimization principles
   • Testing strategies
   • Error handling philosophy

3. Create new skill with just those patterns

4. User can add framework-specific examples later

Example:

The backend-dev-guidelines uses Express, but the layered architecture
(Routes → Controllers → Services → Repositories) works for Django too.

I can create a skill with:
- Layered architecture pattern
- Separation of concerns principles
- Error handling best practices
- Testing strategies

Then you can add Django-specific examples as you establish patterns.

Option 3: Use as Reference Only

When to use: Too different to adapt, but user wants inspiration

Process:

1. User browses the existing skill
2. You help create a new skill from scratch
3. Use existing skill's structure as a template
4. Follow modular pattern (main + resource files)

What Usually Transfers Across Tech Stacks

Architecture & Organization:

• ✅ Layered architecture (Routes/Controllers/Services pattern)
• ✅ Separation of concerns
• ✅ File organization strategies (features/ pattern)
• ✅ Progressive disclosure (main + resource files)
• ✅ Repository pattern for data access

Development Practices:

• ✅ Error handling philosophy
• ✅ Input validation importance
• ✅ Testing strategies
• ✅ Performance optimization principles
• ✅ TypeScript best practices

Framework-Specific Code:

• ❌ React hooks → Don't transfer to Vue/Angular
• ❌ MUI components → Different component libraries
• ❌ Prisma queries → Different ORM syntax
• ❌ Express middleware → Different framework patterns
• ❌ Routing implementations → Framework-specific

When to Recommend Adaptation vs Skipping

Recommend adaptation if:

• User wants similar guidelines for their stack
• Core patterns apply (layered architecture, etc.)
• User has time to help with framework-specific examples

Recommend skipping if:

• Stacks are completely different
• User doesn't need those patterns
• Would take too long to adapt
• User prefers creating from scratch

---

Integrating Hooks

Essential Hooks (Always Safe to Copy)

skill-activation-prompt (UserPromptSubmit)

Purpose: Auto-suggests skills based on user prompts

Integration (NO customization needed):

# Copy both files
cp showcase/.claude/hooks/skill-activation-prompt.sh \\\\
   $CLAUDE_PROJECT_DIR/.claude/hooks/
cp showcase/.claude/hooks/skill-activation-prompt.ts \\\\
   $CLAUDE_PROJECT_DIR/.claude/hooks/

# Make executable
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh

# Install dependencies if needed
if [ -f "showcase/.claude/hooks/package.json" ]; then
  cp showcase/.claude/hooks/package.json \\\\
     $CLAUDE_PROJECT_DIR/.claude/hooks/
  cd $CLAUDE_PROJECT_DIR/.claude/hooks && npm install
fi

Add to settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
          }
        ]
      }
    ]
  }
}

This hook is FULLY GENERIC - works anywhere, no customization needed!

post-tool-use-tracker (PostToolUse)

Purpose: Tracks file changes for context management

Integration (NO customization needed):

# Copy file
cp showcase/.claude/hooks/post-tool-use-tracker.sh \\\\
   $CLAUDE_PROJECT_DIR/.claude/hooks/

# Make executable
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh

Add to settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"
          }
        ]
      }
    ]
  }
}

This hook is FULLY GENERIC - auto-detects project structure!

---

Optional Hooks (Require Heavy Customization)

tsc-check.sh and trigger-build-resolver.sh (Stop hooks)

⚠️ WARNING: These hooks are configured for a specific multi-service monorepo structure.

Before integrating, ask:

1. "Do you have a monorepo with multiple TypeScript services?"
2. "What are your service directory names?"
3. "Where are your tsconfig.json files located?"

For SIMPLE projects (single service):

• RECOMMEND SKIPPING these hooks
• They're overkill for single-service projects
• User can run tsc --noEmit manually instead

For COMPLEX projects (multi-service monorepo):

1. Copy the files
2. MUST EDIT tsc-check.sh - find this section:

case "$repo" in
    email|exports|form|frontend|projects|uploads|users|utilities|events|database)
        echo "$repo"
        return 0
        ;;
esac

3. Replace with USER'S actual service names:

case "$repo" in
    api|web|auth|payments|notifications)  # ← User's services
        echo "$repo"
        return 0
        ;;
esac

4. Test manually before adding to settings.json:

./.claude/hooks/tsc-check.sh

IMPORTANT: If this hook fails, it will block Stop events. Only add if you're sure it works for their setup.

---

Integrating Agents

Agents are STANDALONE - easiest to integrate!

Standard Agent Integration

# Copy the agent file
cp showcase/.claude/agents/[agent-name].md \\\\
   $CLAUDE_PROJECT_DIR/.claude/agents/

That's it! Agents work immediately, no configuration needed.

Check for Hardcoded Paths

Some agents may reference paths. Before copying, read the agent file and check for:

• ~/git/old-project/ → Should be $CLAUDE_PROJECT_DIR or .
• /root/git/project/ → Should be $CLAUDE_PROJECT_DIR or .
• Hardcoded screenshot paths → Ask user where they want screenshots

If found, update them:

sed -i 's|~/git/old-project/|.|g' $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
sed -i 's|/root/git/.*PROJECT.*DIR|$CLAUDE_PROJECT_DIR|g' \\\\
    $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md

Agent-Specific Notes

auth-route-tester / auth-route-debugger:

• Requires JWT cookie-based authentication in user's project
• Ask: "Do you use JWT cookies for auth?"
• If NO: "These agents are for JWT cookie auth. Skip them or want me to adapt?"

frontend-error-fixer:

• May reference screenshot paths
• Ask: "Where should screenshots be saved?"

All other agents:

• Copy as-is, they're fully generic

---

Integrating Slash Commands

# Copy command file
cp showcase/.claude/commands/[command].md \\\\
   $CLAUDE_PROJECT_DIR/.claude/commands/

Customize Paths

Commands may reference dev docs paths. Check and update:

dev-docs and dev-docs-update:

• Look for dev/active/ path references
• Ask: "Where do you want dev documentation stored?"
• Update paths in the command files

route-research-for-testing:

• May reference service paths
• Ask about their API structure

---

Common Patterns & Best Practices

Pattern: Asking Ab