Skip to content

Commit 6cbdbae

Browse files
caohy1988claude
caohy1988
and
claude
committed
feat: add 1P BigQuery skill for guided data analysis workflows
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. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 991abd4 commit 6cbdbae

File tree

11 files changed

+1045
-1
lines changed

11 files changed

+1045
-1
lines changed

‎contributing/samples/1p_bigquery_skill/DESIGN.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Design: First-Party (1P) Skills for ADK Toolsets
2+
3+
## Problem
4+
5+
ADK toolsets like `BigQueryToolset` provide raw tools (e.g., `execute_sql`,
6+
`list_dataset_ids`) but no guidance on how to use them effectively. Developers
7+
must re-invent prompt engineering for each toolset, embedding workflow
8+
knowledge directly in agent instructions. This leads to:
9+
10+
- Duplicated effort across agent builders.
11+
- Inconsistent quality of analysis workflows.
12+
- No standard way to share toolset expertise.
13+
- Agent instructions that grow unwieldy as guidance accumulates.
14+
15+
## Solution
16+
17+
Pre-packaged skills that follow the
18+
[agentskills.io specification](https://agentskills.io/specification),
19+
consumed via ADK's existing `SkillToolset`. Zero new APIs, zero new classes.
20+
21+
A 1P skill is simply a spec-compliant skill directory that ships with ADK
22+
alongside its corresponding toolset. Users add both the toolset (for tools)
23+
and a `SkillToolset` (for guided workflows) to their agent.
24+
25+
```python
26+
# Before: raw toolset, no guidance
27+
root_agent = LlmAgent(tools=[bigquery_toolset])
28+
29+
# After: toolset + 1P skill for guided workflows
30+
bq_skill_toolset = SkillToolset(skills=[get_bigquery_skill()])
31+
root_agent = LlmAgent(tools=[bigquery_toolset, bq_skill_toolset])
32+
```
33+
34+
## How It Works
35+
36+
### Progressive Disclosure
37+
38+
The skill content is loaded in three levels, keeping context efficient:
39+
40+
1. **L1 - Metadata** (always in context): Skill name and description are
41+
returned by `list_skills`. The LLM sees what skills are available without
42+
loading full instructions.
43+
44+
2. **L2 - Instructions** (loaded on activation): When the LLM calls
45+
`load_skill(name="bigquery-data-analysis")`, it receives the SKILL.md
46+
body with step-by-step workflow guidance.
47+
48+
3. **L3 - References** (loaded on demand): When the LLM needs detailed
49+
patterns, it calls `load_skill_resource` to load specific reference
50+
files (e.g., `sql_patterns.md`, `error_handling.md`).
51+
52+
### Runtime Flow
53+
54+
```
55+
1. Agent starts -> SkillToolset injects skill system instruction
56+
2. User asks question -> LLM sees list_skills tool available
57+
3. LLM calls list_skills -> sees "bigquery-data-analysis" skill
58+
4. LLM calls load_skill("bigquery-data-analysis") -> gets workflow steps
59+
5. LLM follows steps, using BigQuery tools (execute_sql, etc.)
60+
6. LLM calls load_skill_resource for detailed patterns as needed
61+
```
62+
63+
### Directory Structure
64+
65+
```
66+
src/google/adk/tools/bigquery/
67+
├── bigquery_toolset.py # Existing: raw tools
68+
├── bigquery_skill.py # New: get_bigquery_skill() loader
69+
└── skills/
70+
└── bigquery-data-analysis/ # Spec-compliant skill directory
71+
├── SKILL.md # Frontmatter + workflow instructions
72+
└── references/
73+
├── sql_patterns.md
74+
├── schema_exploration.md
75+
└── error_handling.md
76+
```
77+
78+
## API Usage
79+
80+
### Before (tools only)
81+
82+
```python
83+
from google.adk.agents.llm_agent import LlmAgent
84+
from google.adk.tools.bigquery.bigquery_toolset import BigQueryToolset
85+
86+
bigquery_toolset = BigQueryToolset(credentials_config=creds)
87+
88+
root_agent = LlmAgent(
89+
model="gemini-2.5-flash",
90+
name="analyst",
91+
instruction="""You are a data analyst. When analyzing data:
92+
1. First explore schemas with list_dataset_ids, list_table_ids...
93+
2. Use get_table_info before writing queries...
94+
3. Always use LIMIT on exploratory queries...
95+
4. Use CTEs for complex queries...
96+
5. Handle errors by checking get_job_info...
97+
... (many lines of hand-written guidance)""",
98+
tools=[bigquery_toolset],
99+
)
100+
```
101+
102+
### After (tools + 1P skill)
103+
104+
```python
105+
from google.adk.agents.llm_agent import LlmAgent
106+
from google.adk.tools.bigquery.bigquery_toolset import BigQueryToolset
107+
from google.adk.tools.bigquery.bigquery_skill import get_bigquery_skill
108+
from google.adk.tools.skill_toolset import SkillToolset
109+
110+
bigquery_toolset = BigQueryToolset(credentials_config=creds)
111+
bq_skill_toolset = SkillToolset(skills=[get_bigquery_skill()])
112+
113+
root_agent = LlmAgent(
114+
model="gemini-2.5-flash",
115+
name="analyst",
116+
instruction="You are a data analyst. Use your tools and skills.",
117+
tools=[bigquery_toolset, bq_skill_toolset],
118+
)
119+
```
120+
121+
The curated guidance moves from fragile inline instructions into a
122+
structured, versioned, spec-compliant skill that the agent discovers
123+
and loads at runtime.
124+
125+
## Extension Guide
126+
127+
Other teams can follow the same pattern for their toolsets:
128+
129+
### 1. Create a Spec-Compliant Skill Directory
130+
131+
```
132+
src/google/adk/tools/<toolset>/skills/<skill-name>/
133+
├── SKILL.md # Required: YAML frontmatter + instructions
134+
└── references/ # Optional: detailed reference materials
135+
└── ...
136+
```
137+
138+
The directory name must match the `name` field in SKILL.md frontmatter.
139+
140+
### 2. Add a Convenience Loader
141+
142+
```python
143+
# src/google/adk/tools/<toolset>/<toolset>_skill.py
144+
145+
import pathlib
146+
from google.adk.skills import Skill, load_skill_from_dir
147+
148+
_SKILL_DIR = pathlib.Path(__file__).parent / "skills" / "<skill-name>"
149+
150+
def get_<toolset>_skill() -> Skill:
151+
return load_skill_from_dir(_SKILL_DIR)
152+
```
153+
154+
### 3. Users Combine Toolset + SkillToolset
155+
156+
```python
157+
from google.adk.tools.<toolset> import <Toolset>
158+
from google.adk.tools.<toolset>.<toolset>_skill import get_<toolset>_skill
159+
from google.adk.tools.skill_toolset import SkillToolset
160+
161+
toolset = <Toolset>(...)
162+
skill_toolset = SkillToolset(skills=[get_<toolset>_skill()])
163+
agent = LlmAgent(tools=[toolset, skill_toolset])
164+
```
165+
166+
### Candidate Toolsets
167+
168+
- **Spanner**: Schema design, transaction patterns, query optimization.
169+
- **Bigtable**: Row key design, filter patterns, scan optimization.
170+
- **PubSub**: Topic/subscription setup, message handling, dead-letter queues.
171+
172+
## Spec Compliance
173+
174+
The skill directory maps to [agentskills.io](https://agentskills.io/specification)
175+
fields as follows:
176+
177+
| Spec Field | Source |
178+
|------------|--------|
179+
| `name` | SKILL.md frontmatter `name` (must match directory name) |
180+
| `description` | SKILL.md frontmatter `description` |
181+
| `license` | SKILL.md frontmatter `license` |
182+
| `metadata` | SKILL.md frontmatter `metadata` |
183+
| `instructions` | SKILL.md body (after frontmatter) |
184+
| `references` | `references/` directory (loaded by `load_skill_resource`) |
185+
| `assets` | `assets/` directory (not used by this skill) |
186+
| `scripts` | `scripts/` directory (not used by this skill) |
187+
188+
ADK's `load_skill_from_dir()` validates name-directory match, parses YAML
189+
frontmatter, and loads all resource directories. `SkillToolset` provides
190+
the standard tools for skill discovery, loading, and resource access.

‎contributing/samples/1p_bigquery_skill/README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 1P BigQuery Skill Sample
2+
3+
This sample demonstrates the **1P (first-party) Skills** pattern: combining
4+
a raw toolset (`BigQueryToolset`) with a curated skill (`SkillToolset`) to
5+
give the agent both tools and guided workflows.
6+
7+
## What This Shows
8+
9+
- **BigQueryToolset** provides raw tools: `execute_sql`, `list_dataset_ids`,
10+
`get_table_info`, etc.
11+
- **SkillToolset** provides skill discovery and loading: `list_skills`,
12+
`load_skill`, `load_skill_resource`, `run_skill_script`.
13+
- The **bigquery-data-analysis** skill ships pre-packaged with ADK and
14+
follows the [agentskills.io specification](https://agentskills.io/specification).
15+
16+
The agent can discover the skill at runtime, load its instructions for
17+
guided workflows, and access reference materials on-demand.
18+
19+
## Setup
20+
21+
1. Install ADK with BigQuery extras:
22+
23+
```bash
24+
pip install google-adk[bigquery]
25+
```
26+
27+
2. Set up OAuth credentials:
28+
29+
- Create OAuth 2.0 credentials in the Google Cloud Console.
30+
- Update `agent.py` with your `client_id` and `client_secret`.
31+
32+
3. Run the sample:
33+
34+
```bash
35+
adk web contributing/samples
36+
```
37+
38+
4. Select `1p_bigquery_skill` from the agent list.
39+
40+
## How It Works
41+
42+
```
43+
User Query
44+
|
45+
v
46+
LlmAgent (gemini-2.5-flash)
47+
|
48+
+-- BigQueryToolset tools (direct data access)
49+
| list_dataset_ids, list_table_ids, get_table_info,
50+
| execute_sql, forecast, detect_anomalies, ...
51+
|
52+
+-- SkillToolset tools (guided workflows)
53+
list_skills -> discovers "bigquery-data-analysis"
54+
load_skill -> loads step-by-step instructions
55+
load_skill_resource -> loads sql_patterns.md, etc.
56+
run_skill_script -> executes skill scripts
57+
```
58+
59+
## Progressive Disclosure
60+
61+
The skill uses three levels of content:
62+
63+
1. **L1 - Metadata** (always available): skill name and description shown
64+
via `list_skills`.
65+
2. **L2 - Instructions** (on activation): full workflow steps loaded via
66+
`load_skill`.
67+
3. **L3 - References** (on demand): detailed SQL patterns, schema
68+
exploration guides, and error handling loaded via `load_skill_resource`.
69+
70+
This keeps the agent's context efficient while making deep knowledge
71+
available when needed.
72+
73+
## Extending This Pattern
74+
75+
Other toolsets can follow the same pattern:
76+
77+
1. Create a spec-compliant skill directory under `tools/<toolset>/skills/`.
78+
2. Add a `get_*_skill()` convenience loader.
79+
3. Users add both the toolset and `SkillToolset` to their agent's tools.

‎contributing/samples/1p_bigquery_skill/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
from . import agent

‎contributing/samples/1p_bigquery_skill/agent.py‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Example agent using BigQuery toolset with a 1P skill for guided workflows.
16+
17+
This sample demonstrates the pattern of combining a raw toolset (BigQueryToolset)
18+
with a curated skill (SkillToolset) to provide both tools and guided workflows
19+
to the agent.
20+
21+
Setup:
22+
1. Install ADK with BigQuery extras: pip install google-adk[bigquery]
23+
2. Configure OAuth credentials (see README.md)
24+
3. Run: adk web contributing/samples
25+
"""
26+
27+
from google.adk.agents.llm_agent import LlmAgent
28+
from google.adk.tools.bigquery.bigquery_credentials import BigQueryCredentialsConfig
29+
from google.adk.tools.bigquery.bigquery_skill import get_bigquery_skill
30+
from google.adk.tools.bigquery.bigquery_toolset import BigQueryToolset
31+
from google.adk.tools.skill_toolset import SkillToolset
32+
33+
# Configure BigQuery credentials.
34+
# Replace with your OAuth client credentials.
35+
credentials_config = BigQueryCredentialsConfig(
36+
client_id="YOUR_CLIENT_ID",
37+
client_secret="YOUR_CLIENT_SECRET",
38+
)
39+
40+
# BigQueryToolset provides the raw tools: execute_sql, list_dataset_ids, etc.
41+
bigquery_toolset = BigQueryToolset(
42+
credentials_config=credentials_config,
43+
)
44+
45+
# SkillToolset provides guided workflows via the 1P BigQuery skill.
46+
# The agent can discover and load the skill's instructions and references.
47+
bq_skill_toolset = SkillToolset(
48+
skills=[get_bigquery_skill()],
49+
)
50+
51+
root_agent = LlmAgent(
52+
model="gemini-2.5-flash",
53+
name="bigquery_skill_agent",
54+
instruction=(
55+
"You are a data analyst. Use your tools and skills to help"
56+
" users explore and analyze BigQuery data. When starting a new"
57+
" analysis task, use `list_skills` to discover available skills"
58+
" and `load_skill` to get step-by-step guidance."
59+
),
60+
tools=[bigquery_toolset, bq_skill_toolset],
61+
)

‎src/google/adk/tools/bigquery/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,11 @@
2828
"""
2929

3030
from .bigquery_credentials import BigQueryCredentialsConfig
31+
from .bigquery_skill import get_bigquery_skill
3132
from .bigquery_toolset import BigQueryToolset
3233

3334
__all__ = [
34-
"BigQueryToolset",
3535
"BigQueryCredentialsConfig",
36+
"BigQueryToolset",
37+
"get_bigquery_skill",
3638
]

0 commit comments

Comments
 (0)