Authoring & Improving Grafana Skills

How to write, review, and improve SKILL.md files so they pass the repo's CI gate and score well against the Anthropic-aligned rubric Tessl uses.

Critical rules (always)

1. Description is the primary trigger — third-person, ≤1024 chars, must include explicit "Use when..." phrasing AND list concrete trigger terms users naturally say. See references/descriptions.md for the pushy-description pattern that combats undertriggering.
2. Body under 500 lines — split into references/*.md if approaching the limit. SKILL.md is the routing layer, not the entire knowledge base.
3. One level of nesting for references — link from SKILL.md directly, never SKILL.md → a.md → b.md. Claude may use head -100 previews on nested chains and miss content.
4. Imperative voice — "Run X" not "You should run X" not "It is important to run X". Explain why over heavy-handed MUST markers.
5. Concrete examples beat prose — copy-paste-ready commands, real config snippets. Tessl's actionability dimension scores this directly.
6. No reserved words in name — anthropic and claude are forbidden in skill names.
7. No time-sensitive language in the body — "after August 2025…" rots. Use an <details> "Old patterns" section for legacy info instead.
8. Validate before committing — ./scripts/lint-skills.sh skills/<plugin>/<your-skill> clean + Tessl score ≥75 (run tessl skill review --json <dir>).

The rubric

CI fails any PR where a touched SKILL.md scores below 75 on four 0-3 dimensions: conciseness, actionability, workflow clarity, progressive disclosure. Full per-dimension scoring + Anthropic-doc mapping in references/rubric.md.