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
- 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".
- Missing Keyword Variants
❌ FAILS - Misses "tests" and "testing"
description: Write test code...
✅ WORKS - All variants
description: ...triggers on "test", "tests", "testing"...
- 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.
- 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
- 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.
- 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)
- Maximum Description Length
~1024 characters. Prioritize keywords over prose.
- Test Your Triggers
Use the metaskill-trigger-tester agent to probe skill triggering.
Debugging Non-Triggering Skills
-
Check description exists - Missing = never triggers
-
Check disable-model-invocation
-
true blocks auto-discovery
-
Grep for keywords - Are user's words in description?
-
Check variants - "testing" present but not "test"?
-
Add explicit "Use when" clause - Often missing
-
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