The Problem

Teams using Grafana's observability stack (Prometheus, Loki, Tempo, k6, Alloy) face a knowledge gap: the operational expertise for each tool lives scattered across docs, runbooks, and tribal knowledge. AI coding agents (Claude Code, Cursor, Codex) need that context in a machine-readable form to give accurate answers, but no standardized packaging existed. This repo solves that by publishing Grafana's operational knowledge as reusable "skills" that agents can load on demand.

What This Does

This is a fork of grafana/skills (225 stars upstream) containing 95 files: 78 Markdown skill definitions, 8 shell scripts, and 4 JSON marketplace manifests. Skills are organized into six plugin groups under skills/: grafana-core (dashboards, PromQL, alerting), grafana-cloud (fleet management, integrations), grafana-lgtm (Loki, Mimir, Tempo, Pyroscope), grafana-k6, grafana-app-sdk, and grafana-plugins.

Each skill is a SKILL.md file with optional references/ subdirectories containing deeper documentation. The k6 skills have the richest structure, including scripts/ with 8 shell helpers for fetch, validation, and formatting workflows. The template/SKILL.md file defines the structure for new skills.

How It Is Wired

This is a content distribution repository, not an application. There is no runtime entry point, no import graph (0 internal modules, 0 import edges — only 8 shell files analyzed), and no code that executes on a server. The wiring is entirely declarative:

  • Entry point: .agents-plugin/marketplace.json (and .claude-plugin/, .cursor-plugin/ equivalents) — these manifests tell agent tools which skills exist and where they live.
  • Distribution: skill-registry.json at the root indexes all available skills for tooling that reads it.
  • Validation: .github/workflows/lint-skills.yml and .github/workflows/validate.yml run scripts/lint-skills.sh in CI to check skill structure and content.
  • Installation: agents fetch skills via npx skills add grafana/skills, which reads the manifests and copies SKILL.md files into the agent's local skills directory.

The blast radius is the SKILL.md files themselves — a malformed frontmatter or broken reference breaks agent loading for everyone who installed the marketplace. The CI workflows are the only guard against that.

How To Use It

Setup — no build step; this is content. For any Agent Skills-compatible tool:

npx skills add grafana/skills

For Claude Code specifically:

claude plugin marketplace add grafana/skills
claude plugin install grafana-core@grafana-skills
claude plugin install grafana-cloud@grafana-skills

Configuration — none required. No environment variables, no API keys, no config files. The .agents-plugin/marketplace.json manifest handles discovery automatically.

Running it — invoke your agent with a task like "write a PromQL query for p99 latency" and the agent loads the relevant SKILL.md from skills/grafana-core/promql/ automatically.

Real-World Use

A developer asks Cursor: "Why is my Grafana dashboard showing empty panels after upgrading to v11?" The agent loads skills/grafana-core/dashboarding/SKILL.md, checks references/panels.md for version-specific issues, and answers with migration steps. A k6 contributor runs scripts/test_typescript.sh from skills/grafana-k6/k6-docs/scripts/ to validate their TypeScript changes before submitting a PR.

Code Health & Issues

Static analysis found no structural red flags: tests present (5 test files), CI configured (GitHub Actions), license present, no committed secrets, no circular dependencies. The measured import graph shows 0 internal modules across 8 shell files — this is a documentation repo, so that's expected, not a concern.

  • Med — No lockfile or dependency manifest at root; the shell scripts in skills/grafana-k6/k6-docs/scripts/ depend on system tools (curl, jq, node) that aren't pinned. Reproducibility depends on the environment.
  • Low — The .gitkeep files in grafana-cloud/ and grafana-core/ suggest placeholder directories that may confuse contributors about intended structure.

The Bottom Line

A well-organized, standards-compliant skills marketplace for Grafana's observability stack, already validated by upstream CI and used by the broader Agent Skills ecosystem. It's content, not code — you won't debug it, you'll extend it by adding SKILL.md files. Worth adopting if your team runs Grafana tools and uses AI agents; the k6 skill set is the most mature and shows the pattern done right.