diegosouzapw Skill Activator: Make Your Skills Work
Purpose
Ensure skills are discovered and invoked at the right time by designing effective triggers and descriptions.
Why Skills Don't Get Called
| Problem | Cause | Solution |
|---|---|---|
| Never invoked | Description doesn't match user language | Add trigger phrases |
| Invoked at wrong time | Description too broad | Add "Use when" / "Don't use when" |
| Invoked but ignored | Low relevance signal | Make description more specific |
The Skill Description Formula
[What it does] + [When to use] + [Trigger phrases]
Bad Example
description: Code review skill
- Too vague
- No trigger phrases
- Doesn't say when to use
Good Example
description: >
Perform structured code review with security, performance, and
maintainability checks. Use when reviewing PRs, before merging,
or when user says "review", "check this code", or "find issues".
- Specific about what it does
- Clear when to use
- Multiple trigger phrases
Trigger Phrase Design
Match User Language
Think about how users actually ask for things:
| User Says | Skill Should Match |
|---|---|
| "review this" | code-review |
| "check for bugs" | code-review, debug |
| "is this secure?" | security-review |
| "make it faster" | performance-optimization |
| "clean this up" | refactoring |
Include Variations
description: >
... Use when user says "review", "check", "look at",
"find issues", "is this good", or "before merging".
The Description Template
---
name: {skill-name}
description: >
{One sentence: what this skill does}.
Use when {specific situations}.
Trigger phrases: "{phrase1}", "{phrase2}", "{phrase3}".
Don't use when {exclusions}.
---
Complete Example
---
name: api-design
description: >
Design RESTful APIs following best practices for naming,
versioning, and error handling. Use when creating new endpoints,
reviewing API design, or planning API changes. Trigger phrases:
"design API", "new endpoint", "REST structure", "API review".
Don't use for GraphQL or internal service communication.
---
Skill Audit Checklist
Review each skill against this checklist:
Discoverability
- Description is under 200 characters (for readability)
- First sentence clearly states purpose
- Contains 3+ trigger phrases
- Trigger phrases match real user language
Specificity
- "Use when" is specific, not generic
- "Don't use when" excludes wrong contexts
- Doesn't overlap significantly with other skills
Invocation Testing
- Tested with natural language requests
- Verified it's called in expected scenarios
- Verified it's NOT called in wrong scenarios
Skill Categories and Conventions
By Invocation Style
| Style | disable-model-invocation |
When to Use |
|---|---|---|
| Auto-invoked | false or omitted |
Should trigger automatically based on context |
| Manual only | true |
User must explicitly call with /skill-name |
When to Use Manual-Only
- Destructive operations (delete, reset)
- Long-running processes
- Operations with side effects
- User preference workflows
Debugging Skill Invocation
Skill Not Being Called?
- Check description - Does it match how users ask?
- Check triggers - Are trigger phrases natural?
- Check competition - Is another skill taking priority?
- Test directly - Call with
/skill-nameto verify it works
Skill Called at Wrong Time?
- Add exclusions - "Don't use when..."
- Narrow scope - Make "Use when" more specific
- Split skill - Maybe it's doing too many things
Skill Discovery Commands
List Available Skills
/help skills
Test Skill Matching
Ask Claude: "Which skill would you use for [scenario]?"
Force Skill Invocation
/skill-name [arguments]
Integration with Other Skills
- Use intent-first to clarify what the user needs
- Use delegation-triggers to decide if a skill or agent is appropriate
- Then activate the right skill based on the clarified intent