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