Web Search

Web Search Skill

When to Use This Skill

Use the web-search skill when you need:

• Current information - Events, news, or data after January 2025
• Latest documentation - Up-to-date framework/library docs (React 19, Next.js 15, etc.)
• Real-time data - Stock prices, weather, sports scores, etc.
• Fact verification - Check current status of projects, companies, or technologies
• Recent discussions - Community opinions, GitHub issues, Stack Overflow answers
• Product comparisons - Latest reviews and comparisons
• Troubleshooting - Search for specific error messages or solutions

Examples of when to use:

• User: "What are the new features in React 19?"
• User: "Search for the latest Next.js App Router documentation"
• User: "What's the current status of the Rust async project?"
• User: "Find recent discussions about Vue 3 performance"

How It Works

┌──────────┐    Bash    ┌─────────┐    HTTP    ┌──────────────┐    CDP    ┌────────┐
│  Claude  │───────────▶│ CLI.sh  │───────────▶│ Bridge Server│──────────▶│ Chrome │
│          │            │         │            │ (localhost)  │ Playwright│        │
└──────────┘            └─────────┘            └──────────────┘            └────────┘
                                                      │
                                                  ▼
                                             Google/Bing Search
                                                Extract Results

Architecture:

1. CLI Script - Simple bash interface for Claude
2. Bridge Server - Express HTTP API (auto-started by Electron)
3. Playwright Manager - Browser connection and session management
4. Search Engine Layer - Google primary, Bing fallback
5. Chrome Browser - Visible browser window (all operations transparent)

Basic Usage

Simple Search (Recommended)

IMPORTANT: Always use the $SKILLS_ROOT environment variable to locate the skill scripts. This ensures the skill works in both development and production environments.

bash "$SKILLS_ROOT/web-search/scripts/search.sh" "search query" [max_results]

For non-ASCII queries (Chinese/Japanese/etc.), prefer UTF-8 file input to avoid shell encoding issues on Windows:

cat > /tmp/web-query.txt <<'TXT'
苹果 Siri AI 2026 发布计划
TXT

bash "$SKILLS_ROOT/web-search/scripts/search.sh" @/tmp/web-query.txt 10

Examples:

# Search with default 10 results
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "TypeScript 5.0 new features"

# Limit to 5 results
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "React Server Components guide" 5

# Search for recent news
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "AI news January 2026" 10

Output Format:

The script returns Markdown-formatted results:

# Search Results: TypeScript 5.0 new features

**Query:** TypeScript 5.0 new features
**Results:** 5
**Time:** 834ms

---

## TypeScript 5.0 Release Notes

**URL:** [https://www.typescriptlang.org/docs/...]

TypeScript 5.0 introduces decorators, const type parameters...

---

## (More results...)

Workflow Example

# 1. Search for topic
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Next.js 14 features" 5

# 2. Analyze results and answer user

# 3. Follow-up search if needed
bash "$SKILLS_ROOT/web-search/scripts/search.sh" "Next.js Server Actions tutorial" 3

Advanced Usage

Server Management

The Bridge Server is automatically managed by Electron. You typically don't need to start/stop it manually.

However, for manual control:

# Start server (if not already running)
bash "$SKILLS_ROOT/web-search/scripts/start-server.sh"

# Stop server
bash "$SKILLS_ROOT/web-search/scripts/stop-server.sh"

# Check health (start script will print endpoint status)
bash "$SKILLS_ROOT/web-search/scripts/start-server.sh"

Direct API Calls

For advanced use cases, you can call the HTTP API directly:

# Get or create connection
CONNECTION_ID=$(curl -s -X POST http://127.0.0.1:8923/api/browser/connect \
  -H "Content-Type: application/json" \
  -d '{}' | grep -o '"connectionId":"[^"]*"' | cut -d'"' -f4)

# Perform search
curl -X POST http://127.0.0.1:8923/api/search \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"query\": \"Playwright tutorial\",
    \"maxResults\": 5
  }"

# Navigate to specific URL
curl -X POST http://127.0.0.1:8923/api/page/navigate \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"url\": \"https://example.com\"
  }"

# Take screenshot
curl -X POST http://127.0.0.1:8923/api/page/screenshot \
  -H "Content-Type: application/json" \
  -d "{
    \"connectionId\": \"$CONNECTION_ID\",
    \"format\": \"png\"
  }"

Best Practices

1. Use Specific Queries

❌ Bad: bash scripts/search.sh "react" ✅ Good: bash scripts/search.sh "React 19 new features and breaking changes"

2. Limit Results Appropriately

• Quick lookup: 3-5 results
• Comprehensive research: 10 results
• Don't request more than needed (faster + less noise)

3. Check Server Status First

If search fails, verify the server is running:

bash "$SKILLS_ROOT/web-search/scripts/start-server.sh" || echo "Server not running"

4. Reuse Connections

The CLI script automatically caches connections. Multiple searches in the same session will reuse the same browser connection for better performance.

5. Clean Output

Parse the Markdown output to extract key information for the user. Don't just dump all results - synthesize and summarize.

Common Patterns

Pattern 1: Latest Documentation

# User asks about latest framework features
bash SKILLs/web-search/scripts/search.sh "Next.js 15 documentation" 5

# Parse results, find official docs, summarize features

Pattern 2: Troubleshooting

# User reports an error
bash SKILLs/web-search/scripts/search.sh "TypeError: Cannot read property of undefined React" 5

# Find Stack Overflow answers and GitHub issues, provide solution

Pattern 3: Current Events

# User asks about recent news
bash SKILLs/web-search/scripts/search.sh "AI developments January 2026" 10

# Summarize key news items from results

Pattern 4: Comparison Research

# User wants to compare technologies
bash SKILLs/web-search/scripts/search.sh "Vue 3 vs React 18 performance 2026" 5

# Synthesize comparison from multiple sources

Pattern 5: API/Library Usage

# User needs specific API documentation
bash SKILLs/web-search/scripts/search.sh "Playwright page.evaluate examples" 5

# Extract code examples and usage patterns

Error Handling

Server Not Running

Error: ✗ Bridge Server is not running

Solution:

• The server should auto-start with Electron
• If manual start needed: bash SKILLs/web-search/scripts/start-server.sh
• Check logs: cat SKILLs/web-search/.server.log

Browser Launch Failed

Error: Failed to launch browser

Cause: Chrome not installed or not found

Solution:

• macOS: Install from https://www.google.com/chrome/
• Linux: sudo apt install chromium-browser
• Windows: Install from https://www.google.com/chrome/

Connection Timeout

Error: CDP port not ready or Connection timeout

Solution:

# Stop server
bash SKILLs/web-search/scripts/stop-server.sh

# Clear cache
rm SKILLs/web-search/.connection

# Restart
bash SKILLs/web-search/scripts/start-server.sh

No Search Results

Error: Found 0 results

Possible causes:

• Query too specific or unusual
• Bing changed page structure (rare)
• Network issues

Solution:

• Try broader query
• Check internet connection
• Verify page loads manually at bing.com

Search Timeout

Error: Search failed: timeout

Solution:

• Check internet connection
• Reduce max results
• Try again (might be temporary network issue)

Understanding Results

Result Structure

Each search result contains:

## [Title of Result]

**URL:** [https://example.com/page]

[Snippet/description from search results]

Fields:

• Title - Page/article title
• URL - Direct link (may include Bing tracking)
• Snippet - Preview text from the page

Parsing Results

The search output is Markdown. Extract:

1. Total results count
2. Search duration
3. Individual result titles and URLs
4. Snippets for context

Result Quality

• Official docs - Usually appear in top 3 results
• Stack Overflow - Appears for technical questions
• Recent articles - Bing prioritizes recent content
• Chinese content - Bing works well in China, includes Chinese sources

Performance Considerations

Typical Latencies

• Server startup: ~2 seconds (one-time, auto-started)
• Browser launch: ~3 seconds (one-time, persists across searches)
• First search: ~2-3 seconds (includes browser connection setup)
• Subsequent searches: ~1 second (browser and connection reused)

Optimization Tips

1. Browser persistence - The browser stays alive across searches by default. Connections and pages are reused automatically. Set WEB_SEARCH_CLEANUP=1 to close the browser after each search if needed.
2. Limit results - Request only what you need (5-10 is usually enough)
3. Batch searches - If multiple searches needed, do them consecutively to reuse connection
4. Specific queries - More specific = faster and better results

Security and Privacy

Security Measures

• Localhost only - Bridge Server binds to 127.0.0.1 (no external access)
• No network exposure - Not accessible from other machines
• Isolated browser - Uses separate Chrome profile, won't affect user's main browser
• Visible operations - All browser actions shown in visible window (transparent)
• No credentials - Skill never handles passwords or sensitive data

Privacy Considerations

• Search queries go through Google and/or Bing depending on availability
• Google/Bing may track searches (their standard privacy policies apply)
• No local storage of search history by the skill
• User can observe all browser activity in real-time