What Makes a Good Skill Description for Agent Selection in AI Planning

A good skill description is a concise, third-person two-sentence blurb that explains what the skill does and when to use it, using concrete domain terms to help the AI planner match user requests accurately.

In the mattpocock/skills repository, every agent capability is defined by a YAML front-matter block containing a description field. This description serves as the sole metadata the central planner reads when deciding which skill to invoke, appearing directly in the system prompt alongside all installed skills. Crafting this text carefully ensures the AI can reliably distinguish between similar capabilities and select the correct tool for the job.

Core Guidelines from write-a-skill/SKILL.md

The canonical template in write-a-skill/SKILL.md establishes strict formatting rules that maximize discoverability while respecting context window limits.

Keep It Under 1024 Characters

The description must fit within 1024 characters to avoid truncation in the prompt. Long descriptions risk losing crucial trigger words that the planner uses for matching, effectively rendering the skill invisible to the AI.

Use Third-Person Phrasing

Always write in third person as if describing an autonomous capability: "It extracts…" or "Use when…". This framing aligns with how the planner treats each skill—as an external tool it can invoke rather than an instruction it should follow.

Structure as Two Distinct Sentences

The optimal format follows a strict two-sentence pattern:

1. Capability declaration – States exactly what the skill provides
2. Trigger phrase – Begins with "Use when…" to provide explicit lexical cues

According to lines 73-75 of write-a-skill/SKILL.md, the first sentence gives the planner an immediate notion of the capability, while the second sentence supplies the searchable trigger text.

Employ Concrete Domain Terms

Avoid vague language like "Helps with documents." Instead, use specific nouns, verbs, and domain terminology that differentiate this skill from others. For example, the PDF extractor skill uses: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."

How the Planner Parses Descriptions

The central planner processes skill descriptions through three distinct mechanisms as implemented in the runtime:

1. Prompt assembly – All skill descriptions from their respective SKILL.md files are concatenated into the system prompt
2. Keyword matching – The language model scans for the "Use when…" clause to align user intent with available skills
3. Disambiguation – When multiple skills share overlapping verbs, the specific nouns in the first sentence break ties and determine the best match

The planner essentially treats the description as the answer to two questions: "What does this skill provide?" and "When should the planner call it?"

Implementation Examples

Creating a New Skill with Proper Description

When adding a skill via the CLI, the template generates a skeleton that you must customize:

# Generate the skill structure

npx skills@latest add mattpocock/skills/write-a-skill

# Edit the generated SKILL.md to replace the description

The resulting SKILL.md should contain:

---
name: pdf-extractor
description: Extract text, tables and images from PDF files, then optionally fill forms or merge documents. Use when the user mentions PDFs, form filling, or document extraction.
---

Reference Implementations in the Repository

Several existing skills demonstrate effective description patterns:

• ubiquitous-language/SKILL.md – Shows concrete, trigger-rich description using domain-specific terminology
• triage-issue/SKILL.md – Demonstrates how action verbs like "triage" and "bug" serve as strong selection signals
• tdd/SKILL.md – Illustrates concise capability phrasing for development workflows without ambiguous filler words

Summary

• Limit descriptions to 1024 characters to prevent prompt truncation in write-a-skill/SKILL.md
• Write in third person to maintain the autonomous capability framing
• Use exactly two sentences: first declaring capability, second starting with "Use when…"
• Include concrete nouns and domain verbs to differentiate from similar skills
• Reference specific file paths like write-a-skill/SKILL.md to verify the format

Frequently Asked Questions

How long can a skill description be?

The maximum length is 1024 characters as defined in write-a-skill/SKILL.md at lines 71-78. Exceeding this limit risks truncation, which can remove critical trigger phrases the planner needs to identify when to invoke the skill.

What is the "Use when…" clause and why is it required?

The "Use when…" clause is the second sentence of the description that provides explicit lexical cues for the AI planner. According to the repository implementation, the planner specifically scans for this trigger phrase to match user input against available skills, making it essential for proper agent selection.

Can I write skill descriptions in first person?

No. The guidelines in write-a-skill/SKILL.md (lines 60-66) mandate third-person phrasing such as "It extracts…" or "Use when…". First-person language confuses the planner because it treats the description as instructions rather than capability metadata.

What happens if two skills have similar descriptions?

When multiple skills share overlapping verbs, the planner uses the specific concrete nouns in the first sentence to break ties during disambiguation. Therefore, using distinct domain-specific terminology in the capability declaration ensures your skill stands out from others in the system prompt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}