# Brainstorming: Advanced Web Search Skill

## Objective
Create a versatile web search skill that supports multiple search modes, providers, and use cases.

## Potential Search Modes

### 1. General Search
- **Goal**: Find general information, answers to questions.
- **Tools**: `claude -p` (existing), `googler`, `ddgr`.
- **Features**: Summaries, top N results.

### 2. Documentation Search
- **Goal**: Find specific technical documentation.
- **Target**: MDN, Python Docs, Rust Docs, NixOS Wiki.
- **Strategy**: Restrict search to specific domains (`site:docs.python.org`).

### 3. Code Search
- **Goal**: Find code snippets, libraries, or usage examples.
- **Target**: GitHub, GitLab, StackOverflow.
- **Tools**: GitHub CLI (`gh`), specialized code search APIs.

### 4. Package Search
- **Goal**: Find packages and versions.
- **Target**: NixOS Packages, PyPI, NPM, Crates.io.
- **Tools**: `nix-search` (if available), `pip search` (deprecated, need alternative), `npm search`.

### 5. Deep Research / Investigation
- **Goal**: Thoroughly investigate a topic by following links.
- **Strategy**: Recursive search or multi-step agentic workflow (search -> read -> search).

## Implementation Options

### Option A: Enhanced `claude -p` Wrapper
- Expand the existing `web-search` skill.
- Add flags: `--docs`, `--code`, `--package`.
- Modify the prompt sent to Claude to guide its search behavior.
- **Pros**: Uses existing powerful agent.
- **Cons**: Dependent on Claude's tools and context window.

### Option B: Direct CLI Tools
- Use tools like `googler` or `ddgr` directly for faster, raw results.
- **Pros**: Fast, lightweight, structured output (JSON).
- **Cons**: Requires installing extra tools, raw output might need parsing.

### Option C: Hybrid Approach
- Use CLI tools for discovery (getting URLs).
- Use `claude` or `curl` + `readability` for content extraction.

## Questions for User
- Do you prefer a single "smart" skill that figures out what to do, or explicit flags/subcommands?
- Are there specific sources you search often (e.g., NixOS packages)?
- Do you want raw links or summarized answers?

## Resolution (2025-12-28)

**Context changed**: Claude Code now has built-in WebSearch and WebFetch tools.

**Decisions:**

1. **Single smart skill vs flags?** Keep two separate skills:
   - web-search: Quick searches (for OpenCode which lacks built-in search)
   - web-research: Deep research with structured reports (valuable for both)

2. **Specific sources priority?** Not needed as skill feature.
   - WebSearch has `allowed_domains` parameter
   - User says "search nixos wiki for X" and agent uses domain filtering

3. **Raw links vs summaries?** Summaries by default (current behavior).
   - Raw links without context are less useful
   - Agent synthesizes information

**Deployment:**
- web-search: OpenCode only (Claude Code has native WebSearch)
- web-research: Both (deep research with backends beyond built-in capability)

**Status:** Questions resolved, no changes needed to skills.