agent-team/skills/web-search/examples/basic-search.md

Web Search Skill - Basic Usage Examples

This document provides practical examples of using the Web Search skill.

Quick Start

1. Start the Bridge Server

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

Expected output:

✓ Bridge Server started successfully (PID: 12345)
  Health check: http://127.0.0.1:8923/api/health
  Logs: SKILLs/web-search/.server.log

2. Perform a Simple Search

bash SKILLs/web-search/scripts/search.sh "TypeScript tutorial" 5

Expected output:

🔍 Searching for: "TypeScript tutorial"

✓ Found 5 results in 834ms

# Search Results: TypeScript tutorial

**Query:** TypeScript tutorial
**Results:** 5
**Time:** 834ms

---

## TypeScript Tutorial - W3Schools
...

3. Stop the Server

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

Common Use Cases

Example 1: Research Latest Information

Scenario: Find the latest React 19 features

bash SKILLs/web-search/scripts/search.sh "React 19 new features" 10

Use Case: When you need up-to-date information beyond Claude's knowledge cutoff.

Example 2: Technical Documentation

Scenario: Search for Next.js App Router documentation

bash SKILLs/web-search/scripts/search.sh "Next.js App Router documentation" 5

Use Case: Find official documentation for specific frameworks or libraries.

Example 3: News and Current Events

Scenario: Find recent AI news

bash SKILLs/web-search/scripts/search.sh "AI news 2026" 10

Use Case: Get real-time information about current events.

Example 4: Troubleshooting Errors

Scenario: Search for error solutions

bash SKILLs/web-search/scripts/search.sh "TypeError: Cannot read property of undefined" 5

Use Case: Find solutions to specific error messages.

Example 5: Comparative Research

Scenario: Compare technologies

bash SKILLs/web-search/scripts/search.sh "Vue vs React 2026 comparison" 8

Use Case: Gather information for comparative analysis.

Advanced API Usage

Direct API Calls (for advanced users)

Health Check

curl http://127.0.0.1:8923/api/health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 123.45,
    "connections": 1
  }
}

Launch Browser

curl -X POST http://127.0.0.1:8923/api/browser/launch \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "data": {
    "pid": 12345,
    "cdpPort": 9222,
    "startTime": 1707363600000
  }
}

Connect to Browser

curl -X POST http://127.0.0.1:8923/api/browser/connect \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "success": true,
  "data": {
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec",
    "cdpPort": 9222
  }
}

Perform Search

curl -X POST http://127.0.0.1:8923/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec",
    "query": "TypeScript tutorial",
    "maxResults": 5
  }'

Response:

{
  "success": true,
  "data": {
    "query": "TypeScript tutorial",
    "results": [
      {
        "title": "TypeScript Tutorial - W3Schools",
        "url": "https://www.w3schools.com/typescript/",
        "snippet": "Learn TypeScript with examples...",
        "source": "bing",
        "position": 1
      }
    ],
    "totalResults": 5,
    "timestamp": 1707363600000,
    "duration": 834
  }
}

Take Screenshot

curl -X POST http://127.0.0.1:8923/api/page/screenshot \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec",
    "format": "png",
    "fullPage": false
  }'

Response:

{
  "success": true,
  "data": {
    "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",
    "format": "png",
    "size": 387122
  }
}

Navigate to URL

curl -X POST http://127.0.0.1:8923/api/page/navigate \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec",
    "url": "https://example.com",
    "waitUntil": "domcontentloaded",
    "timeout": 15000
  }'

Get Page Text

curl -X POST http://127.0.0.1:8923/api/page/text \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec"
  }'

Disconnect

curl -X POST http://127.0.0.1:8923/api/browser/disconnect \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "e2421754-0091-450d-a54c-7bc58498bfec"
  }'

Workflow Example: Complete Research Session

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

# 2. Search for topic
bash SKILLs/web-search/scripts/search.sh "React Server Components" 5

# 3. Search for related topic
bash SKILLs/web-search/scripts/search.sh "Next.js 14 features" 5

# 4. Search for comparisons
bash SKILLs/web-search/scripts/search.sh "RSC vs traditional React" 3

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

Integration with Cowork Sessions

When using this skill in Cowork sessions, Claude will automatically:

1. Check if the Bridge Server is running
2. Start the server if needed (via Electron service manager)
3. Execute searches using the simplified CLI
4. Parse and analyze results
5. Provide answers based on real-time information

Example Cowork interaction:

User: What are the new features in React 19?

Claude: Let me search for the latest information about React 19.
        [Calls: bash SKILLs/web-search/scripts/search.sh "React 19 new features" 5]

        Based on the search results, React 19 introduces several key features:
        1. React Compiler - automatic optimization
        2. Actions - simplified form handling
        3. Document metadata - built-in SEO support
        ...

Troubleshooting

Server Won't Start

Problem: Bridge Server fails to start

Solution:

# Check if port 8923 is already in use
lsof -i :8923

# Check logs
cat SKILLs/web-search/.server.log

# Reinstall dependencies
cd SKILLs/web-search
npm install
npm run build

Chrome Not Found

Problem: Browser fails to launch

Solution:

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

Connection Failed

Problem: Failed to connect to browser

Solution:

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

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

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

Search Timeout

Problem: Search takes too long or times out

Solution:

• Check your internet connection
• Try a different search query
• Reduce max results (e.g., 3 instead of 10)
• Restart the browser

Best Practices

1. Start server once - Keep server running during research sessions
2. Use specific queries - Better results with focused search terms
3. Limit results - Request only what you need (5-10 results)
4. Clean up - Stop server when done to free resources
5. Check logs - Review .server.log if issues occur

Performance Tips

• Connection caching - Reuses browser connections for faster searches
• Background server - Server runs independently, no startup delay
• Concurrent searches - Multiple searches can run simultaneously
• Resource cleanup - Automatic cleanup on shutdown

Security Notes

• Server only listens on 127.0.0.1 (localhost)
• No external network exposure
• Isolated browser profile (separate from your main Chrome)
• All operations visible in the browser window
• No credential storage or sensitive operations