Skip to content

Skill Descriptions

Condensed from optimizing skill descriptions. Load this when the skill fails to trigger, over-triggers, or the description field is being rewritten.

Role of description

At startup, agents typically load only name and description. That field is the discovery surface. The body is unread until a task matches.

Agents often skip skills for one-step work they can already do. Descriptions matter most for specialized knowledge, uncommon formats, and multi-step procedures.

Hard limit: 1024 characters (specification).

Writing

  • Imperative: "Use this skill when..." rather than "This skill does...".
  • User intent, not internals. Match what the user asked for.
  • List apply contexts, including cases that never name the domain.
  • Stay to a few sentences. Long descriptions tax discovery context across all skills.

Quote YAML values that contain colons.

Trigger Evals

Author ~20 realistic queries: 8–10 should-trigger, 8–10 should-not-trigger.

Should-trigger queries should vary phrasing, explicitness, detail, and complexity. The useful ones are cases where the skill helps but the connection is not obvious.

Should-not-trigger queries should be near-misses that share keywords but need a different capability. Irrelevant prompts ("what's the weather") do not test precision.

Include file paths, casual language, and specific domain nouns. Store as JSON:

[
  {"query": "I've got a spreadsheet in ~/data/q4_results.xlsx ...", "should_trigger": true},
  {"query": "whats the quickest way to convert this json file to yaml", "should_trigger": false}
]

Measuring

A trigger is a load of SKILL.md, not a mention of the skill name in prose.

Because model behavior is noisy, run each query several times (3 is a starting point) and compute trigger rate. A reasonable pass bar is rate ≥ 0.5 for should-trigger and < 0.5 for should-not-trigger.

Split ~60% train / ~40% validation, mixed positives and negatives, and keep the split fixed. Revise from train failures only. Score selection on validation pass rate.

  • Missed triggers: description too narrow. Broaden categories, not query keywords.
  • False triggers: too broad. Add what the skill does not cover.
  • Do not paste failed-query keywords into the description; that overfits.

Five iterations is usually enough. If results stall, inspect the queries.

After selecting a description, confirm it is under 1024 characters and spot-check with 5–10 fresh queries that were never in the eval set.

The skill-creator skill automates split, parallel eval, and revision. Detection of a "Skill" tool call is client-specific; adapt the check to the harness in use.