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
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:

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

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

**Examples:**

```bash
# 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:

```markdown
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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
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

```bash
# 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

```bash
# User reports an error
bash SKILLs/web-search/scripts/search.sh