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

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:

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

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