feat: add 1P BigQuery skill for guided data analysis

[caohy1988]

Summary

• Adds a pre-packaged BigQuery data analysis skill following the agentskills.io specification
• Users combine BigQueryToolset (raw tools) with SkillToolset (curated guidance) for progressive disclosure of workflow instructions and reference materials
• Purely additive — no existing files modified

New files (10)

File	Purpose
src/google/adk/tools/bigquery/skills/bigquery-data-analysis/SKILL.md	Spec-compliant skill: frontmatter + workflow instructions
src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/sql_patterns.md	SQL patterns reference (window functions, CTEs, etc.)
src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/schema_exploration.md	Schema exploration reference (INFORMATION_SCHEMA, profiling)
src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/error_handling.md	Error handling reference (common errors, quota, timeouts)
src/google/adk/tools/bigquery/bigquery_skill.py	get_bigquery_skill() convenience loader
contributing/samples/1p_bigquery_skill/__init__.py	Sample agent init
contributing/samples/1p_bigquery_skill/agent.py	Sample agent showing BigQueryToolset + SkillToolset pattern
contributing/samples/1p_bigquery_skill/README.md	Sample setup & usage docs
contributing/samples/1p_bigquery_skill/DESIGN.md	Design document (problem, solution, extension guide)
tests/unittests/tools/bigquery/test_bigquery_skill.py	7 unit tests

Test plan

• pytest tests/unittests/tools/bigquery/test_bigquery_skill.py -v — 7/7 tests pass
• Spec validation passes (_validate_skill_dir returns empty problems list)
• ./autoformat.sh clean
• Verify sample agent runs with adk web contributing/samples (requires BQ credentials)

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new first-party BigQuery data analysis skill to the ADK framework. This skill provides structured, guided workflows and comprehensive reference materials, allowing agents to leverage both raw BigQuery tools and curated expertise. The primary goal is to standardize and improve the quality of data analysis workflows, thereby reducing the need for extensive manual prompt engineering and making BigQuery interactions more efficient and reliable for agents.

Highlights

• New BigQuery Data Analysis Skill: A pre-packaged BigQuery data analysis skill has been added, adhering to the agentskills.io specification, to provide curated guidance for BigQuery operations.
• Enhanced Agent Capabilities: Users can now combine the raw BigQueryToolset with the new SkillToolset to enable progressive disclosure of workflow instructions and reference materials for agents.
• Additive Change: This feature is purely additive, introducing new files and functionality without modifying any existing core files.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• contributing/samples/1p_bigquery_skill/DESIGN.md
  • Added a design document outlining the problem, solution, and extension guide for first-party skills.
• contributing/samples/1p_bigquery_skill/README.md
  • Added a README file detailing the setup and usage instructions for the 1P BigQuery skill sample.
• contributing/samples/1p_bigquery_skill/init.py
  • Added an initialization file for the sample agent.
• contributing/samples/1p_bigquery_skill/agent.py
  • Added a sample agent demonstrating the integration of BigQueryToolset with SkillToolset for guided workflows.
• src/google/adk/tools/bigquery/bigquery_skill.py
  • Added a convenience loader function get_bigquery_skill to retrieve the pre-packaged BigQuery data analysis skill.
• src/google/adk/tools/bigquery/skills/bigquery-data-analysis/SKILL.md
  • Added the core BigQuery data analysis skill definition, including YAML frontmatter and step-by-step workflow instructions.
• src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/error_handling.md
  • Added a reference document for handling common BigQuery error codes, quota issues, and timeout strategies.
• src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/schema_exploration.md
  • Added a reference document on BigQuery schema exploration techniques, including INFORMATION_SCHEMA and column profiling.
• src/google/adk/tools/bigquery/skills/bigquery-data-analysis/references/sql_patterns.md
  • Added a reference document detailing common SQL patterns for BigQuery, such as window functions and CTEs.
• tests/unittests/tools/bigquery/test_bigquery_skill.py
  • Added unit tests to validate the BigQuery skill's functionality, spec compliance, and integration with SkillToolset.

Activity

• The pull request was generated using Claude Code.
• All 7 unit tests for test_bigquery_skill.py passed successfully.
• Spec validation for the skill directory passed, indicating no problems.
• The autoformat.sh script ran clean, ensuring code style compliance.
• Verification of the sample agent running with adk web contributing/samples is pending, as it requires BigQuery credentials.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @caohy1988, thank you for your contribution!

To move forward with your pull request, please address the following:

• Sign the Contributor License Agreement (CLA): Our records indicate that the CLA has not been signed. You can do so at https://cla.developers.google.com/.
• Associate an Issue: For new features like this, please create a GitHub issue that outlines the feature and then link it to this pull request.

These steps are necessary to ensure your contribution can be reviewed and merged. Thank you!

[gemini-code-assist]

Code Review

The pull request introduces a new 1P BigQuery skill for guided data analysis, which is a valuable addition for improving agent workflows. The design document, README, and skill content (SKILL.md, error_handling.md, schema_exploration.md, sql_patterns.md) are well-structured and provide clear guidance. The unit tests cover the skill's functionality and integration effectively. However, there are a couple of areas related to credential handling and string formatting in the sample agent that could be improved for better security and readability.

[gemini-code-assist]

Hardcoding client_id and client_secret directly in the agent.py file, even as placeholders, is not ideal for security and maintainability. It's best practice to load these sensitive credentials from environment variables or a secure configuration store to prevent accidental exposure and facilitate easier management across different environments.

Suggested change

	credentials_config = BigQueryCredentialsConfig(
	client_id="YOUR_CLIENT_ID",
	client_secret="YOUR_CLIENT_SECRET",
	credentials_config = BigQueryCredentialsConfig(
	client_id=os.environ.get("BIGQUERY_CLIENT_ID", "YOUR_CLIENT_ID"),
	client_secret=os.environ.get("BIGQUERY_CLIENT_SECRET", "YOUR_CLIENT_SECRET"),
	)

[gemini-code-assist]

It's generally recommended to avoid hardcoding sensitive information like client_id and client_secret directly in code files, even if they are placeholders in a sample. This practice can lead to accidental exposure if not handled carefully. Consider suggesting the use of environment variables or a secure configuration management system for these credentials.

[caohy1988]

Re: "There is no automatic inclusion" (DESIGN.md, Proposal §4)

Automatic inclusion would change existing BigQueryToolset behavior — users who only want raw tools would unexpectedly get 4 extra skill tools (list_skills, load_skill, load_skill_resource, run_skill_script) injected into their agent's context. This increases token usage and can interfere with agents that have their own custom instructions or skills. Keeping it opt-in preserves backward compatibility and lets users control exactly what goes into their agent's tool set.

[caohy1988]

Re: Directory Structure — moving skills to adk/integration/bigquery

Done in 73c918b. Skill files now live at their canonical location under google.adk.integration.bigquery:

src/google/adk/integration/bigquery/    # Canonical location
├── __init__.py                         # Exports get_bigquery_skill
├── bigquery_skill.py                   # Convenience loader
└── skills/
    └── bigquery-data-analysis/
        ├── SKILL.md
        └── references/

src/google/adk/tools/bigquery/
├── bigquery_toolset.py                 # Existing: raw tools
└── bigquery_skill.py                   # Alias → integration.bigquery

Both import paths work:

• Canonical: from google.adk.integration.bigquery import get_bigquery_skill
• Alias: from google.adk.tools.bigquery import get_bigquery_skill

This establishes integration/ as the home for toolset skills going forward, while keeping backward compatibility via the alias in tools/bigquery/. The same pattern applies when adding skills for Spanner, Bigtable, etc.

[caohy1988]

Re: Directory Structure — moving BigQuery tools to adk/integration/bigquery

Done in 3068d5e. All BigQuery source files (toolset, credentials, client, config, query/metadata/data-insights tools, skill, and skill directory) now live under the canonical location google.adk.integration.bigquery.

The old google.adk.tools.bigquery is a single __init__.py that:

1. Imports all submodules from integration.bigquery
2. Registers them in sys.modules under the alias paths (e.g., google.adk.tools.bigquery.client → same object as google.adk.integration.bigquery.client)
3. Re-exports BigQueryToolset, BigQueryCredentialsConfig, get_bigquery_skill

This ensures full backward compatibility — all existing imports, mock.patch.object targets, and submodule attribute access (including private _ names) work unchanged. All 163 BQ tests + 27 related tests pass.

# Both paths resolve to the same module object:
from google.adk.integration.bigquery import BigQueryToolset  # canonical
from google.adk.tools.bigquery import BigQueryToolset        # alias (same object)

DESIGN.md updated to reflect the new structure and backward-compatibility approach.

[caohy1988]

Re: API ergonomics — BigQueryToolset(load_skills=True)

An alternative to the two-line pattern:

# Current (explicit, two toolsets)
bigquery_toolset = BigQueryToolset(credentials_config=creds)
bq_skill_toolset = SkillToolset(skills=[get_bigquery_skill()])
agent = LlmAgent(tools=[bigquery_toolset, bq_skill_toolset])

# Proposed (single flag)
bigquery_toolset = BigQueryToolset(credentials_config=creds, load_skills=True)
agent = LlmAgent(tools=[bigquery_toolset])

Pros:

• Single-line UX — lower friction for the common case
• No need to know about SkillToolset or get_bigquery_skill() imports

Cons:

• Couples BigQueryToolset to SkillToolset — the toolset now needs to know about skills, breaking the current separation of concerns
• Adds a new parameter to an existing public API (BigQueryToolset.__init__)
• get_tools() behavior changes based on a flag (returns 10 tools vs 14 tools) — harder to reason about
• Less composable: what if you want the 1P skill + your own custom skills in one SkillToolset? The flag can't express that
• Sets a precedent: every toolset would need the same load_skills parameter

Could be a good Phase 2 convenience on top of the current composable primitives. The explicit two-toolset pattern ships first as the foundation, then we can add the flag as sugar if the pattern proves too verbose in practice.

[caohy1988]

Re: Why not Phase 1 — done.

Added load_skills=True flag to BigQueryToolset in f09a118. It's ~10 lines:

# Single-line UX
bigquery_toolset = BigQueryToolset(credentials_config=creds, load_skills=True)
agent = LlmAgent(tools=[bigquery_toolset])  # 10 BQ tools + 4 skill tools

• __init__ is already kw_only (*), so adding load_skills: bool = False is non-breaking
• Defaults to False — existing behavior unchanged, existing tests pass (165/165)
• Imports are lazy (inside if load_skills:) so no new dependencies when disabled
• Explicit SkillToolset pattern still available for custom skill composition