A skill that fires at the wrong time is as useless as one that never fires. Design activation like you'd design a cron expression: specific, testable, boundaried.
When to Use
- Debugging skills that don't fire
- Two skills claiming the same trigger
- Skills firing on unrelated queries
- Designing a new suite with multiple related skills
The Activation Signal Stack
The model matches your skill against user queries using:
- Name — weak signal
- Description first sentence — strong signal, this is the "what"
- "Use this skill when" line — strongest signal, the "when"
- "Activate when" keyword list — pattern match against query phrases
Invest most in (3) and (4).
Four Activation Patterns
1. Error-Driven
Skill fires when user pastes or describes an error:
description: |
Decode Java stack traces and suggest root causes.
Use this skill when user shares a stack trace, exception, or runtime error in Java.
Activate when: Exception, NullPointerException, stack trace, Caused by, Java error, runtime crash.
Include the literal tokens that appear in errors. Users paste them verbatim.
2. Intent-Driven
Skill fires when user expresses a goal:
description: |
Refactor code to extract methods, rename, and improve structure without changing behavior.
Use this skill when user asks to refactor, clean up, or restructure existing code.
Activate when: refactor, clean up, extract method, rename, restructure, DRY up, improve this code.
Match imperative verbs and goal phrases.
3. Tool/Technology-Driven
Skill fires when the user mentions a specific tool:
description: |
Configure Next.js App Router — server components, server actions, middleware, caching.
Use this skill when the user is working with Next.js App Router, specifically app/ directory routes.
Activate when: Next.js, App Router, server component, server action, app/ directory, use server.
Name the technology and its key concepts; matches work well.
4. Workflow-Driven
Skill fires during a known phase of work:
description: |
Pre-release checklist for a production deploy — changelog, version bump, migration safety, smoke tests.
Use this skill when user is about to deploy to production, cut a release, or tag a version.
Activate when: deploy to prod, release, version bump, production release, pre-release check.
Workflow skills need to be clearly scoped to that phase or they fire constantly.
Disambiguating Overlapping Skills
If two skills could both fire on "help me write a test", they compete. Differentiate in the description itself.
Before (ambiguous)
- Skill A: "Generate tests for JavaScript code."
- Skill B: "Generate tests for React components."
On "write a test for MyComponent", both fire. Model picks randomly.
After (disambiguated)
- Skill A: "Generate tests for JavaScript code. Use when code is non-React (Node, utilities, backend). Activate: test, unit test. NOT for React components — use react-test-generator instead."
- Skill B: "Generate tests for React components with Testing Library. Use for JSX/TSX component tests. Activate: React test, component test, Testing Library. NOT for backend — use js-test-generator."
The "NOT for..." line is a powerful routing hint.
Over-Activation
Symptom: skill fires on nearly every query. Cause: description too broad.
Too broad
description: |
Help with coding tasks.
Activate when: code, programming, development.
Fix — narrow the WHEN
description: |
Help refactoring existing code for readability — NOT for new code generation, bug fixing, or debugging.
Use this skill when user specifically asks to refactor, clean up, or restructure.
Activate when: refactor, clean up, extract method, DRY up, improve readability.
"NOT for X" sentences are explicit guards. Use them.
Under-Activation
Symptom: skill has clear use case but never fires. Cause: description misses the user's vocabulary.
Fix — expand keywords
Audit real queries users send. Add their exact phrasings:
Activate when:
- merge conflict, resolve conflicts # jargon
- CONFLICT markers, <<<<<<< HEAD # literal tokens
- git says there's a conflict # natural phrasing
- merge failed, can't merge # error paraphrases
- rebase stopped, rebase conflict # related workflows
Mix jargon, error strings, and natural phrasings.
Negative Triggers
Some patterns explicitly should NOT activate the skill. Call them out:
description: |
Write SQL migrations safely.
Use for: ALTER TABLE, new columns with defaults, adding indexes on prod tables.
DO NOT use for: read-only queries (use sql-query-helper), ORM model changes, new tables from scratch.
Activate when: ALTER TABLE, add column, migration, safe migration, Postgres lock, online DDL.
Explicit negatives reduce competition with nearby skills.
Testing Activation
See the skill-testing companion skill. Briefly:
- Compile a list of 10+ realistic user queries that SHOULD activate
- Compile 10+ queries that SHOULD NOT
- Run against your skill loader; measure precision & recall
- Iterate description until both are high
Common Failure Modes
- Generic verbs —
help,handle,manage. Match too broadly - Missing error strings — users paste exceptions; you don't list them
- Skill name matches a common word —
tests,bugs,config - Duplicated descriptions across related skills — model sees ties, picks randomly
- No WHEN clause — description is all WHAT, zero specificity on triggers
Best Practices
- Write the description with real user queries in mind — paste examples in a notebook next to it
- Include both jargon AND natural phrasing in keywords
- For each related skill, include an explicit "NOT for X" guard
- Test with a query suite — measure precision and recall
- Iterate: bad activation is the #1 reason a skill feels "broken"
- When in doubt, narrow — an under-firing skill is fixable; an over-firing skill erodes trust