Home › Skill description examples
Your skill's description field is the only thing the loader sees before deciding whether to run it. A body written perfectly still fails if the description gives nothing to match against. Below are copy-ready examples in both forms, the pattern behind them, and the four mistakes that produce a skill that never fires.
The pattern that works: WHAT plus WHEN.
First sentence says what the skill does, in the third person, starting with a verb. Second sentence says when to use it, naming the situations and the words a user would actually type.
description: Extracts text and tables from PDF files. Use when the
user mentions a PDF, a scanned document, an invoice, or needs data pulled
out of a file into CSV.A description of "Helps with PDFs" gives the loader nothing. It cannot match against a vague noun, only against concrete ones.
A skill is dormant by default. Before any instructions run, something has to decide the skill is relevant. That decision is driven almost entirely by the description, not the body.
This creates an asymmetry that surprises people. Writing better instructions in the body has no effect on triggering. Rewriting the description can go from never firing to firing on every relevant request.
| Field | Read when | Effect of improving it |
|---|---|---|
description | Before deciding to load the skill | Decides whether the skill runs at all |
name | Same moment, plus the folder check | A mismatch here is a silent failure |
| Body content | After the skill is already running | Quality of the output, not whether you get one |
That is why polishing the body first is backwards when a skill will not fire. Fix the description first. The not triggering page covers the diagnosis; this page is about writing it correctly the first time.
description: <verb, third person, what it does>. Use when <situation>,
<situation>, or <situation>.| Part | Job | Do | Don't |
|---|---|---|---|
| WHAT | Say what output it produces | Start with a verb: "Converts", "Extracts", "Writes" | Start with "This skill..." — wastes tokens |
| WHEN | Name the trigger situations | List what the user would say or what would appear in the message | Say "when relevant" — that matches everything and nothing |
Bad — Bad — "Helps with PDFs" and similar
Good — Good — "Extracts text and tables from PDF files, including scanned documents. Use when the user uploads a PDF, mentions an invoice or a report, or needs data pulled from a file into CSV or a table."
Bad — Bad — "Helps write status updates"
Good — Good — "Drafts weekly status updates in the user's preferred format, with completed, in progress, and blocked sections. Use when the user asks for a weekly report, a status summary, or an update to send to their team or manager."
Bad — Bad — "Reviews code"
Good — Good — "Reviews code for correctness, edge cases, and error handling, and returns findings ranked by severity. Use when the user pastes a diff, a snippet, or a file and asks for a review, a second opinion, or feedback before shipping."
Bad — Bad — "Converts files"
Good — Good — "Converts between CSV, JSON, and YAML, preserving key order and reporting rows that fail to parse. Use when the user mentions converting a data file, asks for JSON from CSV, or has a file with the wrong extension."
Bad — Bad — "Writes reports for clients"
Good — Good — "Writes client status reports using the brand colours, logo, and section order in the attached reference files. Use when the user mentions a client report, a monthly summary for a customer, or asks to apply house style to a document."
Bad — Bad — "Gem migration tool"
Good — Good — "Converts a Gemini Gem's instruction text into a valid SKILL.md file with correct frontmatter. Use when the user is migrating away from Gems, mentions a Gem that is being deleted, or needs a skill file before the November 17 shutdown."
The trigger half is where most descriptions fail, because it is written as an intention rather than as a set of matchable conditions.
| Weak WHEN | Strong WHEN | Why |
|---|---|---|
| "Use when relevant" | "Use when the user mentions a PDF or an invoice" | One is unmatchable, the other names concrete tokens |
| "Use for document tasks" | "Use when the user asks to extract, summarise, or convert a document" | Names the verbs a request would contain |
| "Use for code" | "Use when the user pastes a diff or asks for a review" | Says what appears in the message, not just the topic |
| "Use when writing reports" | "Use when the user asks for a weekly report or a client summary" | Turns a category into two likely phrasings |
Write the WHEN part from the user's side, not yours. Your mental model is "this is my PDF skill". The loader's input is a message that says "can you pull the numbers out of this invoice". The description has to contain the vocabulary of that message.
It reads well and it wastes the opening. Every sentence competes for a limited field; the first few words do the most work. Lead with the verb instead.
Bad — Bad — "This skill helps users convert spreadsheets into structured data."
Good — Good — "Converts spreadsheets into structured data, noting rows that cannot be parsed."
A pure capability statement tells the loader what the skill produces but gives no basis for the decision. It will match too rarely, or too broadly, depending on phrasing.
Bad — Bad — "Writes professional emails to customers about delays."
Good — Good — "Writes professional emails to customers about delivery delays, offering options and a revised date. Use when the user needs to tell a customer about a late order, a shipping problem, or a revised delivery date."
Describing how the skill works is not the same as describing when to use it. A user never asks for "a markdown pipeline with YAML frontmatter".
Bad — Bad — "Parses frontmatter, validates against a schema, and normalises naming conventions using a three-pass pipeline."
Good — Good — "Checks a SKILL.md for the format rules Gemini enforces and reports every violation. Use when the user mentions a skill that will not upload, a skill that never triggers, or a validation error."
A description covering everything matches everything, including requests the skill cannot help with. Over-triggering is as broken as never triggering: you lose trust in the tool without noticing you have lost it.
Bad — Bad — "Helps with writing, editing, research, analysis, and planning."
Good — Good — "Rewrites internal technical documentation so it can be read by non-specialists, keeping every technical term accurate. Use when the user asks to simplify documentation, write for a general audience, or make a spec more accessible."
The field accepts 1 to 1024 characters. Nothing useful lives under about 60, and there is no benefit to running past 400.
| Length | Verdict |
|---|---|
| Under 40 | Almost certainly missing the WHEN part |
| 80 to 300 | The useful range. WHAT plus WHEN, plus two or three trigger situations |
| 300 to 500 | Acceptable when the skill covers several distinct situations |
| Over 500 | Usually contains implementation detail that belongs in the body |
| Over 1024 | Rejected |
You can check a description without uploading anything. Write down three requests:
The exact thing the skill exists for, phrased the way you would phrase it.
An adjacent request that should plausibly use it.
Something unrelated. If the words overlap too much, narrow the description.
If request 1 does not use the trigger words in your description, the description is wrong. That is the whole test. Do not upload first and hope.
The validator checks the length and the empty cases automatically. Paste the file in, and confirm the description matches your three test requests before you upload.
It is shown in lists and menus, so a vague description is also confusing to you when you are looking for the right skill among several. Both problems come from the same cause.
Third person is conventional and slightly safer for matching: "Converts files", not "I convert files". Both are accepted; the convention is what most examples use.
Yes. Skills are your files. Edit the frontmatter, re-upload, and allow a few minutes before testing. This is a real advantage over Gems, which have not been editable since October 13, 2026.
Three narrower skills are usually better. Each gets a precise trigger, and you avoid one description that has to cover three unrelated situations and ends up matching everything or nothing.
The description is too broad, most likely because the WHEN part lists topics rather than situations. Narrow it to the specific requests that should trigger it. See skills vs custom instructions if the behaviour should be always-on instead.
As long as the instructions need, with no limit worth worrying about. Keep the description short and concrete, and put the detail in the body where it can be read at full length.