skills-auto-activation

<skill_overview>
Skills often don't activate despite keywords; make activation reliable through better descriptions, explicit triggers, or custom hooks.
</skill_overview>

<rigidity_level>
HIGH FREEDOM - Choose solution level based on project needs (Level 1 for simple, Level 3 for complex). Hook implementation is flexible pattern, not rigid process.
</rigidity_level>

<quick_reference>
| Level | Solution | Effort | Reliability | When to Use |
|-------|----------|--------|-------------|-------------|
| 1 | Better descriptions + explicit requests | Low | Moderate | Small projects, starting out |
| 2 | CLAUDE.md references | Low | Moderate | Document patterns |
| 3 | Custom hook system | High | Very High | Large projects, established patterns |

**Hyperpowers includes:** Auto-activation hook at `hooks/user-prompt-submit/10-skill-activator.js`
</quick_reference>

<when_to_use>
Use this skill when:
- Skills you created aren't being used automatically
- Need consistent skill activation across sessions
- Large codebases with established patterns
- Manual "/use skill-name" gets tedious

**Prerequisites:**
- Skills properly configured (name, description, SKILL.md)
- Code execution enabled (Settings > Capabilities)
- Skills toggled on (Settings > Capabilities)
</when_to_use>

<the_problem>
## What Users Experience

**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)
</the_problem>

<solution_levels>
## Level 1: Official Solutions (Start Here)

### 1. Improve Skill Descriptions

❌ **Bad:**
```yaml
name: backend-dev
description: Helps with backend development
```

✅ **Good:**
```yaml
name: backend