Agent skill

Analyze Usage

by openshift-eng in openshift-eng/ai-helpers

A skill your agent uses when analyzing BigQuery usage patterns, costs, and query performance for a GCP project

Apache-2.0Auto-check passedDatabases

Install Analyze Usage

skills CLI
$ npx skills add openshift-eng/ai-helpers --skill analyze-usage -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install openshift-eng/ai-helpers analyze-usage --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/openshift-eng/ai-helpers.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/bigquery-cost-analysis/skills/analyze-usage .claude/skills/analyze-usage && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
analyze-usage
GitHub stars
120
Token cost
~2.7k tokens
SKILL.md length
743 words
Files
1
Skills in repo
118
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when analyzing BigQuery usage patterns, costs, and query performance for a GCP project

  • Works in 7 steps: Validate Prerequisites → Collect Usage Data → Per-User Deep Dive Analysis → …
  • Analyzing BigQuery usage patterns
  • SKILL.md covers When to Use This Skill, Prerequisites, Parameters and Analysis Workflow, plus 5 more sections
  • Calls gcloud, brew and bq

What it does

Analyze Usage is an agent skill from openshift-eng/ai-helpers. Use when analyzing BigQuery usage patterns, costs, and query performance for a GCP project

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases, covering Data warehousing and Query optimization. It works with Google BigQuery and Google Cloud. The repository describes itself as: Developer productivity tools for Claude Code & other AI assistants. The licence is Apache-2.0.

When your agent uses it

  • Analyzing BigQuery usage patterns
  • Query performance for a GCP project

Example prompts

  • “/analyze-usage”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Validate Prerequisites
  2. Collect Usage Data
  3. Per-User Deep Dive Analysis
  4. Analyze Results and Identify Patterns
  5. Generate Optimization Recommendations
  6. Format Comprehensive Report
  7. Offer to Save Report

What it can do on your machine

Read from SKILL.md and the folder at commit a627176. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • gcloud
    • brew
    • bq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use gcloud, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Analyze Usage loads about 2.7k tokens when it runs. Until then it costs about 26 tokens; SKILL.md has 743 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~26
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from openshift-eng/ai-helpers at commit a627176, republished under its Apache-2.0 licence (© openshift-eng). 743 words, ~2,687 tokens.

Download SKILL.mdSave it as .claude/skills/analyze-usage/SKILL.md (or your agent's skills folder).
name
analyze-usage
description
Use when analyzing BigQuery usage patterns, costs, and query performance for a GCP project

Analyze BigQuery Usage

This skill performs comprehensive analysis of BigQuery usage patterns, costs, and query performance for a given project. It identifies expensive queries, heavy users, and provides actionable optimization recommendations.

When to Use This Skill

This skill is automatically invoked by the /bigquery-cost-analysis:analyze-usage command to perform usage analysis.

Prerequisites

  • Google Cloud SDK (bq command-line tool) must be installed
  • User must have BigQuery read access to the project
  • User must be authenticated (gcloud auth login)
  • User needs bigquery.jobs.list permission at minimum

Parameters

When invoked, this skill expects:

  • Project ID: The GCP project ID to analyze (required)
  • Timeframe: Time period for analysis in hours (e.g., 24, 168 for 7 days)

Analysis Workflow

1. Validate Prerequisites

First, verify the environment is ready:

  • Check if bq command is available
  • Verify project access
  • Parse timeframe into hours
2. Collect Usage Data

Execute the following BigQuery queries against INFORMATION_SCHEMA:

Total Usage Summary
sql
SELECT
  COUNT(*) as total_queries,
  ROUND(SUM(total_bytes_processed) / POW(10, 12), 2) as total_tb_scanned,
  ROUND(SUM(total_bytes_processed) / POW(10, 12) * 6.25, 2) as estimated_cost_usd
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @hours HOUR)
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND statement_type != 'SCRIPT'
Usage by User/Service Account
sql
SELECT
  user_email,
  COUNT(*) as query_count,
  ROUND(SUM(total_bytes_processed) / POW(10, 12), 2) as total_tb_scanned,
  ROUND(SUM(total_bytes_processed) / POW(10, 12) * 6.25, 2) as estimated_cost_usd,
  ROUND(AVG(total_bytes_processed) / POW(10, 9), 2) as avg_gb_per_query
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @hours HOUR)
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND statement_type != 'SCRIPT'
GROUP BY user_email
ORDER BY total_tb_scanned DESC
LIMIT 20
Top Individual Queries by Cost
sql
SELECT
  creation_time,
  user_email,
  job_id,
  ROUND(total_bytes_processed / POW(10, 12), 3) as tb_scanned,
  ROUND(total_bytes_processed / POW(10, 12) * 6.25, 2) as cost_usd,
  SUBSTR(query, 1, 200) as query_preview
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @hours HOUR)
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND statement_type != 'SCRIPT'
  AND total_bytes_processed > 0
ORDER BY total_bytes_processed DESC
LIMIT 20
Query Pattern Analysis
sql
SELECT
  SUBSTR(query, 1, 200) as query_pattern,
  COUNT(*) as execution_count,
  ROUND(SUM(total_bytes_processed) / POW(10, 12), 3) as total_tb_scanned,
  ROUND(AVG(total_bytes_processed) / POW(10, 9), 2) as avg_gb_per_execution,
  ANY_VALUE(user_email) as sample_user
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @hours HOUR)
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND statement_type != 'SCRIPT'
  AND total_bytes_processed > 0
GROUP BY query_pattern
HAVING execution_count > 10
ORDER BY total_tb_scanned DESC
LIMIT 15
3. Per-User Deep Dive Analysis

For the top 2-3 users by data scanned, perform detailed query pattern analysis:

sql
SELECT
  SUBSTR(query, 1, 300) as query_pattern,
  COUNT(*) as execution_count,
  ROUND(SUM(total_bytes_processed) / POW(10, 12), 3) as total_tb_scanned,
  ROUND(AVG(total_bytes_processed) / POW(10, 9), 2) as avg_gb_per_execution,
  MIN(creation_time) as first_execution,
  MAX(creation_time) as last_execution
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL @hours HOUR)
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND statement_type != 'SCRIPT'
  AND user_email = @user_email
  AND total_bytes_processed > 0
GROUP BY query_pattern
ORDER BY total_tb_scanned DESC
LIMIT 20

This reveals:

  • What each heavy user is querying
  • Patterns in their query behavior
  • Opportunities for user-specific optimizations
  • Whether queries are automated (service accounts) or manual (humans)
4. Analyze Results and Identify Patterns

Look for common issues:

Query Anti-Patterns:

  • SELECT * on large tables
  • Full table scans without WHERE clauses
  • High-frequency queries that could be cached
  • Queries scanning data unnecessarily (e.g., counting rows by scanning 40GB)
  • Missing partitioning filters
  • Repeated identical queries

User Behavior Patterns:

  • Service accounts with high query volume (automation candidates)
  • Deduplication checks that scan large amounts of data
  • Dashboard queries hitting raw tables instead of materialized views
  • Scheduled queries running too frequently

Cost Drivers:

  • Single expensive queries
  • High-volume low-cost queries (death by a thousand cuts)
  • Inefficient aggregations
  • Missing indexes/clustering
5. Generate Optimization Recommendations

For each issue found, provide:

  1. What: Describe the issue clearly
  2. Why: Explain why it's expensive
  3. How: Provide specific fix instructions
  4. Savings: Estimate potential cost reduction
  5. Difficulty: Rate implementation effort (easy/medium/hard)
  6. Priority: Based on impact and ease

Prioritization Framework:

  • Priority 1: High impact, easy wins (>$5/day saved, easy implementation)
  • Priority 2: Medium impact (>$2/day saved)
  • Priority 3: Architectural improvements (long-term benefits)
6. Format Comprehensive Report

Structure the output as:

markdown
# BigQuery Usage Analysis Report
**Project:** <project-id>
**Analysis Period:** Last <timeframe>
**Generated:** <timestamp>

## Executive Summary
- Total Queries Executed: <count>
- Total Data Scanned: <TB>
- Estimated Cost: $<amount>

### Key Findings
1. <Top issue with data/cost>
2. <Second major issue>
3. <Third issue>

## Usage by User/Service Account
<Table with top 10-20 users>

## Top Query Patterns
<Detailed breakdown of top patterns with recommendations>

## Per-User Analysis

### Top User 1: <user_email> (<TB> scanned, $<cost>)
<Summary of what this user does>

**Primary Query Types:**
1. <Pattern description> (<data scanned>)
   - Execution count
   - Average per query
   - Specific optimization recommendation

### Top User 2: <user_email> (<TB> scanned, $<cost>)
<Summary of what this user does>

**Primary Query Types:**
1. <Pattern description> (<data scanned>)
   - Execution count
   - Average per query
   - Specific optimization recommendation

## Top Individual Queries
<Table of most expensive queries>

## Optimization Recommendations

### Priority 1: High Impact, Easy Wins
1. **<Recommendation title>**
   - Issue: <description>
   - Fix: <specific steps>
   - Estimated Savings: <$/day or %>
   - Difficulty: Easy/Medium/Hard

### Priority 2: Medium Impact
...

### Priority 3: Architectural Improvements
...

## Cost Breakdown Summary
- Service Accounts: $<amount> (<percentage>)
- Human Users: $<amount> (<percentage>)
7. Offer to Save Report

After presenting the analysis, ask the user if they want to save it to a markdown file:

  • Suggest filename: bigquery-usage-<project-id>-<YYYYMMDD>.md
  • Include all analysis details
  • Format with proper markdown tables and sections
Show full SKILL.md (332 more words)Show less

Error Handling

Handle common issues by displaying a clear error message and suggesting a fix:

"bq command not found"

  • Provide installation instructions for user's platform
  • macOS: brew install google-cloud-sdk
  • Linux: Point to cloud.google.com/sdk
  • Verify PATH configuration

"Access Denied" errors

  • Guide user through gcloud auth login
  • Verify project access: bq ls --project_id=<project-id>
  • Check IAM permissions (need BigQuery Job User role minimum)

"Invalid project ID"

  • Verify project ID vs project name
  • List available projects: gcloud projects list
  • Check for typos

No data returned

  • Verify queries have run in the specified timeframe
  • Check region (try region-us, US, EU, etc.)
  • Ensure querying correct project

Query execution errors

  • Check INFORMATION_SCHEMA availability
  • Verify region-specific schema locations
  • Adjust queries for project's BigQuery setup

Implementation Notes

Cost Calculation
  • Use on-demand pricing: $6.25/TB (as of 2024-2025)
  • Note in report if project may have flat-rate pricing
  • Savings estimates are based on on-demand pricing
Region Handling
  • Default to region-us INFORMATION_SCHEMA
  • If queries fail, try US or EU
  • Consider making region configurable in future
Performance Considerations
  • All analysis queries are read-only
  • Use INFORMATION_SCHEMA (metadata only, very efficient)
  • Queries should complete in seconds
  • Longer timeframes (30 days) may take longer but still fast
Query Optimization
  • Use --format=json for easy parsing
  • Use --use_legacy_sql=false for standard SQL
  • Limit result sets to 20 rows unless the user requests more
  • Filter to completed queries only (state = 'DONE')

Example Output Insights

Good User Analysis Example:

### openshift-ci-data-writer (4.07 TB, $25.41)
This service account runs test run analysis and backend disruption monitoring.

**Primary Query Types:**
1. **TestRuns_Summary_Last200Runs** (3.02 TB - 74% of usage)
   - 96 executions using SELECT *
   - 31.41 GB per query
   - **Recommendation:** Replace SELECT * with specific columns.
     Estimated savings: $9-15/day

2. **BackendDisruption Lookups** (0.68 TB - 17% of usage)
   - 4,165 queries checking for job run names
   - **Recommendation:** Add clustering on JobName + JobRunStartTime.
     Implement result caching.

This level of detail helps users understand exactly what's driving their costs and how to fix it.

Success Criteria

A successful analysis should:

  1. Identify all queries scanning >100GB per execution
  2. Find high-frequency query patterns (>100 executions)
  3. Provide at least 3 actionable optimization recommendations
  4. Include cost estimates for top recommendations
  5. Offer clear next steps for the user
  6. Be formatted clearly and professionally

Future Enhancements

Add:

  • Trend analysis (compare current period to previous periods)
  • Query performance metrics (execution time, slot usage)
  • Automatic detection of partitioning opportunities
  • Cost anomaly detection (unusual spikes)
  • Integration with BigQuery Reservations data
  • Historical cost tracking over time

© openshift-eng, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugins/bigquery-cost-analysis/skills/analyze-usage of openshift-eng/ai-helpers.

Open the folder on GitHubat commit a627176

Compare with similar skills

Analyze Usage next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Analyze Usage compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Analyze Usage this skillopenshift-eng/ai-helpers120—~2.7kAutomated safety check: PassApache-2.0
BigQuery Slot and Cost Optimizergoogle/skills21k—~2.3kAutomated safety check: PassApache-2.0
Altimate Data Warehouse DelegateAltimateAI/data-engineering-skills127—~1.4kAutomated safety check: PassMIT
GCP Audit Logssickn33/agentic-awesome-skills47k2 repos~3.8kAutomated safety check: PassMIT
Imaging Data CommonsK-Dense-AI/scientific-agent-skills48k1 repos~7.8kAutomated safety check: PassMIT
Bigquery Bigframesgoogle/skills21k1 repos~1.3kAutomated safety check: PassApache-2.0

Similar skills

  • Official

    Analyzes BigQuery slot use, query costs and execution bottlenecks from INFORMATION_SCHEMA to diagnose slow queries, slot contention and unpartitioned scans.

    21k GitHub stars~2.3k tokensUpdated yesterday
    DatabasesAuto-check passed
  • Altimate Data Warehouse Delegate

    AltimateAI/data-engineering-skills

    Delegates dbt and warehouse tasks such as lineage, migrations and cost attribution to the altimate-code CLI agent and relays its answer back.

    127 GitHub stars~1.4k tokensUpdated 6 days ago
    DatabasesAuto-check passed
  • GCP Audit Logs

    sickn33/agentic-awesome-skills

    Configure GCP Cloud Audit Logs for compliance. An agent skill from sickn33/agentic-awesome-skills.

    47k GitHub starsUsed in 2 repos~3.8k tokens
    DatabasesAuto-check passed
  • Imaging Data Commons

    K-Dense-AI/scientific-agent-skills

    Queries and downloads public cancer imaging data from NCI Imaging Data Commons.

    48k GitHub starsUsed in 1 repo~7.8k tokens
    DatabasesAuto-check passed
  • Bigquery Bigframes

    google/skills

    Official

    Generates Python code using BigQuery DataFrames (BigFrames).

    21k GitHub starsUsed in 1 repo~1.3k tokens
    DatabasesAuto-check passed
  • Official

    Provides data-retrieval best practices, tool selection guidance, and performant SQL query syntax for BigQuery telemetry across INFORMATIONSCHEMA, Cloud Monitoring, and the REST API.

    21k GitHub stars~3.5k tokensUpdated yesterday
    DatabasesAuto-check passed

More from openshift-eng/ai-helpers

All 118 skills in this repo
  • Investigate CI Reliability

    openshift-eng/ai-helpers

    Find and independently validate actionable reliability defects across OpenShift release jobs and presubmits, then export portable issue handoffs.

    120 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed
  • Address Review PR

    openshift-eng/ai-helpers

    Fetch and address all PR review comments — categorize by priority, make code changes, post replies, and push.

    120 GitHub stars~2.9k tokensUpdated yesterday
    Auto-check passed
  • Categorize Activity Types

    openshift-eng/ai-helpers

    Categorize Jira issues into Red Hat Sankey Activity Type categories using MCP Jira tools.

    120 GitHub stars~2.4k tokensUpdated yesterday
    Auto-check passed
  • Has Review Work

    openshift-eng/ai-helpers

    Decide whether a GitHub PR has unanswered authorized review comments or new required CI failures worth a follow-up agent.

    120 GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed
  • Must Gather Analyzer

    openshift-eng/ai-helpers

    Analyze OpenShift must-gather diagnostic data including cluster operators, pods, nodes, and network components.

    120 GitHub stars~2.3k tokensUpdated yesterday
    Auto-check passed
  • Payload Autodl JSON

    openshift-eng/ai-helpers

    Schema for the autodl JSON data file produced by payload-analysis for database ingestion — you must use this skill whenever generating the autodl JSON file

    120 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check passed

Categories

Questions about Analyze Usage

What does Analyze Usage do?

A skill your agent uses when analyzing BigQuery usage patterns, costs, and query performance for a GCP project. Analyze Usage is an agent skill from openshift-eng/ai-helpers.

When should I use Analyze Usage?

Analyze Usage fits situations like: analyzing BigQuery usage patterns; query performance for a GCP project.

How do I install Analyze Usage in Claude Code?

Run `npx skills add openshift-eng/ai-helpers --skill analyze-usage -a claude-code`. Or copy the skill folder (plugins/bigquery-cost-analysis/skills/analyze-usage in openshift-eng/ai-helpers) into .claude/skills/analyze-usage in your project. Claude Code loads it when a task matches its description.

How do I install Analyze Usage in Codex?

Run `npx skills add openshift-eng/ai-helpers --skill analyze-usage -a codex`. Or copy the skill folder (plugins/bigquery-cost-analysis/skills/analyze-usage in openshift-eng/ai-helpers) into .agents/skills/analyze-usage in your project. Codex loads it when a task matches its description.

Can I use Analyze Usage in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add openshift-eng/ai-helpers --skill analyze-usage -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/analyze-usage, .gemini/skills/analyze-usage, .github/skills/analyze-usage and .opencode/skills/analyze-usage in your project.

What does Analyze Usage need to run?

Going by SKILL.md and its folder, Analyze Usage needs the command-line tools its instructions call (gcloud, brew and bq).

Does Analyze Usage access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Analyze Usage safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Analyze Usage use?

Analyze Usage is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Analyze Usage use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Analyze Usage?

Skills that share tags, products or a category with Analyze Usage: BigQuery Slot and Cost Optimizer (google/skills, 21k stars), Altimate Data Warehouse Delegate (AltimateAI/data-engineering-skills, 127 stars), GCP Audit Logs (sickn33/agentic-awesome-skills, 47k stars) and Imaging Data Commons (K-Dense-AI/scientific-agent-skills, 48k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Analyze Usage?

openshift-eng (a GitHub organization) maintains it in openshift-eng/ai-helpers, which has 120 GitHub stars. The repository holds 118 skills in this directory. The repository was last updated on October 6, 2026.

Source: openshift-eng/ai-helpers on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.