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.

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

Get these skills on Agensi

code-reviewer

Free

Run a structured code review on your recent changes without waiting for a teammate. This skill checks for security vulnerabilities (SQL injection, XSS, authentication bypasses), logic errors, edge cases, performance issues, and style violations.Findings are organized by severity: Critical, Warning, and Suggestion. Each finding includes the file, line number, a description of the issue, and a concrete fix. Use it as a first pass before peer review, or as your only reviewer on solo projects.

Get this skill

git-commit-writer

Free

Stop writing vague commit messages. This skill reads your actual staged diff and generates precise, informative commit messages following the Conventional Commits specification. It detects the commit type (feat, fix, refactor, docs, chore, etc.), identifies the scope from the changed files, flags breaking changes, and suggests splitting commits when multiple logical changes are staged. Works with any git repository.`

Get this skill

designing-hybrid-context-layers

$10

What This Skill DoesMost RAG systems fail silently — not because the model is weak, but because the retrieval architecture assumes every query is a lookup. This skill teaches you to design hybrid context layers that match the retrieval strategy to the query type, so your agent gets the right kind of context every time.Problems It SolvesThe RAG-for-everything trap — routing relational and temporal queries through vector search causes silent structural failure, expensive reranking, and answers that get worse as you add more context.Multi-hop blindness — "Which teams own services that depend on the deprecated API?" is an entity-traversal query, not a lookup. Vector RAG cannot answer it accurately.Missing organizational causation — questions like "What decisions led to this incident?" require a temporal event graph, not a document chunk.Context-reasoning mismatch — good context routed to a weak reasoning tier, or long context with no causal structure, produces hallucinations at scale.What You GetThe skill defines a three-layer context model:Layer 1 — Factual Store (Vector RAG): Single-fact, single-document point queries — the only case where RAG is structurally correct.Layer 2 — Relational Store (Knowledge Graph): Entity relationships, dependency chains, and multi-hop queries that require traversal across linked nodes.Layer 3 — Temporal/Episodic Store (Timeline Index): Event sequences, causal decision chains, and "how did we get here" queries that require timestamped structure.You also get a query router decision tree — a concrete classification step that routes every incoming query to the correct layer before any retrieval begins, plus a phased implementation roadmap for teams migrating from RAG-only systems.Who Should Use ThisTeams building AI agents over enterprise knowledge bases, architecture decision records, incident histories, or any organizational system where the agent must answer relational or causal questions — not just fact lookups.

Get this skill

Browse all skills

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.