nimble-web-expert

What this skill does

# Nimble Web Expert

Web extraction, search, and URL discovery using the Nimble CLI. Returns clean structured data from any website.

User request: $ARGUMENTS

## Core principles

- **Route by intent first.** Named site/domain → check for pre-built agent first (announce it out loud). Direct URL → `nimble extract`. Research/topic → `nimble search`. Discover/crawl URLs → `nimble map` or `nimble crawl`.
- **One command → present results → done.** Run once with `--transform "data.parsing"` for agents. Show the data immediately as a table. Do NOT experiment, loop, or write Python to parse output.
- **Multiple inputs → always parallel.** 2+ URLs/keywords/ASINs → `&`+`wait`. 6–20 → `xargs -P`. 20+ → Python asyncio script. See `references/batch-patterns.md`.
- **Escalate render tiers silently.** Tier 1 → 2 → 3 → … without asking. Surface a decision only when all tiers fail and investigation tools are needed.
- **Never answer from training data.** Live prices, current news, today's listings → always fetch via Nimble. If unavailable, say so.
- **AskUserQuestion at every meaningful choice.** Header ≤12 chars, 2–4 options, label 1–5 words, recommended option first. Never present choices as numbered prose.
- **Save all outputs to `.nimble/`.** Never leave extraction results in memory only.
- **Verify the connection BEFORE working — don't fire a data call and react to the error.** With bash, `nimble --version` + `NIMBLE_API_KEY` confirms the CLI path; otherwise run one read-only `mcp__plugin_nimble_nimble__nimble_agents_list` probe. Success = connected; an auth/not-connected error or a response containing an OAuth authorization URL = not connected.
- **No working CLI and no connected MCP → stop.** Do not fall back to WebFetch, WebSearch, curl, or `dangerouslyDisableSandbox`. If the plugin is installed but the connector isn't connected (typical Cowork / claude.ai), surface the verbatim connect steps from `rules/setup.md` and stop; if no plugin at all, follow the install flow in `rules/setup.md`.
- **If a tool hands back an OAuth "Authorize" link instead of data, present it exactly as given and stop.** Never invent a "paste the URL back" / "I'll complete the connection" step — none exists — and never claim tools "will activate" then call them in the same turn. Wait for the user to authorize, then retry or re-probe.

## Skill ecosystem

| Skill                              | Best for                                                                   | Key commands                                     |
| ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------ |
| **nimble-web-expert** (this skill) | Real-time data — fetch any URL, search, map, crawl, run existing agents    | `extract`, `search`, `map`, `crawl`, `agent run` |
| **nimble-agent-builder**           | Build reusable agents — create, refine, publish named extraction templates | CLI: `generate`, `get-generation`, `publish`     |

**Hand off to nimble-agent-builder only when all of these are true:** the user has signalled a recurring/scheduled need, the pattern is repetitive (same site, same fields), and they've seen and approved the results. Don't ask after every extract — only when language clearly signals a recurring workflow ("I want to do this every day", "build me a pipeline", "make this reusable").

**For agent refinement:** _"Agent updates are handled by nimble-agent-builder — it can refine the existing agent without rebuilding from scratch."_

## Interactive UX

- Use `AskUserQuestion` at every meaningful choice — never guess, never ask in prose.
- **Ambiguous request** (no URL, vague topic): ask before running — "What would you like to do?" → Search / Fetch URL / Discover URLs / Call API
- **Before running a search** (if task maps to a specific focus mode): offer focus mode — General / News / Coding / Shopping / Academic / Social
- **After all tiers fail**: check investigation tools (`which browser-use`, `python3 -c "from playwright.sync_api..."`) and ask whether to investigate with browser-use, Playwright, or skip.
- After presenting results, always close with: "Were these results what you needed?" → `Looks great!` / `Mostly good` / `Not quite` / `Skip feedback`

## Prerequisites

Pick CLI or MCP at session start — same skill, two transports. Once a transport is selected, stick with it for the session and don't re-probe on every command.

```bash
nimble --version && echo "${NIMBLE_API_KEY:+API key: set}"        # CLI path
# OR (fallback when shell isn't available)
claude mcp list 2>/dev/null | grep -q "nimble" && echo "MCP: ok"  # plugin MCP
```

- **CLI ready** (version + API key both print) → proceed to [Step 0](#analyze--route), use `nimble ...` commands.
- **MCP connected** (no CLI, but plugin is installed) → proceed to [Step 0](#analyze--route), use `mcp__plugin_nimble_nimble__*` tools instead.
- **Neither** → load `rules/setup.md` for the environment-aware install flow. Any Claude product (Code, Cowork, claude.ai) → `/plugin install nimble`. Codex or other terminal-only agents → `npm i -g @nimble-way/nimble-cli`. Cursor / VS Code / generic MCP clients → paste the `mcp.json` snippet.

**If bash is denied:** you're in a Cowork-like / MCP-only host. Use `mcp__plugin_nimble_nimble__*` tools, but verify the connection first with one read-only `nimble_agents_list` probe. If the probe fails with an auth/not-connected error or returns an OAuth authorization URL, the connector isn't connected — surface the connection steps from [Core principles](#core-principles) and stop (and never invent an auth-completion flow). **Never substitute WebFetch, WebSearch, curl, or any other tool for Nimble operations.**

---

## Analyze & Route

| User signal                        | Command                                       | Notes                                          |
| ---------------------------------- | --------------------------------------------- | ---------------------------------------------- |
| Names a specific site or domain    | `nimble agent` → `nimble extract` if no agent | Always check for agent first — announce it     |
| Provides a direct URL              | `nimble extract`                              | Skip agent check                               |
| Research, topic, or vertical query | `nimble search`                               | Use focus modes for news, jobs, shopping, etc. |
| "Find URLs / sitemap / all pages"  | `nimble map`                                  | Returns URL list + metadata                    |
| "Crawl / archive a whole section"  | `nimble crawl`                                | Async bulk extraction                          |

### Step 0 — Agent check (when a domain is named)

Pre-built agents return clean structured data with zero selector work. Always check first.

**Always verbalize — never silently:**

1. **Announce:** _"Let me check if there's a pre-built Nimble agent for [site]..."_
2. **Report:** _"Found `<agent_name>` — using it now."_ or _"No pre-built agent — falling back to extraction."_

**Lookup order:**

1. `~/.claude/skills/nimble-web-expert/learned/examples.json` → `agents[]` array
2. `references/nimble-agents/SKILL.md` → baked-in table (50+ sites)
3. `nimble agent list --limit 100 --search "<domain or vertical>"` → show table, confirm with user
4. No match → proceed to extract/search

**Run with `--transform "data.parsing"` — always:**

```bash
nimble --transform "data.parsing" agent run --agent <name> --params '{"keyword": "..."}'
```

Do NOT run without `--transform "data.parsing"` and then parse raw output. The raw response contains `html` (useless), `headers`, and `parsing` (what you want). The transform flag extracts `parsing` in one shot.

For the full agent list (50+ sites), see `references/nimble-agents/SKILL.md`.

⚠️ `google_search` is for SEO/SERP rank analysis only — not general information retrieval. For finding information, use `