skills-auto-activation

1. Improve Skill Descriptions

❌ Bad:

name: backend-dev
description: Helps with backend development

✅ Good:

name: backend-dev-guidelines
description: Use when creating API routes, controllers, services, or repositories in backend - enforces TypeScript patterns, error handling with Sentry, and Prisma repository pattern

Key elements:

• Specific keywords: "API routes", "controllers", "services"
• When to use: "Use when creating..."
• What it enforces: Patterns, error handling

2. Be Explicit in Requests

Instead of: "How do I create an endpoint?"

Try: "Use my backend-dev-guidelines skill to create an endpoint"

Result: Works, but tedious

3. Check Settings

• Settings > Capabilities > Enable code execution
• Settings > Capabilities > Toggle Skills on
• Team/Enterprise: Check org-level settings

Level 2: Skill References (Moderate)

Reference skills in CLAUDE.md:

## When Working on Backend

Before making changes:
1. Check `/skills/backend-dev-guidelines` for patterns
2. Follow repository pattern for database access

The backend-dev-guidelines skill contains complete examples.

Pros: No custom code Cons: Claude still might not check

Level 3: Custom Hook System (Advanced)

How it works:

1. UserPromptSubmit hook analyzes prompt before Claude sees it
2. Matches keywords, intent patterns, file paths
3. Injects skill activation reminder into context
4. Claude sees "🎯 USE these skills" before processing

Result: "Night and day difference" - skills consistently used

Architecture

User submits prompt
    ↓
UserPromptSubmit hook intercepts
    ↓
Analyze prompt (keywords, intent, files)
    ↓
Check skill-rules.json for matches
    ↓
Inject activation reminder
    ↓
Claude sees: "🎯 USE these skills: ..."
    ↓
Claude loads and uses relevant skills

Configuration: skill-rules.json

{
  "backend-dev-guidelines": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["backend", "controller", "service", "API", "endpoint"],
      "intentPatterns": [
        "(create|add|build).*?(route|endpoint|controller|service)",
        "(how to|pattern).*?(backend|API)"
      ]
    },
    "fileTriggers": {
      "pathPatterns": ["backend/src/**/*.ts", "server/**/*.ts"],
      "contentPatterns": ["express\\.Router", "export.*Controller"]
    }
  },
  "test-driven-development": {
    "type": "process",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["test", "TDD", "testing"],
      "intentPatterns": [
        "(write|add|create).*?(test|spec)",
        "test.*(first|before|TDD)"
      ]
    },
    "fileTriggers": {
      "pathPatterns": ["**/*.test.ts", "**/*.spec.ts"],
      "contentPatterns": ["describe\\(", "it\\(", "test\\("]
    }
  }
}

Trigger Types

1. Keyword Triggers - Simple string matching (case insensitive)
2. Intent Pattern Triggers - Regex for actions + objects
3. File Path Triggers - Glob patterns for file paths
4. Content Pattern Triggers - Regex in file content

Hook Implementation (High-Level)

#!/usr/bin/env node
// ~/.claude/hooks/user-prompt-submit/skill-activator.js

const fs = require('fs');
const path = require('path');

// Load skill rules
const rules = JSON.parse(fs.readFileSync(
  path.join(process.env.HOME, '.claude/skill-rules.json'), 'utf8'
));

// Read prompt from stdin
let promptData = '';
process.stdin.on('data', chunk => promptData += chunk);

process.stdin.on('end', () => {
    const prompt = JSON.parse(promptData);

    // Analyze prompt for skill matches
    const activatedSkills = analyzePrompt(prompt.text);

    if (activatedSkills.length > 0) {
        // Inject skill activation reminder
        const context = `
🎯 SKILL ACTIVATION CHECK

Relevant skills for this prompt:
${activatedSkills.map(s => `- **${s.skill}** (${s.priority} priority)`).join('\n')}

Check if these skills should be used before responding.
`;

        console.log(JSON.stringify({
            decision: 'approve',
            additionalContext: context
        }));
    } else {
        console.log(JSON.stringify({ decision: 'approve' }));
    }
});

function analyzePrompt(text) {
    // Match against all skill rules
    // Return list of activated skills with priorities
}

For complete working implementation: See resources/hook-implementation.md

Progressive Enhancement

Phase 1 (Week 1): Basic keyword matching

{"keywords": ["backend", "API", "controller"]}

Phase 2 (Week 2): Add intent patterns

{"intentPatterns": ["(create|add).*?(route|endpoint)"]}

Phase 3 (Week 3): Add file triggers

{"fileTriggers": {"pathPatterns": ["backend/**/*.ts"]}}

Phase 4 (Ongoing): Refine based on observation