Module 5 · Skills

Descriptions & Discovery

You can write a perfect skill and never see it run. The reason is almost always the same: the description didn't tell the agent when to reach for it.

6 min read

Lesson 5.1

The description is the trigger

At startup the agent sees only Tier-1 metadata, for potentially dozens of skills at once. When a task arrives, it decides which skills are relevant using essentially one field: the description. If the description doesn't clearly signal when to use the skill, the skill simply never fires. The best instructions in the world can't save a skill the agent never opens.

So a good description does two jobs at once:

  • What it does: the capability, in plain terms.
  • When to use it: the concrete situations and trigger words a user might say.
Weak
description: Helps with documents.

No capability, no triggers. Against ten other skills, the agent has nothing to match on.

Strong
description: Extracts tables and form fields from PDF files. Use when reading a PDF, pulling data from a scanned form, or converting a PDF table to CSV.

States the capability and lists the moments ("PDF", "scanned form", "CSV") a request might contain.

Lesson 5.2

The rules that matter

A few constraints have outsized impact on whether a skill gets discovered and behaves:

  • Write in the third person. The description is injected into the system prompt. "Extracts data from PDFs" reads as a capability; "I can help you with PDFs" reads as chatter.
  • Front-load trigger terms. The listing is truncated, so put the distinctive nouns and verbs early.
  • Name in kebab-case, ≤ 64 chars, no reserved words like claude or anthropic. Gerund names read well: processing-pdfs.
  • Keep the description ≤ 1024 chars and free of XML tagsXML tags: angle-bracket labels like <name> used to mark structured text..

The number-one reason a skill "doesn't work" is a vague description. Before debugging the body, reread the description as if you were the agent scanning a long list: would this obviously match the task?

Lesson 5.3 · Interactive

Spot the bad skill

Here's a skill that won't get discovered and won't behave. Tap each underlined problem to diagnose it (there are four). See if you can find them all before reading the explanations.

helper/SKILL.md
---
name: My PDF Helper
description: I can help you with all kinds of documents and stuff!
---

# Helper

You are an expert assistant. When the user wants help, do
your best to figure out what they need and help them...

## Reference
(...620 lines of the full PDF spec pasted inline...)
Tap each problem you can spot.
1
Invalid name. "My PDF Helper" has capitals and spaces. Names must be kebab-case (e.g. pdf-extractor) and that name becomes the command.
2
Vague, first-person description. "help you with documents and stuff" gives the agent nothing to match on, and first person reads as chatter in the system prompt. Say what it does and when to use it, in third person.
3
No actual procedure. "do your best to figure out what they need" is not instruction. A skill should give a concrete workflow, not a pep talk.
4
Reference pasted inline. 620 lines in the body defeats Dynamic Context; it sits in context every turn. Move it to references/pdf-spec.md and point to it.

Which description is most likely to get the skill reliably picked for the right task?

Takeaways

1. The description is the trigger; it alone decides whether the skill is chosen.
2. Say what it does and when to use it, with concrete trigger terms, in third person.
3. Kebab-case name, ≤ 1024-char description, no reserved words, no inlined references.

Descriptions dialed in?

Last core module: putting the primitives together.