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.

How discovery works

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).

Common mistakes

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.

How to write a good description

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

Bad:

description: Code review skill

Better:

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

Best:

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.

Negative triggers

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

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.

Testing your description

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.

The manual fallback

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.