skills-auto-activation
Use when skills aren't activating reliably - covers official solutions (better descriptions) and custom hook system for deterministic skill activation
When & Why to Use This Skill
This Claude skill optimizes agentic workflows by ensuring reliable and deterministic skill activation. It provides a comprehensive framework—ranging from optimized metadata descriptions to advanced custom hook systems—to solve the common issue of skills failing to trigger automatically, thereby streamlining developer productivity and enforcing consistent coding patterns across large codebases.
Use Cases
- Case 1: Automating domain-specific skill activation in large-scale projects to ensure architectural patterns (like Repository or Service patterns) are followed without manual intervention.
- Case 2: Implementing a custom hook system to intercept user prompts and inject context-aware skill reminders for high-priority tasks such as TDD, security audits, or API documentation.
- Case 3: Reducing workflow friction in complex development environments by using keyword and intent-based triggers to eliminate the need for repetitive manual '/use' commands.
| name | skills-auto-activation |
|---|---|
| description | Use when skills aren't activating reliably - covers official solutions (better descriptions) and custom hook system for deterministic skill activation |
Hyperpowers includes: Auto-activation hook at hooks/user-prompt-submit/10-skill-activator.js
Prerequisites:
- Skills properly configured (name, description, SKILL.md)
- Code execution enabled (Settings > Capabilities)
- Skills toggled on (Settings > Capabilities)
Symptoms:
- Keywords from skill descriptions present → skill not used
- Working on files that should trigger skills → nothing
- Skills exist but sit unused
Community reports:
- GitHub Issue #9954: "Skills not available even if explicitly enabled"
- "Claude knows it should use skills, but it's not reliable"
- Skills activation is "not reliable yet"
Root cause: Skills rely on Claude recognizing relevance (not deterministic)
## Level 1: Official Solutions (Start Here)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:
- UserPromptSubmit hook analyzes prompt before Claude sees it
- Matches keywords, intent patterns, file paths
- Injects skill activation reminder into context
- 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
- Keyword Triggers - Simple string matching (case insensitive)
- Intent Pattern Triggers - Regex for actions + objects
- File Path Triggers - Glob patterns for file paths
- 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
### Before Hook System- Skills sit unused despite perfect keywords
- Manual "/use skill-name" every time
- Inconsistent patterns across codebase
- Time spent fixing "creative interpretations"
After Hook System
- Skills activate automatically and reliably
- Consistent patterns enforced
- Claude self-checks before showing code
- "Night and day difference"
Real user: "Skills went from 'expensive decorations' to actually useful"
## Hook System Limitations- Requires hook system - Not built into Claude Code
- Maintenance overhead - skill-rules.json needs updates
- May over-activate - Too many skills overwhelm context
- Not perfect - Still relies on Claude using activated skills
Considerations
Token usage:
- Activation reminder adds ~50-100 tokens per prompt
- Multiple skills add more tokens
- Use priorities to limit activation
Performance:
- Hook adds ~100-300ms to prompt processing
- Acceptable for quality improvement
- Optimize regex patterns if slow
Maintenance:
- Update rules when adding new skills
- Review activation logs monthly
- Refine patterns based on misses
Use Model Context Protocol to provide skills as context.
Pros: Built into Claude system Cons: Still not deterministic, same activation issues
Approach 2: Custom System Prompt
Modify Claude's system prompt to always check certain skills.
Pros: Works without hooks Cons: Limited to Pro plan, can't customize per-project
Approach 3: Manual Discipline
Always explicitly request skill usage.
Pros: No setup required Cons: Tedious, easy to forget, doesn't scale
Approach 4: Skill Consolidation
Combine all guidelines into CLAUDE.md.
Pros: Always loaded Cons: Violates progressive disclosure, wastes tokens
Recommendation: Level 3 (hooks) for large projects, Level 1 for smaller projects
## Rules That Have No Exceptions- Try Level 1 first → Better descriptions and explicit requests before building hooks
- Observe before building → Watch which prompts should activate skills
- Start with keywords → Add complexity incrementally (keywords → intent → files)
- Keep hook fast (<1 second) → Don't block prompt processing
- Maintain skill-rules.json → Update when skills change
Common Excuses
All of these mean: Try Level 1 first, then decide.
- "Skills should just work automatically" (They should, but don't reliably - workaround needed)
- "Hook system too complex" (Setup takes 2 hours, saves hundreds of hours)
- "I'll manually specify skills" (You'll forget, it gets tedious)
- "Improving descriptions will fix it" (Helps, but not deterministic)
- "This is overkill" (Maybe - start Level 1, upgrade if needed)
- Tried improving skill descriptions (Level 1)
- Tried explicit skill requests (Level 1)
- Checked all settings are enabled
- Observed which prompts should activate skills
- Identified patterns in failures
- Project large enough to justify hook overhead
- Have time for 2-hour setup + ongoing maintenance
If Level 1 works: Don't build hook system
If Level 1 insufficient: Build hook system (Level 3)
**This skill covers:** Skill activation strategiesRelated skills:
- hyperpowers:building-hooks (how to build hook system)
- hyperpowers:using-hyper (when to use skills generally)
- hyperpowers:writing-skills (creating skills that activate well)
This skill enables:
- Consistent enforcement of patterns
- Automatic guideline checking
- Reliable skill usage across sessions
Hyperpowers includes: Auto-activation hook at hooks/user-prompt-submit/10-skill-activator.js
Official documentation:
When stuck:
- Skills still not activating → Check Settings > Capabilities
- Hook not working → Check ~/.claude/logs/hooks.log
- Over-activation → Reduce keywords, increase priority thresholds
- Under-activation → Add more keywords, broaden intent patterns