---

name: metaskill-triggering description: Optimize skill triggers and descriptions for reliable activation. Use when skill is not triggering, optimizing trigger keywords, writing frontmatter, debugging activation, or when user mentions "trigger", "frontmatter", "description", "skill not triggering", "optimize trigger", "skill won't fire", "skill activation", "trigger keywords".

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

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

Example Breakdown

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

Keyword Best Practices

Include Variants

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

# ❌ Only one form - misses variations
"testing"

Include User Phrases

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

# ❌ Only formal terms
"implement unit tests"

Include Action Verbs

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

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

Include Slang and Abbreviations

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

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

Common Trigger Failures

1. Description Too Vague

Copy# ❌ 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

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

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

3. No "Use When" Clause

Copy# ❌ 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

Copy# ❌ 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

Execution-Related (No Trigger Effect)

Pro Tips

1. Self-Recognition

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

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

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