skill-activator

# Skill Activator: Make Your Skills Work

## Purpose

Ensure skills are discovered and invoked at the right time by designing effective triggers and descriptions.

## Why Skills Don't Get Called

| Problem | Cause | Solution |
|---------|-------|----------|
| Never invoked | Description doesn't match user language | Add trigger phrases |
| Invoked at wrong time | Description too broad | Add "Use when" / "Don't use when" |
| Invoked but ignored | Low relevance signal | Make description more specific |

## The Skill Description Formula

```
[What it does] + [When to use] + [Trigger phrases]
```

### Bad Example
```yaml
description: Code review skill
```
- Too vague
- No trigger phrases
- Doesn't say when to use

### Good Example
```yaml
description: >
  Perform structured code review with security, performance, and
  maintainability checks. Use when reviewing PRs, before merging,
  or when user says "review", "check this code", or "find issues".
```
- Specific about what it does
- Clear when to use
- Multiple trigger phrases

## Trigger Phrase Design

### Match User Language

Think about how users actually ask for things:

| User Says | Skill Should Match |
|-----------|-------------------|
| "review this" | code-review |
| "check for bugs" | code-review, debug |
| "is this secure?" | security-review |
| "make it faster" | performance-optimization |
| "clean this up" | refactoring |

### Include Variations

```yaml
description: >
  ... Use when user says "review", "check", "look at",
  "find issues", "is this good", or "before merging".
```

## The Description Template

```markdown
---
name: {skill-name}
description: >
  {One sentence: what this skill does}.
  Use when {specific situations}.
  Trigger phrases: "{phrase1}", "{phrase2}", "{phrase3}".
  Don't use when {exclusions}.
---
```

### Complete Example

```markdown
---
name: api-design
description: >
  Design RESTful APIs following best practices for naming,
  versioning, and error handling. Use when creating ne