A lightweight, LLM-discoverable skill for analyzing Google ADK BigQuery Agent Analytics data. Built to the Agent Skills specification.
No server, no MCP — just a prompt skill with pre-built CTEs, query templates, and a structured analysis methodology that any AI coding assistant can use.
export GCP_PROJECT_ID="your-project-id"
export BQ_DATASET="your-dataset-id"
export BQ_TABLE="agent_events" # optional, defaults to agent_events
pip install google-cloud-bigqueryThis repo also includes plugins/bigquery-agent-analytics-tracing, a Claude
Code/Codex-oriented tracing bridge that emits rows in the same BigQuery Agent
Analytics agent_events format analyzed by this skill.
- Claude Code: install from the repo-local
.claude-plugin/marketplace.json. - Codex/other agents: use the
.codex-pluginpackage metadata and the Python SDK atplugins/bigquery-agent-analytics-tracing/sdk/python/bqaa_tracing.py. - The plugin maps coding-agent hooks to BQAA events such as
LLM_REQUEST,LLM_RESPONSE,TOOL_STARTING, andTOOL_COMPLETED.
See
plugins/bigquery-agent-analytics-tracing/README.md for setup and SDK examples.
plugins/bigquery-agent-analytics-mod writes the same agent_events rows from
inside the host coding-agent CLI as a mod (a JavaScript/TypeScript hooks
module) instead of settings-hook scripts. Its hooks never wait on BigQuery:
they queue rows in memory and a background writer streams them with
insertAll, with retries, a local dead-letter directory and /bqaa-backfill.
It also records each model request with its token usage and latency, and
subagents with their own spans. Use it or the tracing plugin against a table,
not both.
--marketplace needs v2.1.292 or later:
claude plugin install bigquery-agent-analytics-mod \
--marketplace haiyuan-eng-google/bigquery_agent_analytics_skill \
--config project=my-gcp-project --config dataset=agent_analyticsplugins/bigquery-agent-analytics-mod/QUICKSTART.md
walks through a sandbox of your own, joining what your team set up, and
the administrator's steps. See plugins/bigquery-agent-analytics-mod/README.md for the dataset
(setup.sh), installing from a clone, configuration, the event mapping,
sample rows and queries, and limitations.
Claude Code — add to CLAUDE.md or copy to .claude/skills/:
For agent analytics, use the skill at: bigquery-agent-analytics-skill/SKILL.md
Cursor — reference in .cursorrules:
@bigquery-agent-analytics-skill/SKILL.md
Clients without progressive disclosure — compile first:
python bigquery-agent-analytics-skill/scripts/compile.pyThen reference bigquery-agent-analytics-skill/compiled_skill.md.
"What's the error rate for my agents this week?"
"Which tool has the highest failure rate?"
"Compare latency across models for the last 30 days"
"Show me the delegation flow for trace abc123"
bigquery-agent-analytics-skill/ # Skill directory (matches name field)
├── SKILL.md # Core instructions (<100 lines)
├── references/ # Loaded on demand by the LLM
│ ├── schema.md # Full table schema + nested paths
│ ├── ctes.md # 5 mandatory base CTEs
│ ├── queries.md # 8 ready-to-run analytics queries
│ ├── failure-patterns.md # 11 diagnostic signal/cause/action mappings
│ └── examples.md # 3 complete prompt-to-execution walkthroughs
├── assets/
│ └── mermaid-template.md # Mermaid diagram template for delegation flows
└── scripts/
├── run_bq.py # Query executor with dry-run + auto env injection
└── compile.py # Inlines everything into compiled_skill.md
The skill is structured for efficient context usage per the Agent Skills spec:
| Layer | What loads | Token cost |
|---|---|---|
| Metadata | name + description from frontmatter |
~100 tokens |
| Instructions | Full SKILL.md body (gotchas, execution, methodology, output rules) |
~1,500 tokens |
| References | Individual files from references/ — only when needed |
On demand |
The LLM reads SKILL.md on activation and loads reference files only when it needs them (e.g., references/ctes.md when writing a query, references/failure-patterns.md when diagnosing results).
Every query goes through a mandatory dry-run before execution:
run_bq.py --dry-runestimates bytes scanned via the BigQuery API without running the jobrun_bq.py --max-gbsets a hard billing limit (default 1 GB)SKILL.mdinstructs the LLM to refuse execution if the dry-run exceeds the limit
| Environment Variable | Description | Required | Default |
|---|---|---|---|
GCP_PROJECT_ID |
Your GCP project ID | Yes | — |
BQ_DATASET |
BigQuery dataset name | Yes | — |
BQ_TABLE |
Table name | No | agent_events |
GOOGLE_APPLICATION_CREDENTIALS |
Path to service account JSON (if not using ADC) | No | — |
run_bq.py auto-replaces {PROJECT}, {DATASET}, {TABLE} in SQL from these env vars. The LLM never needs to ask the user for their config.
MIT