How to use the Cloud Monitoring PromQL Query Generator agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and supporting files that an AI agent reads when a task matches the skill's description. This one, cloud-monitoring-promql-query, is focused on turning a Cloud Monitoring metric and its resource details into a structured PromQL query.

Once installed, the agent chooses functions such as rate, sum or histogram_quantile based on the metric type. It follows rules from the skill, such as always filtering by monitored resource and not summing ratio metrics like CPU percentage across instances. A validator script then checks generated queries for the required syntax.

• Works from metric descriptors and resource parameters you provide, or looks them up through the Cloud Monitoring API.
• Requires a Google Cloud project ID before it generates anything.
• Checks query structure only, not whether the query returns correct results.

Install the skill from the ZIP download

Download the ZIP for this skill from this page and unzip it. The skill folder should contain SKILL.md, a references folder and a scripts folder.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only there.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Set up the requirements

The skill needs a Google Cloud project ID. You can give it in your request, or set a default with gcloud so the agent can read it with gcloud config get-value project.

For descriptor lookups and Cloud Monitoring API calls, the gcloud CLI must be installed and authenticated. The validator script needs Python 3 and the promql-parser package. The skill's instructions show the check it uses: install the package only if it is missing.

The Cloud Monitoring MCP server (google-cloud-monitoring) is optional. If it is not available, the skill falls back to direct Cloud Monitoring API calls.

• Google Cloud project ID, from your request or gcloud config
• gcloud CLI with authentication
• Python 3 with the promql-parser package for the validator
• Cloud Monitoring MCP server (optional, with direct API fallback)

Trigger the skill with natural requests

You do not need a special command. Ask for a PromQL query in plain language and include the details you have. The skill's description covers requests to create, generate, write or format PromQL queries, PromQL strings or PromQL aggregations for Cloud Monitoring metrics and resources.

Give the metric type and project if you know them. If you only know a rough description such as VM CPU usage, the skill first uses the cloud-monitoring-metric-selection skill to identify the metric. The skill does not choose metrics on its own.

• "Write a PromQL query for compute.googleapis.com/instance/cpu/utilization in project my-project, grouped by instance."
• "Generate a PromQL aggregation for this latency distribution metric in project my-project."
• "Format a PromQL string filtering gae_app by version_id in project my-project."

Example workflow and what to check

When a request is clear, the agent resolves the project ID, reads the metric descriptor, applies the resource filter and aggregation rules, then runs the validator on the query before showing it to you. If the project ID is missing and gcloud cannot supply one, the agent stops and asks you for it rather than using a placeholder.

Treat the output as a draft. Read the query, check the metric name and resource labels against your own setup, and test it in a non-production environment before it goes into a dashboard or alert.

• Confirm the project ID and metric type in the answer.
• Check that monitored_resource is set to the resource type you expect.
• Review aggregations, especially on ratio metrics such as CPU or memory percentages.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The validator at scripts/validate_promql.py checks query syntax. Its test file is scripts/validate_promql_test.py. The skill also calls gcloud, the Cloud Monitoring API, and optionally an MCP server.

The skill's attribution rules require gcloud commands run in the terminal to be prefixed with an environment variable that tags usage with the skill name and version. Read references/attribution.md if you want the exact rules. The skill also says these tags must not appear in generated scripts, Terraform or user code.

Review the skill files before installing, and run any command in a sandbox or non-production project if you are unsure.

• Scripts: validate_promql.py and validate_promql_test.py
• Network: calls to the Cloud Monitoring API and optional MCP server
• Attribution: gcloud commands in the terminal are tagged, not configured persistently

Tips for better results

Give exact values. The skill uses the literal resource names, namespaces and IDs you provide and does not replace them with resources it discovers, unless you ask it to find active resources.

If a generated query fails validation, the skill's error recovery reference covers common problems such as range versus instant vector mismatches, misplaced by or without clauses, and histogram_quantile bucket label mismatches. Ask the agent to apply that guidance and validate again.

• Include the project ID, metric type and any resource filter values in one request.
• For ratio metrics, ask for per-instance results rather than a total.
• For Cloud SQL databases, give the instance and project so the composite database_id can be formed correctly.