skill-authoring

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) 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. Body under 500 lines — split into references/*.md if approaching the limit. SKILL.md is the routing layer, not the entire knowledge base. 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. Imperative voice — "Run X" not "You should run X" not "It is important to run X". Explain why over heavy-handed MUST markers. Concrete examples beat prose — copy-paste-ready commands, real config snippets. Tessl's actionability dimension scores this directly. No reserved words in name — anthropic and claude are forbidden in skill names. No time-sensitive language in the body — "after August 2025…" rots. Use an