Skip to content
Get packs

Guide · Agent skill

How to use the Cloud Monitoring ListTimeSeries request agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This page explains how to use the cloud-monitoring-list-time-series-request agent skill, a set of instructions that lets an AI agent such as Claude build Google Cloud Monitoring ListTimeSeries REST requests. It is for engineers, SREs and cloud operators who already know which metric they want and need a correctly structured filter, time interval and aggregation. By the end you will know how to install the skill, how to phrase a request so the agent uses it, and what to check before you rely on the output.

Cloud Monitoring Time Series Requestsgoogle/skills · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in your project.
  2. 2Confirm your Project ID. Make sure the Google Cloud project ID is in your request or set in gcloud config, since the skill will not guess it.
  3. 3Name the metric and resource. Give the full metric type, such as compute.googleapis.com/instance/cpu/utilization, and the resource details you know, such as instance name or database ID.
  4. 4Ask for the request. Ask the agent to build a ListTimeSeries request, filter expression, or aggregation for that metric and time window.
  5. 5Check the filter and aggregation. Read the generated filter, interval and aligner/reducer settings and confirm they match your metric's metricKind and valueType.
  6. 6Validate before use. Run the query in a test setting or review it before using it in dashboards, scripts or production.

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file and optional reference files that an AI agent reads when a task matches the skill's description. This skill covers one narrow job: turning a Cloud Monitoring metric descriptor and resource details into a valid ListTimeSeries request.

Once installed, the agent produces the query parameters name, filter, interval.startTime, interval.endTime, aggregation.* and view. It applies rules for label prefixes, handles GCE instance names versus numeric IDs, and uses the Ops Agent memory and disk state rule. It asks for a Project ID rather than guessing one.

  • It builds the filter expression, time interval, and perSeriesAligner, crossSeriesReducer and groupByFields settings used for charts.
  • It does not choose which metric to monitor. For vague requests such as VM CPU usage, the skill points to the separate cloud-monitoring-metric-selection skill.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places depending on how you work.

For personal use across projects, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

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

Trigger the skill with natural requests

The agent loads the skill when your request matches its description. Ask for the thing it produces: a ListTimeSeries request, a JSON payload, a filter expression, or an aligner and reducer aggregation for a metric or chart. Include the metric type and resource details you have. Always include your Project ID, or make sure gcloud config has one set, because the skill will ask for it otherwise.

Do not expect it to find a metric for you. If you only describe a symptom, ask for metric selection first, then ask for the request.

  • Good: "Build a ListTimeSeries request for compute.googleapis.com/instance/cpu/utilization on instance-1 in project my-project, last 6 hours, as a chart."
  • Good: "Write the filter for Ops Agent memory percent_used on VMs, excluding free memory."
  • Weak: "Why is my server slow?" (this needs metric selection first)

What you need before you start

The skill needs a Google Cloud project ID, either given in the request or resolvable through gcloud config. It also expects the gcloud CLI if commands run in a terminal, and either the Cloud Monitoring MCP server or direct Cloud Monitoring API access for looking up the metric descriptor. The skill reads its own references/basic_aggregations.md and references/attribution.md files, so keep the folder intact.

If the agent cannot find the metric descriptor, it falls back to a direct Cloud Monitoring API call. The skill uses gcloud config get-value project to look up the project when it is not given.

  • Google Cloud project ID
  • gcloud CLI (for terminal commands)
  • Cloud Monitoring MCP server or direct API access
  • The skill's reference files, unchanged
gcloud config get-value project

Safety notes: scripts and network

This skill does not run scripts. It does use the network, because the requests it helps build are meant for Google Cloud APIs and the agent may call the Cloud Monitoring API or MCP server to read a metric descriptor.

When the agent runs gcloud, curl or MCP commands in a terminal, it tags them with a usage attribution value through the CLOUDSDK_METRICS_REQUEST_ATTRIBUTION variable and a User-Agent header. The skill tells the agent not to use gcloud config set for this, so the tag does not persist. The tag contains only the skill name and version, not user data. Do not put this tag into generated scripts, Terraform or application code.

  • No scripts are run by the skill.
  • Network use is for reading metric descriptors and for direct API calls.
  • Generated queries are not run against a live project by the skill, so check them before production use.

Tips for correct filters and aggregations

Give the metric type, metricKind, valueType and resource type if you have them, since the agent will use them directly. For multi-instance resources such as VMs or databases, the skill groups by the primary resource identifier so separate streams are not merged into one total.

For VMs, use the instance name in a metric label or system label rather than assigning it to resource.labels.instance_id, which expects a numeric ID. Ops Agent memory and disk percent_used metrics should be filtered with state != "free", not state = "used".

  • Use resource.labels.instance_id for VMs and resource.labels.database_id for databases.
  • Use metric.labels.instance_name or metadata.system_labels.name to match a VM by name.
  • Do not use resource.metadata.* in filters; that prefix is invalid.
  • Database IDs use the format project:instance.
metric.labels.state != "free"

What people use it for

  • Building a Cloud Monitoring chart query for a known VM CPU utilization metric.
  • Writing a filter that matches a Cloud SQL or Spanner database by its composite database_id.
  • Creating a ListTimeSeries call for Ops Agent memory usage that excludes free memory.
  • Preparing a JSON payload for a script that queries Cloud Monitoring over the REST API.

Frequently asked questions

How do I install the cloud monitoring list time series agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to use this skill?

You need a Google Cloud project ID, either given in the request or set through gcloud config. The skill also expects the gcloud CLI for terminal commands and either the Cloud Monitoring MCP server or direct API access to look up metric descriptors.

Does this skill choose which metric to monitor?

No. Choosing a metric is handled by the separate cloud-monitoring-metric-selection skill. This skill starts from a known metric type and builds the request for it.

Does the skill run scripts or use the network?

It does not run scripts. It does use the network, for reading metric descriptors and for direct Cloud Monitoring API calls, and it tags those calls with a usage attribution value.

Is this skill free to use and what is its licence?

The skill is published under the Apache-2.0 licence. This page does not state any price, so check the source repository for terms beyond the licence.

Why does my filter fail when I use a VM name?

Cloud Monitoring's resource.labels.instance_id expects a numeric ID, so a name like instance-1 will not match there. The skill filters by metric.labels.instance_name or metadata.system_labels.name instead, and it avoids resource.metadata.* which is invalid.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill is a good fit for engineers and SREs who already know the metric type and want correctly structured ListTimeSeries filters and aggregations, especially for VMs, databases and Ops Agent state labels. It is not suitable for vague troubleshooting, metric discovery, or anyone without a Google Cloud project, and its output should be validated before production use.

Download the skill