You wrote a skill, put the folder in the right place, started a new session, asked for exactly the thing the skill does, and the agent ignored it. This is the most common complaint about Agent Skills, and the cause is almost always the same line: the description in the frontmatter.
This guide explains why that one field decides whether a skill runs, and how to write it so it does.
Why the description matters more than the body
Agent Skills load in stages. When a session starts, the app reads the frontmatter of every installed skill and puts each name and description into the agent's context. That costs about a hundred tokens per skill, which is why you can install dozens of them. The body of SKILL.md, and any reference files, stay on disk.
When you make a request, the agent compares it with those descriptions and decides whether one of them fits. Only then does it open the skill and read the instructions. So the agent never sees your carefully written steps unless the description convinces it first. A brilliant body behind a vague description is a skill that never runs.
The two-part pattern
Good descriptions follow the same shape: what the skill does, then when to use it.
description: Writes release notes from git history and merged pull requests, grouped into
Features, Fixes and Breaking changes in Keep a Changelog format. Use when the user asks for
release notes, a changelog entry, a version summary or "what shipped since the last tag".
The first sentence names the job and the output. The second sentence lists the requests that should load it, in the words people actually type. Both halves matter: the first helps the agent recognise a match, the second gives it the vocabulary to match on.
Keep it on one line in the file (YAML folds long lines fine if you indent continuation lines, but some loaders read only the first line of a multi-line value). Stay under 1,024 characters, the limit in the specification. Between 150 and 500 characters is the range where most well-performing skills sit.
Write in third person
The description is injected into the agent's system prompt alongside other instructions. "I can help you write release notes" reads oddly there and can confuse the agent about who is speaking. "You can use this to write release notes" has the same problem. Write it like a catalogue entry:
"Generates…", "Reviews…", "Extracts…", "Converts…"
not "I generate…", "Helps you…", "This skill will…"
Name concrete triggers
Agents match on meaning, but concrete words make the match much more reliable. Include:
File types and formats: PDF, CSV, .xlsx, Dockerfile, OpenAPI, .mdc.
Tools and commands: git, Terraform, Playwright, pytest, psql.
The nouns of the task: invoice, changelog, migration, meta description.
Phrases users say: "what changed", "clean up this data", "is this accessible".
Compare these two descriptions for the same skill:
Vague
description: Helps with data tasks.
Specific
description: Profiles and cleans CSV and Excel files: detects types, duplicates, missing
values and inconsistent dates, then writes a cleaned copy and a change log. Use when the
user shares a spreadsheet or CSV, asks to clean, dedupe or fix a data file, or mentions
messy exports.
The vague version matches almost nothing, or worse, everything. The specific version loads when someone drops a CSV into the chat and says "can you fix this".
Avoid the words that make descriptions useless
Some phrases appear in a lot of skills that never trigger:
"helps with", "assists with", "various tasks", "utility", "general purpose"
"best practices" with no domain attached
a list of ten unrelated jobs ("docs, tests, deploys and code review")
If a skill really does several unrelated jobs, split it. One job per skill keeps descriptions sharp and keeps the body short.
Check the name too
The name must match the folder and use only lowercase letters, digits and single hyphens, up to 64 characters. Names containing "claude" or "anthropic" are rejected by Claude. A wrong name is the second most common reason a skill silently fails to load, after the description. A name like release-notes-writer also helps the agent: it is one more signal of what the skill is for.
Test that it triggers
After installing, start a fresh session and try three kinds of request:
The obvious one: "Write release notes for v2.3." It should load.
A paraphrase: "What shipped since last month?" It should load.
A near miss: "Write a blog post about our launch." It should not load.
If the paraphrase fails, add its words to the description. If the near miss loads, the description is too broad; name the output more precisely. Most apps show when a skill is used, so you can see the result directly.
A checklist you can copy
Starts with a verb in third person and names the output.
Contains "Use when…" followed by real requests, file types and tools.
150-500 characters, one line, no angle brackets.
One job, not a list of jobs.
Name matches the folder, lowercase-with-hyphens.
The SKILL.md checker tests all of these automatically and shows a fix for each problem it finds, and the builder writes descriptions in this pattern from a plain-English brief. To see the pattern in practice, every Pro skill on SkillMarkdown follows it, for example:
Why this is worth the effort
A skill is a small bet: a few minutes of writing in exchange for an agent that does a task your way every time. The description is where that bet pays off or does not. Spend as long on those two sentences as on the rest of the file, test them with a paraphrase and a near miss, and the skill will load when you need it and stay out of the way when you do not.
Source: https://skillmarkdown.net/blog/how-to-write-a-skill-description-that-triggers
Top comments (0)