content-description-routing

Skill and agent descriptions should guide routing; command descriptions should clearly explain their purpose

Severity	warning (auto)
Autofix	-
Since	v0.18.0
Repo Types	agentskills, apm, codex-marketplace, codex-plugin, dot-claude, marketplace, single-plugin
Category	Content Intelligence

Checks that skill and agent descriptions work as routing signals, while command descriptions clearly explain their picker-visible purpose.

What it checks

• Descriptions are present, non-empty strings. This basic check stays on when the routing heuristics are disabled.
• Skill and agent descriptions say when the model should use them. Commands are excluded because users select them directly.
• Descriptions do more than restate the building block name or category, such as a deploy-staging skill described only as "Deploy staging" or a command described only as "A command."

Skills with disable-model-invocation: true are user-only: the model cannot route to them, so this rule skips them by default. Set check-user-only-skills: true to check their descriptions normally. Only the YAML boolean true opts a skill out; an absent field, false, strings, and numbers remain checked.

Natural selection clauses count as trigger phrasing, including "Use this skill for ...", "Invoke this skill whenever ...", "This skill should be used before ...", and "Use only when ...".

The routing heuristics and user-only-skill behavior can be configured independently:

rules:
  description-routing:
    require-trigger-phrasing: true
    flag-name-restatement: true
    check-user-only-skills: false

Why this matters

Descriptions are the text a model uses to decide which skill or agent should handle a request. A description that gives no usage trigger or repeats only its name provides little evidence for that decision.

How to fix

State what the building block does. For a skill or agent, also name the situations or user phrases that should route to it. Commands need a clear purpose but no routing phrase because users select them directly. For example: "Deploys the current build to staging. Use when the user asks to test a change in the staging environment."

This rule reports warnings and does not autofix prose.

Configuration

rules:
  content-description-routing:
    enabled: auto  # true | false | auto
    severity: warning

Parameter	Description	Default
require-trigger-phrasing	Require skill and agent descriptions to say when they should be used	true
flag-name-restatement	Flag descriptions that only restate the name or generic category	true
check-user-only-skills	Check skills whose frontmatter sets disable-model-invocation to true	false

Run skillsaw explain content-description-routing to see this documentation and the rule's effective configuration in your terminal.