How to use the Cloud Logging FinOps Auditor agent skill

What the skill makes the agent do

Once installed, the agent can investigate which services, log streams and severities generate the most log volume and cost in a Google Cloud project, and which log sinks route them. It reconciles billing export costs with volume metrics and produces a FinOps report with charts and copy-paste log exclusion filters.

The skill is designed to ask a few questions first and to make changes only with your approval. It is not meant for writing or running log queries for debugging; the skill itself points you to a different skill (cloud-logging-query-generation) for that.

Install the skill from the ZIP file

Download the ZIP for the skill from this page and unzip it. To make it available to Claude Code for all your projects, place the unzipped folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project

Prepare Python, gcloud and credentials

The skill runs Python scripts and gcloud commands against a live project, so it needs a few things in place first. The skill's setup step creates a Python virtualenv with uv and installs the packages listed in scripts/requirements.txt. You also need the Google Cloud SDK (gcloud) installed and authenticated with Application Default Credentials, and an active Cloud Billing account attached to the project.

The identity running the audit needs IAM roles such as roles/logging.viewer and roles/monitoring.viewer. Invoiced costs from the billing export need BigQuery roles, and billing-wide search needs cloudasset and billing viewer roles. The skill does not grant roles itself.

• Python with a uv-created virtualenv (installs from scripts/requirements.txt)
• Google Cloud SDK (gcloud), authenticated with Application Default Credentials
• An active Cloud Billing account attached to the project
• roles/logging.viewer and roles/monitoring.viewer for every audit
• BigQuery roles (roles/bigquery.jobUser, roles/bigquery.dataViewer) for invoiced costs
• cloudasset and billing viewer roles for billing-wide search

Trigger the skill with a natural request

You do not need special syntax. Ask for what you want in ordinary language, and name the project. The skill will confirm the project and then ask where the billing export is, so have the BigQuery table ID ready if you know it (project.dataset.table), or say you are not sure and let it search.

If you do not name a project, the skill uses the active gcloud project after confirming it with you.

• Audit the Cloud Logging costs for my project my-project and tell me where to cut.
• Find the top logging contributors in my project and generate exclusion filters.
• Make a FinOps report on our log sinks and the services driving log volume.

Understand the questions and the report

Before the collection finishes, the skill asks what the report should answer. You can choose any of five topics: where the money goes (attribution by service and stream), whether spend is growing (trends and projection), what you can safely turn off (savings actions), what the logs are saying (noisiest patterns and samples), and severity and audit-log posture. If you skip the question, all five are covered.

Cost figures depend on the billing mode you pick. With the billing export, figures are invoiced. Without it, the skill uses list-price estimates. The skill is written to state recoverable spend as a minimum, not as a maximum.

Safety notes: scripts and network access

The skill executes Python scripts and gcloud commands, and it uses the network to call Google Cloud APIs. Read the commands before they run, especially any that would enable an API or upgrade a log bucket. The skill is written to ask first: it enables APIs only after you approve, and it upgrades log buckets only with approval. Its audit is intended to be read-only otherwise.

For automated or scheduled runs, the skill is designed to ask nothing and to put any item that needed your decision, such as a disabled API or a missing role, into the report instead of acting on it.

Every gcloud command the skill runs is tagged with a usage attribution prefix that identifies only the skill and its version. The tag carries no user data.

• Review commands before approving them.
• The skill only enables APIs or upgrades log buckets with your approval.
• Scheduled runs use the billing search mode and never enable APIs or upgrade buckets.

Tips for a faster, cleaner audit

If the billing export search takes too long, you can answer with the table ID instead. The skill says that passing the table with --billing-table makes billing discovery take about two seconds on later runs. If you have no billing export for the project, the skill can use list-price estimates instead.

Keep the exclusion filters the skill produces as copy-paste candidates and test them before applying them to production sinks.

• Pass --billing-table=<table> on repeat runs to skip discovery.
• Give the billing search time on large billing accounts; progress prints every 30 seconds.
• If a run is slow, the collection profile table shows per-stage timings.