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?

1. Check description - Does it match how users ask?
2. Check triggers - Are trigger phrases natural?
3. Check competition - Is another skill taking priority?
4. Test directly - Call with /skill-name to verify it works

Skill Called at Wrong Time?

1. Add exclusions - "Don't use when..."
2. Narrow scope - Make "Use when" more specific
3. 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