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

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

Example Breakdown

# ✅ 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

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

# ❌ Only one form - misses variations
"testing"

Include User Phrases

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

# ❌ Only formal terms
"implement unit tests"

Include Action Verbs

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

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

Include Slang and Abbreviations

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

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

Common Trigger Failures

1. Description Too Vague

# ❌ FAILS - No specific keywords
description: Helps with testing stuff.

# ✅ WORKS - Specific and keyword-rich
description: Write and run pytest tests. Use when creating tests, fixing test failures, or when user mentions "test", "pytest", "fixture", "mock".

2. Missing Keyword Variants

# ❌ FAILS - Misses "tests" and "testing"
description: Write test code...

# ✅ WORKS - All variants
description: ...triggers on "test", "tests", "testing"...

3. No "Use When" Clause

# ❌ FAILS - Claude doesn't know WHEN to use it
description: Handles test code.

# ✅ WORKS - Clear trigger conditions
description: ...Use when writing tests, reviewing test code, or debugging test failures.

4. Missing User Phrases

# ❌ FAILS - Formal terms only
description: Implements unit test suites.

# ✅ WORKS - Includes casual phrases
description: ...triggers on "add tests", "write tests", "test this", "TDD this mf"...

Frontmatter Fields Reference

Triggering-Related

| Field | Effect on Triggering | |-------|---------------------| | name | Used with /skill-name invocation | | description | ONLY field that affects auto-triggering | | disable-model-invocation | true = blocks ALL auto-discovery |

Execution-Related (No Trigger Effect)

| Field | Purpose | |-------|---------| | allowed-tools | Restricts tools available during skill | | skills | Makes other skills available (for groups) |

Pro Tips

1. Self-Recognition

Claude should trigger skills when IT plans actions, not just when user says keywords:

# ✅ Includes Claude's planned actions
description: ...or when about to create/edit files in tests/ directory.

2. Negative Keywords (What NOT to Trigger On)

Can't specify directly, but make description specific enough:

# ✅ Specific enough to avoid false positives
description: Write PYTEST tests for Python code...
# Won't trigger on "test the API endpoint" (manual testing)

3. Maximum Description Length

~1024 characters. Prioritize keywords over prose.

4. Test Your Triggers

Use the metaskill-trigger-tester agent to probe skill triggering.

Debugging Non-Triggering Skills

1. Check description exists - Missing = never triggers
2. Check disable-model-invocation - true blocks auto-discovery
3. Grep for keywords - Are user's words in description?
4. Check variants - "testing" present but not "test"?
5. Add explicit "Use when" clause - Often missing
6. Add user phrases - Include how users actually talk

Related Skills

• For naming conventions, see /metaskill-naming
• For skill structure and writing, see /metaskill-authoring
• For skill group pattern, see /metaskill-grouping
• For plugin packaging and placement, see /metaskill-packaging
• To test triggers, use the metaskill-trigger-tester agent

Reference Files

• references/frontmatter-fields.md - All frontmatter fields
• references/description-patterns.md - Good and bad examples