Skill: theoseo/google-web-search (version 1.0.3)

--- name: google-web-search description: Enables grounded question answering by automatically executing the Google Search tool within Gemini models. Use when the required information is recent (post knowledge cutoff) or requires verifiable citation. metadata: { "openclaw": { "emoji": "🔍", "requires": { "env": ["GEMINI_API_KEY"] }, "primaryEnv": "GEMINI_API_KEY", "install": [ { "id": "python-deps", "kind": "shell", "command": "pip install -r {baseDir}/requirements.txt", "label": "Install Python dependencies (google-genai, pydantic-settings)", }, ], }, } --- # Google Web Search ## Overview This skill provides the capability to perform real-time web searches via the Gemini API's `google_search` grounding tool. It is designed to fetch the most current information available on the web to provide grounded, citable answers to user queries. **Key Features:** - Real-time web search via Gemini API - Grounded responses with verifiable citations - Configurable model selection - Simple Python API ## Usage This skill exposes the Gemini API's `google_search` tool. It should be used when the user asks for **real-time information**, **recent events**, or requests **verifiable citations**. ### Execution Context The core logic is in `scripts/example.py`. This script requires the following environment variables: - **GEMINI_API_KEY** (required): Your Gemini API key - **GEMINI_MODEL** (optional): Model to use (default: `gemini-2.5-flash-lite`) **Supported Models:** - `gemini-2.5-flash-lite` (default) - Fast and cost-effective - `gemini-3-flash-preview` - Latest flash model - `gemini-3-pro-preview` - More capable, slower - `gemini-2.5-flash-lite-preview-09-2025` - Specific version ### Python Tool Implementation Pattern When integrating this skill into a larger workflow, the helper script should be executed in an environment where the `google-genai` library is available and the `GEMINI_API_KEY` is exposed. Example Python invocation structure: ```python from skills.google-web-search.scripts.example import get_grounded_response # Basic usage (uses default model): prompt = "What is the latest market trend?" response_text = get_grounded_response(prompt) print(response_text) # Using a specific model: response_text = get_grounded_response(prompt, model="gemini-3-pro-preview") print(response_text) # Or set via environment variable: import os os.environ["GEMINI_MODEL"] = "gemini-3-flash-preview" response_text = get_grounded_response(prompt) print(response_text) ``` ### Troubleshooting If the script fails: 1. **Missing API Key**: Ensure `GEMINI_API_KEY` is set in the execution environment. 2. **Library Missing**: Verify that the `google-genai` library is installed (`pip install google-generativeai`). 3. **API Limits**: Check the API usage limits on the Google AI Studio dashboard. 4. **Invalid Model**: If you set `GEMINI_MODEL`, ensure it's a valid Gemini model name. 5. **Model Not Supporting Grounding**: Some models may not support the `google_search` tool. Use flash or pro variants.

path: README.md
content: # Google Web Search (Gemini Grounding)

Real-time web search using Gemini API's `google_search` grounding tool.

## Features

- ✅ Real-time web search with grounded citations
- ✅ Natural language answers (no JSON parsing needed)
- ✅ Configurable Gemini model selection
- ✅ Simple Python API

## Quick Start

### 1. Set API Key

```bash
export GEMINI_API_KEY=your_key_here
```

Get your API key at [Google AI Studio](https://aistudio.google.com/app/apikey)

### 2. Use in OpenClaw

```python
from skills.google-web-search.scripts.example import get_grounded_response

# Ask a question
answer = get_grounded_response("What is the weather in Seoul today?")
print(answer)
# Output: Natural language answer with citations
```

### 3. Optional: Change Model

```bash
export GEMINI_MODEL=gemini-3-pro-preview
```

Supported models:
- `gemini-2.5-flash-lite` (default) - Fast & cheap
- `gemini-3-flash-preview` - Latest flash
- `gemini-3-pro-preview` - More capable

## Use Cases

- 📰 Real-time news and events
- 💹 Current prices (stocks, crypto, etc.)
- 🌤️ Weather forecasts
- 📊 Latest statistics and data
- 🔍 Any information requiring recent sources

## How It Works

This skill uses Gemini's **grounding with Google Search** tool, which:
1. Executes a Google search for your query
2. Processes the search results
3. Generates a natural language answer
4. Includes verifiable citations

**Key advantage:** You get curated answers instead of raw search results.

## Requirements

- Python ≥ 3.11
- `google-genai` ≥ 1.50.0
- `pydantic-settings` ≥ 2.0.0

## Installation

The skill auto-installs Python dependencies using one of:

1. **[uv](https://github.com/astral-sh/uv)** (if available) - A fast Python package manager by Astral (creators of Ruff)
2. **pip** (fallback) - Standard Python package installer

```bash
# The install command checks for uv first, falls back to pip:
# command -v uv >/dev/null && uv sync || pip install -r requirements.txt
```

To install manually:
```bash
cd skills/google-web-search
pip install -r requirements.txt
```

## Credentials

This skill requires **one** environment variable:

| Variable | Required | Description |
|----------|----------|-------------|
| `GEMINI_API_KEY` | ✅ Yes | Your Gemini API key from [Google AI Studio](https://aistudio.google.com/app/apikey) |
| `GEMINI_MODEL` | ❌ No | Model to use (default: `gemini-2.5-flash-lite`) |

**Security tip:** Create a restricted API key with minimal permissions (only Gemini API access needed).

## License

Same as OpenClaw project


path: assets/example_asset.txt
content: # Example Asset File

This placeholder represents where asset files would be stored.
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.

Asset files are NOT intended to be loaded into context, but rather used within
the output Claude produces.

Example asset files from other skills:
- Brand guidelines: logo.png, slides_template.pptx
- Frontend builder: hello-world/ directory with HTML/React boilerplate
- Typography: custom-font.ttf, font-family.woff2
- Data: sample_data.csv, test_dataset.json

## Common Asset Types

- Templates: .pptx, .docx, boilerplate directories
- Images: .png, .jpg, .svg, .gif
- Fonts: .ttf, .otf, .woff, .woff2
- Boilerplate code: Project directories, starter files
- Icons: .ico, .svg
- Data files: .csv, .json, .xml, .yaml

Note: This is a text placeholder. Actual assets can be any file type.


path: pyproject.toml
content: [project]
name = "google-web-search-skill"
version = "1.0.0"
description = "Real-time web search using Gemini API's google_search grounding tool - natural language answers with verifiable citations."
requires-python = ">=3.11"
dependencies = [
    "google-genai>=1.50.0",
    "pydantic-settings>=2.0.0",
]


path: references/api_reference.md
content: # Google Search Tool Reference

This reference contains the core API invocation patterns for using the Google Search grounding tool with Gemini models.

## Python Usage (Recommended for execution)
The Python client handles the orchestration of search queries, result processing, and citation metadata extraction.

```python
from google import genai
from google.genai import types

client = genai.Client() # Assumes GEMINI_API_KEY is set in environment
grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)
config = types.GenerateContentConfig(tools=[grounding_tool])

response = client.models.generate_content(
    model="gemini-2.5-flash-preview", # Or gemini-3-pro-preview
    contents="Who won the euro 2024?",
    config=config,
)

# The response.text will contain grounded output with citation links
print(response.text)
```

## Response Metadata Key Fields

When successful, the response contains `groundingMetadata`:
- `webSearchQueries`: The queries the model generated.
- `groundingChunks`: The raw web sources retrieved.
- `groundingSupports`: Data linking the response text segments to the sources.

## Pricing Note
When using Gemini 3.x models, you are billed per search query executed. This does not apply to Gemini 2.5 models.

path: requirements.txt
content: google-genai>=1.50.0
pydantic-settings>=2.0.0


path: scripts/example.py
content: #!/usr/bin/env python3
"""
Core script for google-web-search skill.
This script handles the actual execution of the Google Search grounding tool.
NOTE: API Key should be retrieved from environment variables (e.g., GEMINI_API_KEY) or Skill Config.
"""
import os
import json
from google import genai
from google.genai import types
from pydantic_settings import BaseSettings, SettingsConfigDict

# --- Configuration Management ---
class GoogleSearchSettings(BaseSettings):
    """Configuration for the Google Search Tool."""
    model_config = SettingsConfigDict(
        env_file=".env",
        case_sensitive=False,
        extra="ignore"
    )
    # Keys are loaded from environment variables or .env file
    gemini_api_key: str = ""
    gemini_model: str = "gemini-2.5-flash-lite"  # Default model

SETTINGS = GoogleSearchSettings()
# -----------------------------------------------------------------------------

def get_grounded_response(prompt: str, model: str = None) -> str:
    """
    Executes the Google Search tool to provide a grounded response.
    
    Args:
        prompt: The user's query string.
        model: Optional model name to use (defaults to GEMINI_MODEL env var or gemini-2.5-flash-lite)
        
    Returns:
        str: The model's grounded response text, including citations metadata.
    """
    # Get API key from environment
    [REDACTED_SECRET]"GEMINI_API_KEY")
    if not [REDACTED_SECRET] "ERROR: GEMINI_API_KEY environment variable not set. Cannot ground search."
    
    # Get model from parameter, env var, or default
    if model is None:
        model = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash-lite")

    try:
        client = genai.Client([REDACTED_SECRET])
        
        # Define the tool configuration
        grounding_tool = types.Tool(
            google_search=types.GoogleSearch()
        )
        config = types.GenerateContentConfig(
            tools=[grounding_tool]
        )
        
        # Call the API
        response = client.models.generate_content(
            model=model,
            contents=prompt,
            config=config,
        )
        
        # Return the response text which contains grounded information and metadata
        return response.text

    except Exception as e:
        return f"ERROR during API call or grounding: {e}"

if __name__ == "__main__":
    # Direct test execution for demonstration.
    test_prompt = "What is the current status of the OpenClaw Gateway?"
    
    print(f"--- Running Direct Test with prompt: {test_prompt} ---")
    result = get_grounded_response(test_prompt)
    print(result)
    print("--- Test Complete ---")

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)