promql Skill (Grafana) for Claude Code: What It Does and How to Install It

Makes Claude write, check and speed up PromQL queries for Prometheus, Grafana Mimir and Grafana Cloud Metrics.

Installs: 8.6K; on skills.sh
Stars: 302; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

Ask Claude for a metric query, such as an error rate or a p95 latency. The skill makes it keep the rules that trip people up: rate() first and then aggregate, keep le in histogram quantiles, and use a range at least 4 times the scrape interval. It can check the query against your endpoint with curl, then turn a slow dashboard query into a recording rule.

You need a Prometheus, Mimir or Grafana Cloud endpoint to query. For Grafana Cloud the workflow adds basic auth with a metrics user and token to each curl call. The skill is published in Grafana's own skills repo.

Good for

SREs and on-call engineers writing error-rate, p95 and SLO queries
Anyone fixing a wrong rate, a NaN quantile or a "No data" panel
Dashboard owners turning a slow query into a recording rule

Install promql

Claude Code

Copy this prompt.

Install the promql skill in Claude Code. Run this command:

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

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The grafana-core plugin holds promql with the other core skills: its marketplace entry lists 8 skill paths while the README table shows 7. The marketplace entries list skills only, and the repo tree has no hooks or .mcp.json. npx skills add grafana/skills installs every skill in the repo; add --skill promql to install only this one. The skill's workflows run curl and jq against your Prometheus endpoint, so there is no Claude app upload route.

From the project README. Source.

What's in the skill

When it loads

Write, validate, and optimize PromQL for Prometheus / Grafana Mimir / Grafana Cloud Metrics. Covers `rate` vs `irate` vs `increase`, label matchers and regex, `sum / avg / topk / by / without` aggregation, classic + native `histogram_quantile`, ratios with divide-by-zero guards, `absent` / `changes` for staleness, time offsets and `predict_linear`, recording-rule naming, SLO + burn-rate math, and a cardinality-hunting playbook. Use when writing a metric query, fixing wrong p95s, building an error-budget alert, debugging "query is slow", finding the noisy label that blew up cardinality, or migrating a dashboard query to a recording rule — even when the user says "calculate the error rate", "p99 latency", "sum by service", "why is this query slow", or "what's filling Mimir" without naming PromQL.

Sections in SKILL.md

Prerequisites
Common Workflows
1. Write + validate a query
2. Common patterns to copy
3. Convert a slow dashboard query into a recording rule
Common bugs
Resources

Key facts

Author: Grafana Labs (vendor's own repo; the marketplace owner is Grafana Labs)
License: Apache-2.0 (LICENSE file and SKILL.md frontmatter)
Installs on skills.sh: 8,629 (Nov 2, 2026)
GitHub stars: 302 for the whole grafana/skills repo (Nov 2, 2026)
Last repo commit: Nov 1, 2026
What it includes: 2 files including SKILL.md: references/patterns.md. No scripts
skills.sh audits: Gen Agent Trust Hub: pass; Socket: pass; Snyk: pass (Nov 2, 2026)
Part of: The grafana-core plugin (8 skill paths in the marketplace entry, 7 in the README table)
Needs: A Prometheus, Mimir or Grafana Cloud Metrics endpoint; curl and jq for the validation steps

What it includes

Sketches the query, runs it against /api/v1/query, checks the result count
Uses curl and jq. If the result is empty it checks the series list with /api/v1/series. For Grafana Cloud you add basic auth to each call.
Try: “Write a PromQL query for the 5xx error rate per service”
Runs code · Write and validate a query
Per-status rates, p95 with histogram_quantile, divide-by-zero guard
Aggregate after rate, keep le in the inner aggregation of histogram_quantile.
Read · Copy common patterns
Names the expression, adds a rules group, verifies the new metric
Shows a record: rule such as job:http_request_duration_p95:rate5m, then checks the new series and compares values.
Runs code · Convert to a recording rule
NaN quantiles, "No data", wrong rate size, query timeouts
Each bug has a one-line cause, such as forgetting by (le).
Read · Common bugs list
11 sections in references/patterns.md
Rate and aggregation, matchers, histograms, ratios, staleness, offsets, recording rules, SLO burn rate, cardinality and more.
Read · Pattern library
Top series counts and a label to drop at scrape time
Includes an Alloy snippet to drop a high-cardinality label.
Read · Cardinality controls

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Cloud tokens go on the command line
The workflow says to add -u "<metrics_user>:<token>" to each curl call. Our advice: use a read-only token, and avoid pasting it into shared sessions. github.com
Queries load your metrics backend
Cardinality queries such as the top 10 metrics by series count can be heavy on a large Prometheus or Mimir. Run them off-peak. github.com
The plugin route adds 7 more skills
The grafana-core marketplace entry lists 8 skill paths. The marketplace entries list skills only, and the repo tree holds no hooks or .mcp.json. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. The example calls are GET queries; recording rules are written as files.
Talks to	The Prometheus, Mimir or Grafana Cloud metrics endpoint you point it at
Sign-in and keys	SKILL.md says to add basic auth (metrics user and token) to curl for Grafana Cloud.
Scopes	Runs curl and jq against the Prometheus, Mimir or Grafana Cloud endpoint you give it Can write recording rule YAML Sends a metrics user and token as basic auth for Grafana Cloud

Questions

What does the promql skill do?

It makes your agent write, validate and optimise PromQL for Prometheus, Grafana Mimir and Grafana Cloud Metrics. It covers rate vs irate, aggregation, histogram quantiles, ratios, recording rules, SLO burn rates and cardinality.

How do I install it in Claude Code?

Use the install box at the top of this page. The README documents a Claude Code plugin, grafana-core, and the skills CLI, which installs every skill in the repo unless you add --skill promql.

Is it official?

Yes, it is in Grafana's own repo, grafana/skills, and the marketplace owner is Grafana Labs.

Does it need an API key?

It needs access to a Prometheus-compatible endpoint. For Grafana Cloud the workflow says to add basic auth with a metrics user and token to each curl call. A local Prometheus at localhost:9090 needs none in the example.

Does it work in Cursor and Codex?

The README says the repo is compatible with Claude Code, Cursor, Codex and any tool that supports the Agent Skills standard. Cursor and Codex use the skills CLI command in the install box.

Is it safe?

It runs curl queries against the endpoint you give it, and Grafana Cloud calls need a token on the command line. The skill bundles no scripts. Our advice: use a read-only metrics token, and expect heavy queries to load your Prometheus.

What else is in the grafana-core plugin?

Its marketplace entry lists skills for dashboards, Grafana OSS, alerting, Alloy, Beyla, OpenTelemetry and skill authoring, besides promql. The README table lists 7 skills, while the marketplace entry lists 8 paths.

Information

updated Nov 2, 2026

Repository: grafana/skills
Folder: skills/grafana-core/promql

grafana/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

promql SKILL.md · github.com
promql patterns.md · github.com
grafana/skills README · github.com
grafana/skills marketplace.json · github.com