When you prompt an agent with a task, the agent scans a lightweight index (just name and description) and decides whether to fetch the full skill file. The body you spent time on? Only gets read if the description earns it first.
agent index scan view
1title: Document Helper Skill
2description: This skill is designed to help users when they need to work with
3 documents of various kinds including Word documents, PDFs, and other file
4 types. It should be used whenever someone asks about creating, editing,
5 reading, extracting content from, or otherwise manipulating any kind of
6 document file.
7
8# skill body — not read during index scan
9steps:
10 - validate the file type
11 - open and parse the document
12 - return structured content
1Wrong key — schema error. Agent skips this skill entirely.
289 words. Agent scans this on every request. Ambiguity is a liability.
1name: document-helper
2description: >
3 Use when creating, reading, or editing Word docs and PDFs.
4 Triggers: "make a doc", "read this PDF", "edit my file".
5 Do NOT use for spreadsheets or Google Docs.
6
7# skill body — not read during index scan
8steps:
9 - check file type and extension
10 - delegate to the appropriate parser
11 - return structured output
1Correct key.
2Under 300 chars. Fits the index scan.
4Explicit pattern-match hooks.
5Tells agent when not to select. Prevents false positives.
Toggle Agent view to see what the agent actually sees during selection. That’s the interface you’re writing for.
The description field answers one question: when should I reach for this? Get it wrong and the skill effectively doesn’t exist. A vague description doesn’t give the agent enough confidence to select it, or worse, it gets selected for tasks it was never meant for.
Schema matters too. Look at the bad example: it uses title instead of name. That’s a silent failure. The agent won’t compensate for a key it doesn’t recognize, so the skill gets skipped entirely. The good example uses name, keeps the description under 300 characters, and adds explicit trigger phrases so there’s no ambiguity about when to reach for it.
Once the description does its job, the body is where you can breathe. Write out the steps, cover edge cases, add examples. Just keep it under 500 lines. Long bodies bloat the context window and degrade everything else running at the same time. If your skill needs more than that, it’s probably two skills.
The shift is in how you think about the audience. You’re not writing documentation for your fellow developers. You’re building an interface for a non-human reader that makes fast, pattern-based decisions with limited context. Write for that reader.