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-name
```
to 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

Awesome-omni-skill skill-activator