SKILL.md 中一行 description 如何決定技能是否觸發

Across 591 scored skills, the weakest of our six evaluation dimensions is also the one that decides whether the skill gets used at all. The fix takes five minutes and almost nobody does it.

Your skill's description field is the only part of it that's loaded before the skill is chosen. The agent reads it, decides whether this skill matches the request, and only then loads the body. That makes it a routing table, not documentation.

We score it as "trigger quality," worth 20 of 100 points. Across 591 skills it averages 7.74 — the lowest of our six dimensions, behind content (8.30) and workflow design (8.11).

Four jobs, and most skills do one

A description that scores well answers four questions:

1. What does it produce? — most skills do this.
2. When should it fire? — common, usually as Use when the user asks to ….
3. When should it NOT fire? — rare, and the single strongest quality signal we measure.
4. What would a person actually type? — rarer still.

Number 3 is where the money is. A skill with no negative space triggers on everything adjacent to it. Install three of those and your agent starts loading the wrong instructions for ordinary requests — which is worse than not having the skill installed.

Same skill, two descriptions

Both of these describe an identical package that reviews a contract against a risk taxonomy.

Before:

description: Reviews contracts and identifies legal risks.

After:

description: Reviews a contract against a risk taxonomy and returns findings
  with severity and suggested redlines. Use when the user asks to "review this
  contract", "check this NDA", or "flag risky clauses". Not for drafting new
  agreements (use an NDA generator), not for jurisdiction-specific compliance
  questions (use a compliance skill), and not for summarizing a contract without
  risk analysis.

The second one is longer, but length isn't the point — the exclusions are. It routes three adjacent request types somewhere else, which is what stops the skill from firing on the 80% of nearby requests it would handle badly.

The gap isn't where you'd guess

Trigger quality varies a lot by category:

• Marketing skills average 9.30 on this dimension.
• Finance & trading skills average 6.09.

A 3.2-point spread on the same rubric item is huge. But before concluding that marketing people are better at naming things: that number is mostly a story about authorship. The marketing set is dominated by a few coherent, well-documented skill families. The finance set accumulated from many independent authors shipping crypto and market-data tools. The categories differ far less than the people writing in them do.

The five-minute check

Open your skill's frontmatter and go through this in order:

1. What does it produce? (A named artifact beats a verb.)
2. What would a user literally type to trigger it?
3. What should route somewhere else instead?
4. Is there anything in here that isn't about routing — a changelog, a philosophy statement, a roadmap?

If you fix only one, fix #3. It's the difference between a skill that's available and a skill that's useful.

The full rubric — including how trigger quality is scored out of 20, and what the written rationale for each skill looks like — is public.