Skill Description
skill-description
info
experience: discoverability
spec: frontmatter
A skill must declare a description.
A skill must declare a description — it is the primary signal an agent uses to decide when to invoke the skill.
Rule definition
The full Spotlight rule — drop it into a ruleset (.spotlight.yaml / .spectral.yaml) and run it with any Spotlight tool.
skill-description:
title: Skill Description
reference: https://spotlight-rules.com/spec/rules/agent-skill/skill-description/
description: A skill must declare a description — it is the primary signal an
agent uses to decide when to invoke the skill.
message: A skill must declare a description.
severity: info
given: $.frontmatter
then:
field: description
function: truthy
tags:
- format:agent-skill
- spec:frontmatter
- experience:discoverability
prompt: "You are editing an Agent Skill document to satisfy the Spotlight API
governance rule 'skill-description' (Skill Description). Requirement: A
skill must declare a description — it is the primary signal an agent uses to
decide when to invoke the skill. To fix: Ensure `description` is present and
non-empty at each matching location. This rule is evaluated at the JSONPath
`$.frontmatter` — inspect every location it matches and correct only what
violates the rule. Make the smallest change that satisfies the rule, leave
all unrelated content, key order, comments, and formatting unchanged, and
keep the document valid Agent Skill. Return only the complete corrected
document, with no commentary."
AI fix prompt — send this to Claude, Gemini, or ChatGPT with your artifact to auto-fix this rule
You are editing an Agent Skill document to satisfy the Spotlight API governance rule 'skill-description' (Skill Description). Requirement: A skill must declare a description — it is the primary signal an agent uses to decide when to invoke the skill. To fix: Ensure `description` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.frontmatter` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Agent Skill. Return only the complete corrected document, with no commentary.| Artifact | Agent Skill |
|---|---|
| Applies at (given) | $.frontmatter |
| Severity | info — educational by default; raise to warn/error to enforce |
| Reference | https://spotlight-rules.com/spec/rules/agent-skill/skill-description/ |