R005 · description

Description present and well-sized

Code: R005
Slug: description
Tier: structure
Default severity: warning
Packages: recommended, strict
Locked: No
Doc: https://doraval.dev/reference/rules/R005


What	Checks that frontmatter includes a `description` and that it stays within the agentskills.io max (1024 characters).
Why	The description is the trigger. Agents load name + description before the body. Missing or oversized text hides the skill or wastes always-on context.

How to fix

State what the skill does and when to use it.
Prefer concrete triggers over slogans.

# weak
description: API helper

# stronger
description: >-
  Use when writing code that calls the Gemini API for text generation,
  multi-turn chat, image generation, or streaming.

Move long detail into the body or references/ — do not pad the description.
Pair with R014 / R025 so the content of the description is trigger-ready.