How to Fix an Agent Skill That Does Not Trigger: Description Design and Tests¶

For / Key Points

For: Skill authors whose SKILL.md exists but is not selected, or whose Skill triggers for unrelated requests

Key Points:

description is discovery metadata that tells the model what a Skill does and when to use it before the Skill body is loaded
Current requirements include a non-empty description of at most 1,024 characters with no XML tags; the body should stay under 500 lines
Replace intuition-driven rewrites with fixed positive, paraphrase, and negative evaluation cases

Diagnose the layer first¶

description is not the only reason a Skill is missing. Check in this order:

Whether the client discovered the Skill directory
Whether the SKILL.md YAML frontmatter is valid
Whether description distinguishes the intended request
Whether another Skill has overlapping responsibility
Whether the Skill body succeeds after selection

A Skill absent from the available list has a different problem from a listed Skill that is not selected. Investigate placement and frontmatter for the first case, and routing or overlap for the second.

Why description affects selection¶

Agent Skills use progressive disclosure.¹

flowchart LR
    A[name + description] -->|Relevant| B[SKILL.md body]
    B -->|Only when needed| C[references / scripts / assets]

At session start, the model primarily sees each Skill's name and description. A trigger rule placed only in the body cannot help the model decide to load that body.

The description therefore needs two elements:

what: What the Skill creates, inspects, or transforms
when: Which request, file, or situation calls for it

Anthropic's authoring guidance recommends specific descriptions containing what and when, written in the third person.²

Current requirements¶

---
name: invoice-review
description: Reviews invoice PDFs for totals, dates, vendor details, and missing fields. Use when the user asks to validate, compare, or summarize an invoice before approval.
---

# Invoice Review

## Workflow
1. Confirm the target file.
2. Extract required fields.
3. Recalculate totals.
4. Report discrepancies with page references.

The required frontmatter rules are:¹

Field	Requirement
`name`	At most 64 characters; lowercase letters, numbers, and hyphens only; no XML; cannot contain reserved words `anthropic` or `claude`
`description`	Non-empty; at most 1,024 characters; no XML; includes what the Skill does and when to use it

Anthropic recommends keeping the body under 500 lines. Move detail into references/ so it is read only when needed.²

Make what and when concrete¶

Too vague¶

description: Helps with documents.

It does not identify the operation, document type, or triggering situation.

More discriminating¶

description: Creates and revises product requirement documents with goals, scope, acceptance criteria, risks, and open questions. Use when the user asks to draft, review, or update a PRD or feature specification.

This states:

Actions: creates and revises
Object: product requirement documents
Output shape: goals, scope, acceptance criteria, and risks
Triggering requests: draft, review, update, PRD, or feature specification

Describe intent and output instead of listing keywords alone.

Separate overlapping Skills¶

Broadening a description to increase recall can create false triggers.

description: Analyzes data and creates reports. Use for files, metrics, business questions, or analysis.

If data quality, statistical analysis, and KPI reporting are separate Skills, define their boundaries:

description: Profiles tabular datasets for missing values, duplicate keys, schema drift, and invalid ranges. Use before analysis when the user asks to assess whether CSV, Excel, or database extracts are trustworthy.

description: Performs statistical tests, estimates uncertainty, and explains model assumptions. Use when the user asks whether an observed difference or relationship is statistically supported.

description: Produces recurring KPI reports from validated metric tables, including target variance and period-over-period change. Use when the user asks for a weekly, monthly, or quarterly performance report.

All three concern data, but their input state, question, and output differ. Compare descriptions whenever the wrong neighboring Skill wins.

Treat negative conditions as optional evidence-based boundaries¶

Some older patterns require a do-not clause in every description. Anthropic's mandatory rule is what plus when; a negative clause is not required.

Add one only when evaluation shows a real false trigger:

description: Reviews completed pull-request diffs for correctness, regressions, and missing tests. Use after code changes exist and the user asks for review. Do not use for implementing the change itself.

Long exclusion lists can suppress valid use. Add boundaries from observed failures, not speculation.

Test the language users actually type¶

An English description can map to requests in another language, but the specification does not guarantee every synonym or speech-to-text error. Put real user phrases into evaluations.

Should trigger:
- Check the total and tax on this invoice.
- List the vendor and due date.
- Verify the amount before payment.

Should not trigger:
- Design a new invoice template.
- Draft an email asking for a payment delay.
- Convert this PDF to PNG.

Do not enumerate every possible transcription error in the description. Add frequent observed variants to the evaluation set and one natural synonym when needed.

Build evaluation cases¶

Use at least three groups:

Group	Purpose
should trigger	Direct, typical request
paraphrase	Same intent without the obvious keyword
should not trigger	Similar language but a different responsibility

Store them as data:

{"input":"Check the total and tax on this invoice","expected":true,"case":"direct"}
{"input":"Make sure the numbers reconcile before payment","expected":true,"case":"paraphrase"}
{"input":"Create a new invoice template","expected":false,"case":"neighbor"}
{"input":"Convert this PDF to PNG","expected":false,"case":"unrelated"}

Anthropic's checklist recommends at least three evaluations and testing every model you expect to use.² Model changes can change routing behavior, so one successful run is not permanent proof.

Improve one variable at a time¶

Validate frontmatter syntax and required fields
Write what with concrete verbs, objects, and output
Write when with real requests and file types
Compare neighboring Skill descriptions and remove overlap
Run direct, paraphrase, and negative cases
Change one thing for an observed failure
Split detail if the body exceeds 500 lines

Record the description revision with evaluation results. Multiple simultaneous edits hide what improved selection.

Separate triggering from execution quality¶

If the Skill is selected but produces a poor result, changing its description does not fix execution.

Clarify step order in the body
Check required input files before work begins
Move repeatable code into scripts/
Put detail in references/ and state when to read it
Define stop conditions and fallback behavior for failed commands

The description is the entrance; the body is the execution contract. Evaluate them separately.

Security¶

Skills can contain scripts and tool instructions, not only prose. Anthropic recommends using Skills only from trusted authors or official sources.¹

For third-party Skills, inspect:

Files imported by SKILL.md
Commands and network calls under scripts/
Access to credentials, home directories, and Git configuration
Auto-approval or destructive behavior

Improving trigger accuracy does not justify broader execution permission.

Summary¶

When a Skill does not trigger, locate the failing layer: discovery, YAML, routing, or execution.

The description has three core jobs:

State exactly what the Skill does
State when to use it in terms of real requests
Distinguish it from neighboring Skills through evaluation

Once requirements and positive/negative cases are fixed, description design becomes a measurable routing problem instead of guesswork.