metaskill-triggering

# Skill Trigger Optimization

## Critical Insight

**ONLY the `description` field affects triggering.** All other frontmatter fields affect execution, not discovery.

At startup, Claude loads ONLY `name` + `description` (not full SKILL.md body). Matching is keyword-based, not deeply semantic.

## The Trigger Formula

```yaml
description: <What it does> + <Specific actions> + <When to use it> + <Trigger keywords>
```

### Example Breakdown

```yaml
# ✅ OPTIMAL - Hits all four parts
description: Write and review tests following TDD and best practices. ALWAYS use this skill BEFORE writing or modifying any test code. Triggers on "test", "tests", "testing", "TDD", "test-driven", "pytest", "add tests", "write tests", "test this", "unit test", "integration test", "test coverage", "bug fix", "fix bug", "verify", "edge case", or when about to create/edit files in tests/ directory.
```

| Part | Example Content |
|------|-----------------|
| What it does | "Write and review tests following TDD and best practices" |
| Specific actions | "BEFORE writing or modifying any test code" |
| When to use | "when about to create/edit files in tests/ directory" |
| Trigger keywords | "test", "tests", "testing", "TDD", "pytest"... |

## Keyword Best Practices

### Include Variants

```yaml
# ✅ All forms of the word
"test", "tests", "testing", "test-driven"

# ❌ Only one form - misses variations
"testing"
```

### Include User Phrases

```yaml
# ✅ Actual phrases users say
"add tests", "write tests", "test this", "TDD this"

# ❌ Only formal terms
"implement unit tests"
```

### Include Action Verbs

```yaml
# ✅ Action-oriented
"write", "create", "fix", "review", "optimize"

# ❌ Passive/noun-only
"tests", "code", "documentation"
```

### Include Slang and Abbreviations

```yaml
# ✅ How users actually talk
"TDD", "mf" (if appropriate), common abbreviations

# ❌ Only formal language
"test-driven development methodology"
```

## Common Trigger Failures

### 1. Description Too Vague

```yaml
# ❌