# skill-authoring

> Claude/Codex skill by [@grafana](https://omgskills.com/library/grafana/index.md) · 286 stars · Updated 2026-10-17

Author, audit, and improve Grafana SKILL.md files against Anthropic's published Agent Skills guidance and the four-dimension rubric the grafana/skills CI gate uses (conciseness, actionability, workflow clarity, progressive disclosure). Applies the canonical SKILL.md structure (YAML frontmatter + body + references/ + scripts/ + assets/), the "pushy description" trigger pattern, the three-level progressive-disclosure model, and the validate-fix-rerun feedback loop. Use when creating a new skill in this repo, when reviewing a skill PR, when a skill's Tessl review score is below 75 (the merge gate), when a skill's description isn't getting picked up by agents, when restructuring a long SKILL.md into a bundle, or when the user asks how to write, improve, optimize, audit, or fix a skill - even if they don't say "skill" explicitly (e.g. "this isn't triggering", "Tessl scored this 72", "split this doc").

## Install

```sh
git clone https://github.com/grafana/skills /tmp/skills && ln -s /tmp/skills/skills/grafana-core/skill-authoring ~/.claude/skills/skill-authoring
```

## From README

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.

## Links

- HTML page: https://omgskills.com/library/grafana/skills/skill-authoring/
- GitHub: https://github.com/grafana/skills
- Author: [@grafana](https://omgskills.com/library/grafana/index.md)

## More from this repo

- [k6-docs](https://omgskills.com/library/grafana/skills/k6-docs/index.md) — Used to write or review k6 documentation across the three k6 repositories - k6-DefinitelyTyped (TypeScript types),...
   - [@grafana](https://omgskills.com/library/grafana/index.md) · 295 stars
- [adaptive-metrics](https://omgskills.com/library/grafana/skills/adaptive-metrics/index.md) — Cut Grafana Cloud Metrics cost by shrinking active-series count with Adaptive Metrics aggregation rules —...
   - [@grafana](https://omgskills.com/library/grafana/index.md) · 286 stars
- [admin](https://omgskills.com/library/grafana/skills/admin/index.md) — Used to manage Grafana Cloud accounts — organizations, stacks, RBAC roles and assignments, SSO/SAML/OAuth/GitHub auth,...
   - [@grafana](https://omgskills.com/library/grafana/index.md) · 286 stars