Skill Has Usage Section
skill-has-usage-section
info
experience: documentation
spec: body
Skill body should have a "Usage" section.
A skill body should document how to use it under a Usage section, so both humans and agents can see how it is meant to be invoked.
Rule definition
The full Spotlight rule — drop it into a ruleset (.spotlight.yaml / .spectral.yaml) and run it with any Spotlight tool.
skill-has-usage-section:
title: Skill Has Usage Section
reference: https://spotlight-rules.com/spec/rules/agent-skill/skill-has-usage-section/
description: A skill body should document how to use it under a Usage section,
so both humans and agents can see how it is meant to be invoked.
message: Skill body should have a "Usage" section.
severity: info
given: $
then:
function: headingPresent
functionOptions:
name: Usage
tags:
- format:agent-skill
- spec:body
- experience:documentation
prompt: "You are editing an Agent Skill document to satisfy the Spotlight API
governance rule 'skill-has-usage-section' (Skill Has Usage Section).
Requirement: A skill body should document how to use it under a Usage
section, so both humans and agents can see how it is meant to be invoked.
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-has-usage-section' (Skill Has Usage Section). Requirement: A skill body should document how to use it under a Usage section, so both humans and agents can see how it is meant to be invoked. 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) | $ |
| Severity | info — educational by default; raise to warn/error to enforce |
| Reference | https://spotlight-rules.com/spec/rules/agent-skill/skill-has-usage-section/ |