# Cloud monitoring promql query

> Cloud monitoring promql query is an open-source agent skill for cloud and infrastructure. Builds valid PromQL queries for Google Cloud Monitoring metrics and resources. It is available on Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf and Goose.

- **Kind:** Skill
- **Pricing:** Open source
- **Platforms:** Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Goose
- **Website:** https://github.com/google/skills/tree/main/skills/cloud/cloud-monitoring-promql-query
- **Repository:** https://github.com/google/skills
- **GitHub stars:** 24,379
- **License:** Apache-2.0
- **Skill name:** cloud-monitoring-promql-query
- **Collection:** https://github.com/google/skills
- **Categories:** [cloud and infrastructure](https://ai-powered.com/categories/cloud-and-infrastructure)
- **Listing updated:** 2026-11-18

## About

This skill guides an agent through writing PromQL queries against Cloud Monitoring metrics. It maps a metric descriptor's metric kind, value type and monitored resource onto the right PromQL structure, including how metric names are normalized from Cloud Monitoring type strings, such as adding the bucket suffix for distribution metrics. It also covers resource filtering, including keeping the user's literal resource names and using composite identifiers where a resource requires them.

The workflow requires a Google Cloud project ID before any query is written, and it stops to ask the user if none can be found. When descriptors are missing, the agent is directed to a metric selection skill, the Cloud Monitoring MCP tool or a direct REST call to fetch resource label schemas. The skill ships a Python validation script that parses generated queries in one batch, plus reference guides for aggregation mapping and error recovery.

The skill expects gcloud access for project lookup and Python 3 with the promql-parser package for validation. Output is a single-line query with no comments, wrapped in a promql code block.

## When your agent uses it

> Generates valid PromQL queries from Cloud Monitoring metric descriptors and resource parameters. Use when asked to create, generate, write, or format PromQL queries, PromQL strings, or PromQL aggregations for Cloud Monitoring metrics and resources. Don't use for raw metric discovery or metric selection.

## What it can access

From a static check of the files on GitHub; nothing was run.

- [Runs Python scripts](https://github.com/google/skills/tree/HEAD/skills/cloud/cloud-monitoring-promql-query)
- [No network calls found in its scripts](https://github.com/google/skills/tree/HEAD/skills/cloud/cloud-monitoring-promql-query)
- [License: Apache-2.0](https://github.com/google/skills/tree/HEAD/skills/cloud/cloud-monitoring-promql-query)

## Features

- **Metric name normalization:** Converts Cloud Monitoring metric types into the colon-separated PromQL metric names used by Cloud Monitoring.
- **Resource filter handling:** Applies monitored_resource filters and picks the correct resource identifier labels for each resource type.
- **Aggregation mapping:** Maps metric kind, value type, aligner and reducer to PromQL functions such as rate, histogram_quantile, sum and avg.
- **Query validation script:** Runs a Python linter that parses generated PromQL queries in a batch and reports syntax or type errors.
- **Error recovery guide:** Provides fixes for common PromQL type mismatches and syntax errors found during validation.
- **Utilization aggregation rules:** Keeps ratio and percentage utilization metrics unaggregated or grouped by instance rather than summed.

## Good for

- Write a PromQL query for CPU utilization of a GKE cluster
- Build a histogram_quantile query for Cloud Functions execution times
- Create a PromQL aggregation of request counts grouped by service
- Generate a filtered query for a Cloud SQL database by its composite ID

## Install

### Claude Code

Copy the skill folder to `~/.claude/skills/cloud-monitoring-promql-query` to use it in all your projects:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/google/skills.git "$tmp" &&
mkdir -p ~/.claude/skills &&
rm -rf ~/.claude/skills/cloud-monitoring-promql-query &&
cp -R "$tmp/skills/cloud/cloud-monitoring-promql-query" ~/.claude/skills/cloud-monitoring-promql-query &&
rm -rf "$tmp"
```

For one project only, put the folder in `.claude/skills/cloud-monitoring-promql-query` inside it instead.

### Codex

Copy the skill folder to `~/.agents/skills/cloud-monitoring-promql-query` to use it in every repository:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/google/skills.git "$tmp" &&
mkdir -p ~/.agents/skills &&
rm -rf ~/.agents/skills/cloud-monitoring-promql-query &&
cp -R "$tmp/skills/cloud/cloud-monitoring-promql-query" ~/.agents/skills/cloud-monitoring-promql-query &&
rm -rf "$tmp"
```

For one repository only, put the folder in `.agents/skills/cloud-monitoring-promql-query` inside it instead.

### Cursor

Copy the skill folder to `~/.cursor/skills/cloud-monitoring-promql-query` to use it in every project:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/google/skills.git "$tmp" &&
mkdir -p ~/.cursor/skills &&
rm -rf ~/.cursor/skills/cloud-monitoring-promql-query &&
cp -R "$tmp/skills/cloud/cloud-monitoring-promql-query" ~/.cursor/skills/cloud-monitoring-promql-query &&
rm -rf "$tmp"
```

For one project only, put the folder in `.cursor/skills/cloud-monitoring-promql-query` inside it instead.

### Gemini CLI

Run in a terminal (add `--scope workspace` to install it for the current workspace only):

```sh
gemini skills install https://github.com/google/skills.git --path skills/cloud/cloud-monitoring-promql-query
```

Or copy the folder to `~/.gemini/skills/cloud-monitoring-promql-query` yourself.

### VS Code

For GitHub Copilot in VS Code, copy the skill folder to `~/.copilot/skills/cloud-monitoring-promql-query`:

```sh
tmp=$(mktemp -d) &&
git clone --depth 1 https://github.com/google/skills.git "$tmp" &&
mkdir -p ~/.copilot/skills &&
rm -rf ~/.copilot/skills/cloud-monitoring-promql-query &&
cp -R "$tmp/skills/cloud/cloud-monitoring-promql-query" ~/.copilot/skills/cloud-monitoring-promql-query &&
rm -rf "$tmp"
```

For one project only, put the folder in `.github/skills/cloud-monitoring-promql-query` inside it instead.

### Other agents

Get the folder:

```sh
git clone --depth 1 https://github.com/google/skills.git
```

Then copy `skills/skills/cloud/cloud-monitoring-promql-query` into your agent's skills folder as `cloud-monitoring-promql-query`. Agents that support SKILL.md read one folder per skill.

## FAQ

### What does the skill need before it writes a query?

It needs a Google Cloud project ID, taken from the prompt or from gcloud config. If none is available, the skill stops and asks the user for it.

### Does it find metrics for me?

Not on its own. Vague requests are sent to the cloud-monitoring-metric-selection skill, and known metric types are looked up with the list_metric_descriptors MCP tool or a direct API call.

### How are queries checked?

Generated queries are passed to scripts/validate_promql.py, which uses the promql-parser Python package, and failures are diagnosed with the error recovery reference.

### Which clients can use it?

The skill follows the shared agent skills format with no client-specific tooling, so it applies to all supported agents.

### How do I install Cloud monitoring promql query in Claude Code?

Copy the skill folder from GitHub to ~/.claude/skills/cloud-monitoring-promql-query to use it in all your projects, or to .claude/skills/cloud-monitoring-promql-query in one project.

### Does Cloud monitoring promql query run scripts?

Yes. It runs Python scripts. No network calls were found in its scripts. This comes from a static check of the files on GitHub; nothing was run. Read the files before you install it.

### Which AI agents can use Cloud monitoring promql query?

Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf and Goose. Each reads skills in the SKILL.md format from its own folder; the install steps on this page list them.

### What are the best alternatives to Cloud monitoring promql query?

The closest alternatives to Cloud monitoring promql query are Cloud monitoring alert configuration, Cloud monitoring metric selection, Gke observability, Cloud run alert configuration and Cloud monitoring list time series request.

## Where this comes from

- Description: from the skill's own SKILL.md.

## Alternatives

- [Cloud monitoring alert configuration](https://ai-powered.com/skills/cloud-monitoring-alert-configuration): Cloud monitoring alert configuration is an open-source agent skill for cloud and infrastructure.
- [Cloud monitoring metric selection](https://ai-powered.com/skills/cloud-monitoring-metric-selection): Cloud monitoring metric selection is an open-source agent skill for databases.
- [Gke observability](https://ai-powered.com/skills/gke-observability): Gke observability is an open-source agent skill for cloud and infrastructure.
- [Cloud run alert configuration](https://ai-powered.com/skills/cloud-run-alert-configuration): Cloud run alert configuration is an open-source agent skill for cloud and infrastructure.
- [Cloud monitoring list time series request](https://ai-powered.com/skills/cloud-monitoring-list-time-series-request): Cloud monitoring list time series request is an open-source agent skill for cloud and infrastructure.
- [Google cloud slo alert configuration](https://ai-powered.com/skills/google-cloud-slo-alert-configuration): Google cloud slo alert configuration is an open-source agent skill for cloud and infrastructure.
- [Bigquery observability](https://ai-powered.com/skills/bigquery-observability): Bigquery observability is an open-source agent skill for databases.
- [Cloud logging query generation](https://ai-powered.com/skills/cloud-logging-query-generation): Cloud logging query generation is an open-source agent skill for databases.

---
Source: https://ai-powered.com/skills/cloud-monitoring-promql-query
