Agent skill

Promql CLI

Install Promql CLI

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/promql-cli .claude/skills/promql-cli && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .claude/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/samber/cc-skills/tree/main/skills/promql-cli

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/promql-cli .agents/skills/promql-cli && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .agents/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/promql-cli .cursor/skills/promql-cli && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .cursor/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/samber/cc-skills.git --path skills/promql-cli

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/promql-cli .gemini/skills/promql-cli && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .gemini/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/promql-cli .github/skills/promql-cli && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .github/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add samber/cc-skills --skill promql-cli -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install samber/cc-skills promql-cli --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/samber/cc-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/promql-cli .opencode/skills/promql-cli && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "promql-cli" agent skill from https://github.com/samber/cc-skills/tree/main/skills/promql-cli into .opencode/skills/promql-cli/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "promql-cli", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: promql-cli
GitHub stars: 228
Token cost: ~1.9k tokens
SKILL.md length: 761 words
Files: 7 (incl. references)
Skills in repo: 16
Repo updated: Oct 1, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Works in 6 steps: Use rate() on counters, never raw values… → When debugging, isolate a single… → Filter early with label matchers in the… → …
Tasks that involve Monitoring and alerting
SKILL.md covers Reference Files, Setup Check, Quick Command Reference and Key Principles, plus 1 more section
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Promql CLI is an agent skill from samber/cc-skills. CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 8 other files, including reference files (for example `evals/evals.json`, `references/debugging.md` and `references/graphing.md`). Compatibility notes: Requires promql-cli and jq

It sits in DevOps & Cloud, covering Monitoring and alerting and Forecasting and time series. It works with Prometheus and Grafana. The repository describes itself as: 🧑🎨 A collection of agentic skills that works. The licence is MIT.

When your agent uses it

Tasks that involve Monitoring and alerting
Tasks that involve Forecasting and time series

Example prompts

“/promql-cli”

Requirements

Python 3
Compatibility (from SKILL.md): Requires promql-cli and jq
Pre-approved tools (allowed-tools): Read, Edit, Write, Glob, Grep, Agent, Bash(promql:*), mcp__context7__resolve-library-id, mcp__context7__query-docs, AskUserQuestion

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

Use rate() on counters, never raw values — raw counters only ever increase; the absolute value is meaningless. rate() gives the per-second…
When debugging, isolate a single instance — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden…
Filter early with label matchers in the innermost selector — Prometheus evaluates selectors before functions, so filtering late means…
For histograms, keep le in the by clause before histogram_quantile() — the function needs all le buckets to interpolate percentiles…
Prefer --output graph for range queries — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs…
Store credentials in ~/.promql-cli.yaml and ~/.promql_token, chmod 600 — passing tokens as CLI args exposes them in shell history and…

What it can do on your machine

Read from SKILL.md and the folder at commit 123cb15. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
- Read
- Edit
- Write
- Glob
- Grep
- Agent
- Bash(promql:*)
- mcp__context7__resolve-library-id
- mcp__context7__query-docs
- AskUserQuestion
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- github.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Compatibility
Requires promql-cli and jq
From compatibility in the SKILL.md frontmatter.

Context cost

Promql CLI loads about 1.9k tokens when it runs, and up to ~7.7k if it reads all its reference files. Until then it costs about 111 tokens; SKILL.md has 761 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~111
When it runs · the whole SKILL.md, loaded when a task matches: ~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~7.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from samber/cc-skills at commit 123cb15, republished under its MIT licence (© samber). 761 words, ~1,877 tokens.

Download SKILL.mdSave it as .claude/skills/promql-cli/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.

name: promql-cli
description: CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph). Apply when executing PromQL queries, troubleshooting performance issues on a software having observability, investigating latency/error rates/saturation, or analyzing time series data.
allowed-tools: Read, Edit, Write, Glob, Grep, Agent, Bash(promql:*), mcp__context7__resolve-library-id, mcp__context7__query-docs, AskUserQuestion
compatibility: Requires promql-cli and jq
license: MIT
user-invocable: true
metadata.author: samber
metadata.version: 1.2.0

promql-cli — Prometheus Query CLI Skill

promql-cli (github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.

Reference Files

Read the relevant reference file(s) before executing tasks:

File	When to read
`references/installation.md`	User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host)
`references/usage.md`	User wants to discover metrics/exporters/labels, run queries, or choose output formats
`references/graphing.md`	User wants to visualize Prometheus data as an ASCII chart in the terminal
`references/debugging.md`	User is investigating a performance issue, latency, errors, saturation, data gaps, or query cost issues
`references/promql-reference.md`	User needs help writing PromQL, understanding metric types, functions, or aggregations

For most tasks, read references/usage.md. For PromQL help, read references/promql-reference.md. When debugging, read both references/debugging.md and references/promql-reference.md.

Setup Check

Before running any query, verify that a host is configured:

bash

promql 'up'   # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'

Recognize these errors as a configuration/auth problem and refer to references/installation.md:

Error	Cause
`dial tcp ... connection refused`	No host running at the configured address
`dial tcp ... no such host`	Hostname not resolved — wrong host in config
`error querying prometheus: ...401...`	Bearer token missing or invalid
`error querying prometheus: ...403...`	Token valid but insufficient permissions
`please specify an authentication type`	Auth flags partially set — use config file instead

If any of these appear, do not create config files on behalf of the user — config files may contain credentials (tokens, passwords) that must never pass through an LLM. Instead, guide the user to set it up themselves:

"Please create ~/.promql-cli.yaml manually with your Prometheus host (and credentials if needed). See references/installation.md for the exact format. Let me know once it's ready."

Only after the user confirms the config is in place should you proceed with queries.

Quick Command Reference

bash

promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output csv                             # CSV output
promql 'up' --output json                            # JSON output
promql metrics                                       # list all metric names
promql labels <metric>                               # list labels for a metric
promql meta <metric>                                 # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host

Key Principles

Use rate() on counters, never raw values — raw counters only ever increase; the absolute value is meaningless. rate() gives the per-second change rate, which is what you actually care about.
When debugging, isolate a single instance — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden behind healthy peers won't show up in averages.
Filter early with label matchers in the innermost selector — Prometheus evaluates selectors before functions, so filtering late means scanning all time series. Early filters reduce data scanned and query latency.
For histograms, keep le in the by clause before histogram_quantile() — the function needs all le buckets to interpolate percentiles; dropping le early produces NaN or wrong results.
Prefer --output graph for range queries — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling. Never send thousands of raw JSON/CSV rows into the LLM context — use --output graph instead, or run --output graph first and --output table only to inspect a narrow window.
Store credentials in ~/.promql-cli.yaml and ~/.promql_token, chmod 600 — passing tokens as CLI args exposes them in shell history and process listings.

Show full SKILL.md (283 more words)Show less

Query Cost Rules

Always apply these before and during any query session:

Always use the promql CLI — never call the Prometheus HTTP API from Python scripts or shell curl. The CLI handles auth, formatting, and output consistently; Python API calls bypass all of that and produce raw JSON that must be parsed, inflating context and masking the graph output that models interpret best.
Check cardinality first — before querying an unfamiliar metric, count its time series (count(metric_name)). High-cardinality metrics without label filters time out or flood the output. See references/debugging.md for patterns.
Confirm the time window upfront — always ask before running range queries. Large intervals are expensive; prefer multiple short-interval queries over one long one.
Clarify past vs. recent — for new investigations, ask whether the user wants a past event (specific timestamp) or a recent trend. If recent, offer concrete choices: last hour, last day, last week, last month.
Aggregate in Prometheus — never pull raw series to aggregate in Python or shell. Push sum by(...), avg by(...), or topk() into the PromQL expression — Prometheus collapses series server-side.
Timeout = query too broad — if a query takes >15s, reduce scope: add label filters, shorten --start, or add an aggregation wrapper. Apply the same narrowed scope to all subsequent queries in the session.
Data gaps → check up — when a metric shows missing data, run up{job="...", instance="..."} before diagnosing the application. A 0 value confirms the exporter was down. See references/debugging.md.

This skill is not exhaustive. Please refer to the official promql-cli documentation and examples for up-to-date information. Context7 can help as a discoverability platform.

If you encounter a bug or unexpected behavior in promql-cli itself, open an issue at https://github.com/nalbury/promql-cli/issues.

Files

SKILL.md and 6 other files (references) in skills/promql-cli of samber/cc-skills.

SKILL.md
evals/evals.json
references/debugging.md
references/graphing.md
references/installation.md
references/promql-reference.md
references/usage.md

Open the folder on GitHubat commit 123cb15

Compare with similar skills

Promql CLI next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Promql CLI compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Promql CLI this skillsamber/cc-skills	228	—	~1.9k	Automated safety check: Pass	MIT	6 days ago
ML AIgrafana/skills	278	—	~1.3k	Automated safety check: Pass	Apache-2.0	yesterday
Happy Infra Metrics and Grafanaslopus/happy	24k	—	~2k	Automated safety check: Notes	MIT	today
Syncmetapawurb/hotpath-rs	1.9k	—	~1.2k	Automated safety check: Notes	MIT	today
Optimize Slurm TopologyNVlabs/alpasim	1.3k	—	~1.6k	Automated safety check: Pass	Apache-2.0	19 days ago
Dashboard Previewm4r1k/Eneru	149	—	~1.4k	Automated safety check: Pass	MIT	3 days ago

Similar skills

ML AI
grafana/skills
Official
Turn on AI + ML features in Grafana Cloud — Grafana Assistant (NL → PromQL/LogQL/TraceQL, dashboard build, incident investigation, MCP integration), Dynamic Alerting (Prophet forecasting + DBSCAN…
278 GitHub stars~1.3k tokensUpdated yesterday
DevOps & CloudAuto-check passed
Happy Infra Metrics and Grafana
slopus/happy
Queries live Prometheus metrics and manages Grafana dashboards as code for Happy's infrastructure, using the grafanactl CLI and the Grafana datasource proxy API.
24k GitHub stars~2k tokensUpdated today
DevOps & CloudAuto-check: notes
Syncmeta
pawurb/hotpath-rs
Sync changes from the hotpath, hotpath-macros and hotpath-drain crates to their meta counterparts (hotpath-meta, hotpath-macros-meta and hotpath-drain-meta).
1.9k GitHub stars~1.2k tokensUpdated today
DevOps & CloudAuto-check: notes
Optimize Slurm Topology
NVlabs/alpasim
Optimize AlpaSim Slurm topology throughput using persistent local Prometheus/Grafana telemetry and run artifacts.
1.3k GitHub stars~1.6k tokensUpdated 19 days ago
DevOps & CloudAuto-check passed
Dashboard Preview
m4r1k/Eneru
Visually verify Eneru browser-dashboard changes against a live daemon or audit an exact deployment.
149 GitHub stars~1.4k tokensUpdated 3 days ago
DevOps & CloudAuto-check passed
Alerting Irm
grafana/skills
Official
Configure Grafana Alerting, Incident Response Management (IRM), and SLOs end-to-end — provisions Grafana-managed and data-source-managed alert rules, contact points (Slack/PagerDuty/email/webhook)…
278 GitHub starsUsed in 1 repo~1.9k tokens
DevOps & CloudAuto-check passed

Questions about Promql CLI

What does Promql CLI do?

CLI for querying Prometheus and PromQL-compatible engines (Thanos, Cortex, VictoriaMetrics, Grafana Mimir, Grafana Tempo...) — instant queries, range queries, metric discovery (metrics/labels/meta…. Promql CLI is an agent skill from samber/cc-skills.) — instant queries, range queries, metric discovery (metrics/labels/meta subcommands), output formats (table/csv/json/graph).

When should I use Promql CLI?

Promql CLI fits situations like: tasks that involve Monitoring and alerting; tasks that involve Forecasting and time series.

How do I install Promql CLI in Claude Code?

Run `npx skills add samber/cc-skills --skill promql-cli -a claude-code`. Or copy the skill folder (skills/promql-cli in samber/cc-skills) into .claude/skills/promql-cli in your project. Claude Code loads it when a task matches its description.

How do I install Promql CLI in Codex?

Run `npx skills add samber/cc-skills --skill promql-cli -a codex`. Or copy the skill folder (skills/promql-cli in samber/cc-skills) into .agents/skills/promql-cli in your project. Codex loads it when a task matches its description.

Can I use Promql CLI in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add samber/cc-skills --skill promql-cli -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/promql-cli, .gemini/skills/promql-cli, .github/skills/promql-cli and .opencode/skills/promql-cli in your project.

What does Promql CLI need to run?

SKILL.md names no scripts, command-line tools or credentials: Promql CLI is instructions for the agent only. Our summary lists: Python 3. Its frontmatter pre-approves these tools: Read, Edit, Write, Glob, Grep, Agent, Bash(promql:*), mcp__context7__resolve-library-id, mcp__context7__query-docs, AskUserQuestion. Compatibility (from SKILL.md): Requires promql-cli and jq.

Does Promql CLI access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Promql CLI safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Promql CLI use?

Promql CLI is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Promql CLI use?

About 1.9k tokens (SKILL.md is roughly 7.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 5.8k tokens, read only when the agent opens those files.

What are the alternatives to Promql CLI?

Skills that share tags, products or a category with Promql CLI: ML AI (grafana/skills, 278 stars), Happy Infra Metrics and Grafana (slopus/happy, 24k stars), Syncmeta (pawurb/hotpath-rs, 1.9k stars) and Optimize Slurm Topology (NVlabs/alpasim, 1.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Promql CLI?

samber (a GitHub user) maintains it in samber/cc-skills, which has 228 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on October 1, 2026.

Source: samber/cc-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Promql CLI

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Compatibility

Context cost

Safety

SKILL.md

promql-cli — Prometheus Query CLI Skill

Reference Files

Setup Check

Quick Command Reference

Key Principles

Query Cost Rules

Files

Compare with similar skills

Similar skills

More from samber/cc-skills

Related

Questions about Promql CLI