google-cloud-analyzer

name: google-cloud-analyzer description: > Use this skill when scanning GCP projects for idle or stale resources, estimating infrastructure costs, cleaning up unused GCP resources, reducing GCP bills, checking what's running in GCP, verifying gcloud authentication, finding old/stale resources by age, or checking Generative AI API usage (Gemini, Claude, Veo, Imagen, etc.). Covers all major billable services including Compute Engine, Dataflow, Vertex AI, Cloud SQL, GKE, Cloud Composer, and 30+ other services.

Google Cloud Analyzer

Scan GCP projects for idle and stale resources, estimate costs, and safely clean up with user confirmations.

Safety level: High — always confirm before deletion, never auto-delete.

Workflows

This skill provides focused workflows. Pick the one that matches the user's request.

General Rules

Apply these to ALL workflows:

Scanning

# ALWAYS set this before scanning to prevent interactive "Enable API?" prompts
export CLOUDSDK_CORE_DISABLE_PROMPTS=1

• Never enable APIs on projects just to scan them. If an API returns a permission error, skip that service silently.
• Suppress errors with 2>/dev/null on all scan commands.
• Always include creationTimestamp in output format so the user can see resource age.
• For a comprehensive single-project scan, use the bundled script: scripts/scan-project.sh PROJECT_ID (located relative to this SKILL.md file).

Context Reuse

• Before scanning, check if scan results already exist in this conversation. If the user already ran a scan or API usage check earlier in this session, reuse those results instead of re-scanning. Only re-scan if the user explicitly asks to refresh or if the earlier data is from a different project.

Model Names and Recommendations

• NEVER use model names from your training data. Model names change frequently (e.g., "Gemini 1.5" and "Claude 3.5 Sonnet" are deprecated). Your training data is likely outdated.
• Before recommending alternative models, always look up the current model names using one of these methods (in priority order):
  1. google-dev-knowledge MCP: search_documents(query="Vertex AI available Gemini models current") and search_documents(query="Anthropic Claude models on Vertex AI current")
  2. Web search for "Vertex AI supported models" or "Google Cloud Gemini models" with the current date
  3. gcloud ai models list --region=us-central1 --project=PROJECT_ID to see what's actually deployed
• Include the current date in any web search or doc lookup query to ensure you get the latest results.
• When recommending alternatives, always verify the model name exists before suggesting it.

Output Formatting

Always present results in well-formatted tables (Unicode box-drawing, 80-column width, subtotal row, pricing disclaimer). After presenting results, offer to export as CSV.

See references/output-formatting.md for table templates, CSV export format, and recommendation formatting rules.

Workflow: Auth Check

Verify gcloud authentication and setup before any scanning.

# Step 1: Check if gcloud is installed
which gcloud && gcloud --version | head -3

# Step 2: Check current auth status
gcloud auth list

# Step 3: Check active project
gcloud config get-value project

# Step 4: Test if tokens are valid (a lightweight API call)
gcloud projects list --limit=1 --format="value(projectId)"

If tokens are expired: Prompt the user to run gcloud auth login in their own terminal (requires browser interaction for OAuth consent). The skill cannot do this non-interactively.

If multiple accounts are listed: Ask the user which account to use, then set it:

gcloud config set account <ACCOUNT>

Workflow: Scan Project

Scan the current (or a specified) project for all billable resources. Run scans in parallel using subagents where possible — each scan is independent.

Parallel Scanning Strategy

Quick pre-scan: Run Recommender API first to get GCP's built-in idle resource recommendations before deep scanning:

# Quick idle resource check via Recommender API
for recommender in google.compute.instance.IdleResourceRecommender google.compute.disk.IdleResourceRecommender google.compute.address.IdleResourceRecommender google.cloudsql.instance.IdleRecommender; do
  gcloud recommender recommendations list --project=$PROJECT --location=us-central1 \
    --recommender=$recommender --format="table(name.basename(),description,primaryImpact.costProjection.cost)" 2>/dev/null
done

Use subagents (Task tool in Claude Code) or sequential commands (Gemini CLI) to scan 4 categories:

1. Compute & Networking — VMs, MIGs, Dataflow, GKE, Cloud Workstations, LBs, VPN, IPs
2. AI/ML — Vertex AI endpoints, Agent Engine, Feature Stores, Workbench, TPUs, Tensorboards, Vector Search
3. Databases & Storage — Cloud SQL, Spanner, Bigtable, AlloyDB, Redis, Filestore, GCS
4. Apps & Data Processing — Cloud Run, Functions, Composer, Dataproc, App Engine

See the reference files for detailed commands:

• references/compute-networking.md — Compute Engine, Dataflow, GKE, networking commands
• references/ai-ml-services.md — Vertex AI, TPU, Tensorboard commands
• references/databases-storage.md — Database and storage scan commands

Quick Scan (Single Project)

export CLOUDSDK_CORE_DISABLE_PROMPTS=1
PROJECT="PROJECT_ID"

# Compute
gcloud compute instances list --project=$PROJECT \
  --format="table(name,zone,status,machineType.basename(),creationTimestamp)" 2>/dev/null

# Dataflow (check each region)
for region in us-central1 us-west1 us-east1 us-east4 europe-west1 europe-west4; do
  gcloud dataflow jobs list --project=$PROJECT --region=$region \
    --status=active --format="table(id,name,type,state,createTime)" 2>/dev/null
done

# Vertex AI Endpoints (REST API — shows deployed models)
TOKEN=$(gcloud auth print-access-token)
for region in us-central1 us-west1 us-east1 europe-west1; do
  curl -s -H "Authorization: Bearer $TOKEN" \
    "https://${region}-aiplatform.googleapis.com/v1/projects/$PROJECT/locations/${region}/endpoints" 2>/dev/null
done

# GKE
gcloud container clusters list --project=$PROJECT \
  --format="table(name,location,status,currentNodeCount)" 2>/dev/null

# Cloud SQL
gcloud sql instances list --project=$PROJECT \
  --format="table(name,databaseVersion,settings.tier,region,state)" 2>/dev/null

# Cloud Composer (must loop regions — --locations=- is NOT valid)
for region in us-central1 us-east1 us-west1 europe-west1 europe-west4; do
  gcloud composer environments list --project=$PROJECT --location=$region 2>/dev/null
done

For the full scan, use the bundled script: scripts/scan-project.sh PROJECT_ID

Workflow: Scan All Projects

Discover all accessible projects and scan each one.

# List all accessible projects
gcloud projects list --format="table(projectId,name,projectNumber)"

Present the project list to the user. Ask if they want to scan all projects or a subset.

Smart Project Pre-Filter

Before scanning all projects, filter to only those with active APIs to avoid noise:

export CLOUDSDK_CORE_DISABLE_PROMPTS=1

# Quick filter: only scan projects where compute API is already enabled
SCANNABLE_PROJECTS=""
for project in $(gcloud projects list --format="value(projectId)"); do
  if gcloud compute instances list --project=$project --limit=0 2>/dev/null; then
    SCANNABLE_PROJECTS="$SCANNABLE_PROJECTS $project"
  fi
done

echo "Projects with active Compute API: $SCANNABLE_PROJECTS"

Present the filtered list to the user. Then scan only those:

for project in $SCANNABLE_PROJECTS; do
  echo ""
  echo ">>>>>>>>>> SCANNING: $project <<<<<<<<<<"
  bash scripts/scan-project.sh "$project"
done

Using Active Assist / Recommender API

GCP has built-in cost recommendations. Check for idle resource recommendations:

gcloud recommender recommendations list \
  --project=PROJECT_ID \
  --location=ZONE_OR_REGION \
  --recommender=google.compute.instance.IdleResourceRecommender \
  --format="table(name,description,primaryImpact.costProjection.cost)" 2>/dev/null

Other useful recommenders:

• google.compute.disk.IdleResourceRecommender — idle disks
• google.compute.address.IdleResourceRecommender — unused IPs
• google.cloudsql.instance.IdleRecommender — idle Cloud SQL

Workflow: Scan by Age

Filter resource scans by creation date. Use this when the user asks to find old/stale resources or ignore recently created ones.

Date Filter Reference

gcloud supports ISO 8601 relative durations in --filter:

If the user doesn't specify an age threshold, ask them. Default suggestion: 6 months (-P6M).

Example: Scan for resources older than 6 months

export CLOUDSDK_CORE_DISABLE_PROMPTS=1
PROJECT="PROJECT_ID"
AGE_FILTER="creationTimestamp<-P6M"

# Old VMs
gcloud compute instances list --project=$PROJECT \
  --filter="$AGE_FILTER" \
  --format="table(name,zone,status,machineType.basename(),creationTimestamp)" 2>/dev/null

# Old orphaned disks
gcloud compute disks list --project=$PROJECT \
  --filter="NOT users:* AND $AGE_FILTER" \
  --format="table(name,zone,sizeGb,type.basename(),creationTimestamp)" 2>/dev/null

# Old snapshots
gcloud compute snapshots list --project=$PROJECT \
  --filter="$AGE_FILTER" \
  --format="table(name,diskSizeGb,storageBytes,creationTimestamp)" 2>/dev/null

# Old static IPs (unused)
gcloud compute addresses list --project=$PROJECT \
  --filter="status=RESERVED AND $AGE_FILTER" \
  --format="table(name,region,address,creationTimestamp)" 2>/dev/null

# Old Cloud SQL instances
gcloud sql instances list --project=$PROJECT \
  --filter="$AGE_FILTER" \
  --format="table(name,databaseVersion,settings.tier,region,state,createTime)" 2>/dev/null

Age filter compatibility by service:

Not all gcloud commands support ISO 8601 duration filters. For services that don't, list all resources and filter by date in post-processing (with Python or manual review).

GCS Buckets: gcloud storage buckets list --format="value(name,timeCreated)" may return empty timeCreated. Use JSON output instead:

gcloud storage buckets list --project=$PROJECT --format=json 2>/dev/null | \
  python3 -c "
import sys, json
for b in json.load(sys.stdin):
    print(f\"{b.get('name','?')}  {b.get('timeCreated','unknown')}\")
" 2>/dev/null

Combining with other workflows

The age filter can be combined with any scan workflow. For example, "Scan all projects for resources older than 1 year" combines Scan All Projects + Scan by Age.

Workflow: API Usage

Show which Generative AI APIs are enabled, how much each model is being used, and what it's costing. This covers Gemini, Claude (via Vertex), Veo, Imagen, and other AI APIs.

See references/genai-api-usage.md for detailed commands, Cloud Monitoring queries, and BigQuery SQL.

Steps

1. List enabled GenAI APIs — filter gcloud services list for AI/ML APIs
2. Check token usage by model — query Cloud Monitoring token_count metric (see reference for curl commands)
3. Get billing costs — if BigQuery billing export is set up, run SQL queries for per-SKU breakdown

export CLOUDSDK_CORE_DISABLE_PROMPTS=1
PROJECT="PROJECT_ID"

# Step 1: List enabled AI/ML APIs
gcloud services list --enabled --project=$PROJECT \
  --filter="NAME:(aiplatform OR generativelanguage OR vision OR videointelligence OR speech OR translate OR documentai OR language OR automl)" \
  --format="table(NAME,TITLE)" 2>/dev/null

Key APIs: aiplatform.googleapis.com (Vertex AI), generativelanguage.googleapis.com (Gemini Developer API). See references/genai-api-usage.md for the full API reference table, token usage monitoring commands, and BigQuery billing queries.

Pricing accuracy: Cost estimates use approximate list pricing from Feb 2026. For real-time pricing, use google-dev-knowledge MCP or check references/cost-reference.md under "Getting Real-Time Pricing". Always include a disclaimer when presenting cost estimates.

Workflow: Cost Report

Before scanning: Check if infrastructure scan results or API usage data already exist in this conversation. If so, reuse them to build the cost report — do NOT re-scan.

After scanning (or reusing existing data), present results in a consolidated cost estimation table. See references/cost-reference.md for pricing data.

IMPORTANT: All cost estimates are approximate based on list pricing as of February 2026. They are for rough prioritization only and may not reflect actual billing (which depends on discounts, region, and agreements). Always include this disclaimer when presenting cost tables to the user.

For accurate pricing: If the google-dev-knowledge MCP is available, use it to look up current pricing before estimating. Otherwise, note the reference date and recommend the user verify at https://cloud.google.com/products/calculator

Example Output Format

PROJECT: dryrun01
+---------------------------+-----------+----------------+--------+--------------+------------+
| Resource                  | Type      | Machine        | Status | Running Since| Est. $/mo  |
+---------------------------+-----------+----------------+--------+--------------+------------+
| beamapp-jupyter-...-mw1i  | Dataflow  | 1x n1-std-2    | Stream | Jan 2023     | ~$64       |
| fraudfinder_logreg_ep     | Vertex EP | n1-standard-4  | Deploy | Feb 2023     | ~$97       |
| my-sql-instance           | Cloud SQL | db-n1-std-4    | Active | Mar 2022     | ~$200      |
+---------------------------+-----------+----------------+--------+--------------+------------+
                                                        Subtotal: ~$361/month

Exclusion Rules

Before presenting the table, automatically exclude resources the user likely wants to keep:

• VMs created in the last 24 hours (likely active work) — creationTimestamp>-P1D
• Cloud Workstation VMs (managed by Workstations service)
• Resources the user explicitly marked as "keep" in previous interactions
• Vertex AI API-only usage (Gemini, Claude via Vertex) — these are pay-per-call, not infrastructure
• Cloud Run services with 0 minInstances (scale-to-zero, negligible cost)

Flag these as "Excluded (likely active)" at the bottom of the table.

Workflow: Cleanup

Interactive selection and deletion of resources. This is a multi-phase workflow that requires explicit user confirmation at each step.

Step 1: Present the cost table and ask what to delete

Let the user choose:

• Select all — delete everything in the table
• Select by project — delete all resources in specific projects
• Select individually — pick specific resources

Step 2: First confirmation — Summary of what will be deleted

You are about to delete the following resources:

PROJECT: dryrun01
  - Cancel Dataflow job: beamapp-jupyter-...-mw1i (streaming since Jan 2023)
  - Undeploy model from: fraudfinder_logreg_endpoint (n1-standard-4)

PROJECT: ff02-374206
  - Cancel Dataflow job: beamapp-jupyter-...-6v5c (streaming since Jan 2023)
  - Delete VM: python-20230109 (terminated, disk only)

Estimated monthly savings: ~$XXX/month

THIS ACTION IS IRREVERSIBLE for Dataflow jobs and deleted VMs.
Vertex AI models can be re-deployed from the Model Registry if needed.

Step 3: Second confirmation — Explicit consent

• "Do you want to proceed with deleting these resources? (Yes/No)"
• If deleting > 10 resources or estimated savings > $500/month, add an extra warning

Step 4: Execute deletions in correct order

Delete in this order to avoid orphaned resources and respawning VMs:

1. Dataflow jobs — Cancel so they stop spawning worker VMs
2. Vertex AI model undeployments — Release VMs/TPUs
3. Feature Store deletions — Delete with force=true
4. Vector Search index undeploy — Undeploy indexes, then delete endpoints
5. Training jobs / Custom jobs — Cancel running jobs
6. Database services — Cloud SQL, Spanner, Bigtable, AlloyDB, Redis
7. Composer environments — Before removing GKE clusters
8. GKE clusters — Remove managed Kubernetes clusters
9. VM deletions — Delete with --delete-disks=all
10. MIG deletions — Delete managed instance groups and templates
11. Empty endpoints cleanup — Delete endpoints with no deployed models
12. Cloud Run / Functions / App Engine — If selected
13. Networking — Forwarding rules, VPN, NAT, unused IPs
14. Storage cleanup — Orphaned disks, snapshots, Tensorboards

Step 5: Report progress

[1/12] Cancelled Dataflow job in dryrun01 ............ OK
[2/12] Cancelled Dataflow job in ff02-374206 ......... OK
[3/12] Undeployed model from dryrun01 endpoint ....... OK
...

Step 6: Verification

After all deletions complete, run a verification sweep:

gcloud compute instances list --project=PROJECT_ID --filter="status=RUNNING" 2>/dev/null
gcloud dataflow jobs list --project=PROJECT_ID --region=REGION --status=active 2>/dev/null
gcloud compute disks list --project=PROJECT_ID --filter="NOT users:*" 2>/dev/null
gcloud compute addresses list --project=PROJECT_ID --filter="status=RESERVED" 2>/dev/null

Present final summary:

CLEANUP COMPLETE

Deleted: 10 Dataflow jobs, 18 Vertex AI models, 4 VMs, 6 Feature Stores
Estimated monthly savings: ~$6,800/month

Still running (excluded):
  - 3x Cloud Workstation VMs (kaggle-on-gcp) — created today
  - 3x Cloud Run services (scale-to-zero, minimal cost)

Safety Rules

See references/safety-rules.md for the complete safety rules and common gotchas.

Critical rules:

1. Never delete without explicit user confirmation — always show what will be deleted and ask
2. Never delete resources created in the last 24 hours unless explicitly selected
3. Never auto-delete Cloud Workstations — scan for visibility, never delete without explicit user confirmation
4. Cancel Dataflow jobs before deleting worker VMs — otherwise VMs respawn
5. Always use --delete-disks=all when deleting VMs
6. Explain undeploy vs delete for Vertex AI endpoints
7. Never touch billing account settings — only delete/stop individual resources
8. Delete in the correct order — see cleanup workflow deletion order
9. Never enable APIs on projects just to scan them — skip silently if API is not enabled
10. Always use CLOUDSDK_CORE_DISABLE_PROMPTS=1 to suppress interactive prompts during scans

Prerequisites

• gcloud CLI installed and authenticated (minimum version 450+)
• Access to target GCP projects
• Recommended: google-dev-knowledge MCP server for real-time doc lookups