How to Write a SKILL.md Description That Actually Triggers

You write a skill, drop it in your skills directory (whether Claude Code, OpenClaw, or another SKILL.md agent), and ask the agent to do exactly what the skill is for. Nothing happens. You rewrite the instructions. Still nothing.

The problem is almost never your instructions. It's your description field. The description is what the agent reads to decide whether to activate your skill. If it's vague, too broad, or doesn't match how you actually phrase requests, the skill won't trigger.

> Quick Answer: A good SKILL.md description explicitly states what the skill does and includes trigger phrases using "Use when" to guide the agent on activation, avoiding vagueness or overly narrow definitions.

When you start a Claude Code session, the agent loads the frontmatter (name and description) from every skill in your skills directory. It does not read the full instructions yet.

As you make requests, the agent matches your input against those descriptions. If your request matches a skill's description, the agent loads the full SKILL.md and follows the instructions.

This means the description is a filter. A bad description either never matches (skill never triggers) or matches too often (skill triggers when it shouldn't).

Too vague: "Helps with code quality." When does the agent use this? On every code-related request? That's too broad.

Too narrow: "Use only when the user types the exact phrase 'review my code for security issues.'" Nobody phrases requests that precisely.

Missing trigger phrases: The description only mentions one way to ask for the task. But developers might say "review this," "check my code," "look for bugs," "audit this PR," or "scan for security issues." If the description doesn't cover these variations, the skill misses legitimate requests.

Start with what the skill does in one sentence. Then add explicit trigger phrases with "Use when."

Bad: ```yaml description: Code review skill ```

Better: ```yaml description: Reviews code for bugs, security issues, and best practices. ```

Best: ```yaml description: Reviews code for bugs, security vulnerabilities, performance issues, and style violations. Use when the user asks to review code, check a PR, audit changes, scan for bugs, or mentions code review. ```

The "Use when" clause is critical. It tells the agent exactly which user requests should activate this skill.

For skills that might falsely activate on similar requests, add "Do not use when" clauses:

```yaml description: Generates unit tests for source code. Use when the user asks to write tests, add test coverage, or create test files. Do not use when the user asks to run existing tests or fix failing tests. ```

This prevents the test-writing skill from activating when you just want to run your test suite.

After writing a description, test it with both direct and indirect requests:

Direct: "Review my code" (should trigger a code review skill) Indirect: "I changed the auth module, can you check it?" (should also trigger) Negative: "Run the tests" (should NOT trigger a code review skill)

If the skill doesn't trigger on indirect requests, add more trigger phrases. If it triggers on negative cases, add "Do not use when" clauses.

Remember that every skill can be invoked directly with `/skill-name` regardless of the description. If you're having trouble with automatic discovery, you can always invoke manually while you refine the description.

For the full SKILL.md specification, see our format reference. To see examples of well-written descriptions, browse skills on Agensi and read their descriptions.