Google AI Mode Skill
Query Google's AI Search mode to retrieve comprehensive, source-grounded answers from across the web.
When to Use This Skill
Trigger this skill when the user:
- Requests current information beyond the knowledge cutoff (post-January 2025)
- Needs documentation or API references for libraries and frameworks
- Asks for coding examples or implementation patterns
- Wants technical comparisons or best practices
- Requires research with citations and sources
- Mentions "Google AI search", "Google AI mode", or "web research"
CLI Flags
Essential Flags
--debug - Enable comprehensive logging
python scripts/run.py search.py --query "..." --debug
- Saves detailed logs to
logs/search_YYYY-MM-DD_HH-MM-SS.log
- Logs every step: browser launch, CAPTCHA detection, AI content waiting, citation extraction
- Essential for troubleshooting CAPTCHA issues or failed searches
- Log file path printed at completion
--save - Save results to skill folder
python scripts/run.py search.py --query "..." --save
- Saves markdown to
results/YYYY-MM-DD_HH-MM-SS_Query_Name.md
- Timestamped filename for organized storage
- Results preserved in skill directory for future reference
- Use instead of
--output for automatic naming
Combined usage (recommended for debugging):
python scripts/run.py search.py --query "..." --debug --save
Other Flags
--show-browser - Show browser window (for CAPTCHA solving)
python scripts/run.py search.py --query "..." --show-browser
--output <path> - Custom output file path
python scripts/run.py search.py --query "..." --output result.md
--json - Include JSON metadata in output
python scripts/run.py search.py --query "..." --output result.md --json
Query Optimization Strategy
CRITICAL: Always optimize user queries before execution. Google AI Mode's quality depends on query precision.
Optimization Template
[Technology/Topic] [Version] [Year] ([Specific Aspect 1], [Aspect 2], [Aspect 3]). [Output format request].
Optimization Rules
- Include Current Year (2026) for up-to-date results
- Use parentheses to list specific aspects needed
- Request structured output (tables, comparisons, categorized lists)
- Include version numbers for library/framework queries
Examples
| User Query | Optimized Query |
|---|
| "React hooks" | "React hooks best practices 2026 (useState, useEffect, custom hooks, common pitfalls). Provide code examples." |
| "What's new in Rust?" | "Rust 1.75 new features 2026 (async traits, impl Trait improvements, const generics, stabilized APIs). Include migration guide and code examples." |
| "PostgreSQL vs MySQL performance?" | "PostgreSQL vs MySQL performance comparison 2026 (query optimization, indexing strategies, concurrent writes, JSON handling, scaling patterns). Provide benchmark data and use case recommendations." |
| "How to handle errors in Go?" | "Go error handling patterns 2026 (error wrapping, custom errors, sentinel errors, panic vs error, testing error cases). Provide code examples and best practices comparison." |
| "Learn FastAPI basics" | "FastAPI tutorial 2026 (routing, dependency injection, async endpoints, request validation with Pydantic, OpenAPI documentation, testing). Include step-by-step implementation guide." |
Note: If user provides an already detailed query with version numbers and requirements, use it as-is.
Workflow
- Receive user request
- Optimize query using template above
- Inform user: "Searching for: '[optimized query]'"
- Execute search with
--save --debug flags
- Return results with inline citations [1][2][3]
Script Execution
CRITICAL: Always use the run.py wrapper. Direct script execution will fail.
Basic Search
python scripts/run.py search.py --query "Your search query"
Recommended Usage
python scripts/run.py search.py --query "..." --save --debug
The run.py wrapper automatically:
- Creates
.venv on first run
- Installs dependencies (patchright, beautifulsoup4, html-to-markdown)
- Activates virtual environment
- Executes search script
- Installs Google Chrome (not Chromium) for anti-detection
How It Works
- Persistent Browser Context: Uses saved browser profile at
~/.cache/google-ai-mode-skill/chrome_profile to preserve cookies/session between searches
- Eliminates CAPTCHAs: Persistent context means Google recognizes the browser → rarely triggers CAPTCHA
- AI Content Detection: Waits for Google AI Overview to appear on page
- Citation Extraction: Injects JavaScript to extract source links from AI response
- Markdown Conversion: Converts HTML to markdown with inline citations [1][2][3]
- Fast Results: Typical search completes in 5-7 seconds (no CAPTCHA)
CAPTCHA Handling
With persistent context, CAPTCHAs are rare. If encountered:
- Detection: Multi-layer check (URL
/sorry/index, page text, content length)
- Automatic Handling: If CAPTCHA detected in headless mode → script returns
CAPTCHA_REQUIRED error
- Manual Solution: Re-run with
--show-browser flag, solve CAPTCHA in browser, script continues automatically
Note: After CAPTCHA is solved once, persistent context preserves the session → future searches won't require CAPTCHA.
Output Format
Returns markdown with inline citations and source list. Example:
React 18 introduces concurrent features including Suspense for data fetching[1],
automatic batching for state updates[2], and transitions for non-urgent updates[3].
---
## Sources:
[1] React 18 Release Notes
https://react.dev/blog/2022/03/29/react-v18
[2] Automatic Batching Explained
https://github.com/reactwg/react-18/discussions/21
[3] Transitions API Documentation
https://react.dev/reference/react/useTransition
Common Use Cases
Finding Library Documentation
python scripts/run.py search.py --query "Prisma ORM 2026 (schema definition, migrations, client API, relation queries, transactions). Include TypeScript examples." --save --debug
Getting Coding Examples
python scripts/run.py search.py --query "WebSocket implementation Node.js 2026 (server setup, client connection, message handling, authentication, reconnection logic). Production-ready code examples." --save
Technical Comparisons
python scripts/run.py search.py --query "GraphQL vs REST API 2026 (performance, caching, tooling, type safety, learning curve). Comparison table with use case recommendations." --save
Best Practices Research
python scripts/run.py search.py --query "Microservices security patterns 2026 (API gateway authentication, service mesh, mutual TLS, secret management, observability). Architecture diagrams and implementation guide." --save --debug
Troubleshooting
| Issue | Solution |
|---|
ModuleNotFoundError | Use run.py wrapper, never execute scripts directly |
| CAPTCHA every time | First-time setup: solve CAPTCHA once with --show-browser, then persistent context preserves session |
| No AI overview found | Rephrase query with more specificity using optimization template |
| Browser fails to start | Verify internet connection and Chrome installation |
| Need detailed logs | Use --debug flag - log saved to logs/ folder |
| AI Mode not available | Your region/country doesn't support Google AI Mode. Use a proxy/VPN to access from supported regions (US, UK, Germany, etc.) |
Exit Codes:
0 - Success1 - General error2 - CAPTCHA required (retry with --show-browser)3 - Browser closed by user4 - AI Mode not available in region (use proxy/VPN)130 - User interrupted (Ctrl+C)
Best Practices
- Always optimize queries - Specificity determines result quality
- Use
--save --debug for important searches - Preserves results and provides audit trail
- Include version numbers for library/framework queries
- Request structured output - Tables and comparisons improve usability
- Solve CAPTCHA once - Persistent context eliminates future CAPTCHAs
- Verify citations - Check provided sources for accuracy