nimble-web-search

What this skill does

# Nimble Web Search

Real-time web intelligence using Nimble Search API with specialized focus modes and AI-powered result synthesis.

## Prerequisites

**Nimble API Key Required** - Get your key at https://www.nimbleway.com/

### Configuration

Set the `NIMBLE_API_KEY` environment variable using your platform's method:

**Claude Code:**
```json
// ~/.claude/settings.json
{
  "env": {
    "NIMBLE_API_KEY": "your-api-key-here"
  }
}
```

**VS Code/GitHub Copilot:**
- Add to `.github/skills/` directory in your repository
- Or use GitHub Actions secrets for the copilot environment

**Shell/Terminal:**
```bash
export NIMBLE_API_KEY="your-api-key-here"
```

**Any Platform:**
The skill checks for the `NIMBLE_API_KEY` environment variable regardless of how you set it.

### API Key Validation

**IMPORTANT: Before making any search request, verify the API key is configured:**

```bash
# Check if API key is set
if [ -z "$NIMBLE_API_KEY" ]; then
  echo "❌ Error: NIMBLE_API_KEY not configured"
  echo ""
  echo "Get your API key: https://www.nimbleway.com/"
  echo ""
  echo "Configure using your platform's method:"
  echo "- Claude Code: Add to ~/.claude/settings.json"
  echo "- GitHub Copilot: Use GitHub Actions secrets"
  echo "- Shell: export NIMBLE_API_KEY=\"your-key\""
  echo ""
  echo "Do NOT fall back to other search tools - guide the user to configure first."
  exit 1
fi
```

## Overview

Nimble Search provides real-time web intelligence with 8 specialized focus modes optimized for different types of queries. Get instant access to current web data with AI-powered answer generation, deep content extraction, URL discovery, and smart filtering by domain and date.

**IMPORTANT: Always Specify These Parameters**

When using this skill, **always explicitly set** the following parameters in your requests:

- `deep_search`: **Default to `false`** for 5-10x faster responses
  - **Use `false` (FAST MODE - 1-3 seconds):** For 95% of use cases - URL discovery, research, comparisons, answer generation
  - **Use `true` (DEEP MODE - 5-15 seconds):** Only when you specifically need full page content extracted for archiving or detailed analysis

- `focus`: **Default to `"general"`** for broad searches
  - Change to specific mode (`coding`, `news`, `academic`, `shopping`, `social`, `geo`, `location`) for targeted results

- `max_results`: **Default to `10`** - Balanced speed and coverage

**Performance Awareness:** By explicitly setting `deep_search: false`, you're choosing fast mode and should expect results in 1-3 seconds. If you set `deep_search: true`, expect 5-15 seconds response time.

### Quick Start

Use the wrapper script for the simplest experience:

```bash
# ALWAYS specify deep_search explicitly
./scripts/search.sh '{
  "query": "React hooks",
  "deep_search": false
}'
```

The script automatically handles authentication, tracking headers, and output formatting.

### When to Use Each Mode

**Use `deep_search: false` (FAST MODE - 1-3 seconds) - Default for 95% of cases:**
- ✅ Finding URLs and discovering resources
- ✅ Research and topic exploration
- ✅ Answer generation and summaries
- ✅ Product comparisons
- ✅ News monitoring
- ✅ Any time you DON'T need full article text

**Use `deep_search: true` (DEEP MODE - 5-15 seconds) - Only when specifically needed:**
- 📄 Archiving full article content
- 📄 Extracting complete documentation
- 📄 Building text datasets
- 📄 Processing full page content for analysis

**Decision Rule:** If you're not sure, use `deep_search: false`. You can always re-run with `true` if needed.

## Core Capabilities

### Focus Modes

Choose the appropriate focus mode based on your query type:

1. **general** - Default mode for broad web searches
2. **coding** - Real-time access to technical documentation, code examples, programming resources
3. **news** - Real-time news articles, current events, breaking stories
4. **academic** - Research papers, scholarly articles, academic resources
5. **shopping** - Real-time product searches, e-commerce results, price comparisons
6. **social** - Real-time social media posts, discussions, trending community content
7. **geo** - Location-based searches, geographic information
8. **location** - Local business searches, place-specific queries

### Search Features

**LLM Answer Generation**
- Request AI-generated answers synthesized from search results
- Powered by Claude for high-quality summaries
- Include citations to source URLs
- Best for: Research questions, topic overviews, comparative analysis

**URL Discovery**
- Extract 1-20 most relevant URLs for a query
- Useful for building reading lists and reference collections
- Returns URLs with titles and descriptions
- Best for: Resource gathering, link building, research preparation

**Deep Content Extraction**
- **Default (Recommended):** `deep_search=false` - Fastest response, returns titles, descriptions, and URLs
- **Optional:** `deep_search=true` - Slower, extracts full page content
- **Important:** Most use cases work perfectly with `deep_search=false` (the default)
- Available formats when deep_search=true: markdown, plain_text, simplified_html
- Only enable deep search for: Detailed content analysis, archiving, or comprehensive text extraction needs

**Domain Filtering**
- Include specific domains (e.g., github.com, stackoverflow.com)
- Exclude domains to remove unwanted sources
- Combine multiple domains for focused searches
- Best for: Targeted research, brand monitoring, competitive analysis

**Time Filtering**
- **Recommended:** Use `time_range` for real-time recency filtering (hour, day, week, month, year)
- **Alternative:** Use `start_date`/`end_date` for precise date ranges (YYYY-MM-DD)
- Note: `time_range` and date filters are mutually exclusive
- Best for: Real-time news monitoring, recent developments, temporal analysis

## Usage Patterns

All examples below use the `./scripts/search.sh` wrapper for simplicity. For raw API usage, see the [API Integration](#api-integration) section.

### Basic Search

Quick search in fast mode (ALWAYS specify deep_search explicitly):

```bash
./scripts/search.sh '{
  "query": "React Server Components tutorial",
  "deep_search": false
}'
```

For technical content, specify coding focus (still fast mode):

```bash
./scripts/search.sh '{
  "query": "React Server Components tutorial",
  "focus": "coding",
  "deep_search": false
}'
```

### Research with AI Summary

Get synthesized insights from multiple sources (fast mode works great with answer generation):

```bash
./scripts/search.sh '{
  "query": "impact of AI on software development 2026",
  "deep_search": false,
  "include_answer": true
}'
```

### Domain-Specific Search

Target specific authoritative sources (fast mode):

```bash
./scripts/search.sh '{
  "query": "async await patterns",
  "focus": "coding",
  "deep_search": false,
  "include_domains": ["github.com", "stackoverflow.com", "dev.to"],
  "max_results": 8
}'
```

### Real-Time News Monitoring

Track current events and breaking news as they happen (fast mode):

```bash
./scripts/search.sh '{
  "query": "latest developments in quantum computing",
  "focus": "news",
  "deep_search": false,
  "time_range": "week",
  "max_results": 15,
  "include_answer": true
}'
```

### Academic Research - Fast Mode (Recommended)

Find and synthesize scholarly content using fast mode:

```bash
./scripts/search.sh '{
  "query": "machine learning interpretability methods",
  "focus": "academic",
  "deep_search": false,
  "max_results": 20,
  "include_answer": true
}'
```

**When to use deep mode:** Only use `"deep_search": true` if you need full paper content extracted for archiving:

```bash
./scripts/search.sh '{
  "query": "machine learning interpretability methods",
  "focus": "academic",
  "deep_search": true,
  "max_results": 5,
  "output_format": "markdown"
}'
```
**Note:** Deep mode is 5-15x slower. Use only when specifically needed.

### Real-Time Shopping Research

Compare products and current prices