nimbleway/agent-skills/nimble-web-expert

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 (see Analyze & Route for the full decision model). Named site with a matching Extraction Template + a direct item to look up → run the template. Site with no template, or a need that requires discovery/reasoning across pages → a Web Search Agent. One-off single URL → nimble extract. Raw results to work from ("find pages/articles about…") → nimble search; a synthesized deliverable (report, brief, comparison, recommendation) → a Web Search Agent. Discover/crawl URLs → nimble map or nimble crawl.
• Web Search Agent runs: pick a run mode before building the command. Default to named create-or-reuse — nimble agents run --agent-name <stable-name> — so a repeat session lands on the same agent. agents:runs create is the explicit-agent-ID route only and requires --agent-id. references/nimble-agents/reference.md has the mode table, use_case locking, and the one-time skill override.
• One command → present results → done. Run once, 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 on empty or truncated content. Tier 1 → 2 → 3 → … without asking. Surface a decision only when all tiers fail and investigation tools are needed. An access barrier is a different outcome, not a tier to climb — see Guardrails.
• 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.

Capabilities

One skill, one taxonomy. Use Nimble's own product names precisely — never paraphrase them.

Extraction Templates and Web Search Agents are distinct — an Extraction Template is a fixed, site-specific parser; a Web Search Agent reasons across sources. Never call an Extraction Template a "WSA" or a "legacy WSA," and never route a template use to agents (or vice-versa) by name alone. Building new templates/agents is out of scope here — use existing ones (point users to the Nimble app to build new).

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?" → Research & report / Search / Fetch URL / Discover URLs
• Gate B landed on a Web Search Agent at `high`+ effort: offer the cost/latency fork — Researched report / Quick scan (see Analyze & Route)
• 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.

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, use nimble ... commands.
• MCP connected (no CLI, but plugin is installed) → proceed to Step 0, 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 and stop (and never invent an auth-completion flow). Never substitute WebFetch, WebSearch, curl, or any other tool for Nimble operations.

Analyze & Route

Two gates, in order. Gate A asks where the data lives; Gate B asks what the user wants back. Most mis-routes come from skipping Gate B — a request with no location signal is not automatically a search.

Gate A — do I know where the data lives?

The most common overlap — a site with no Extraction Template. It looks like a choice between a raw extract (which dumps parsing work on the user) or building a template (out of scope). Neither is right: fall through to Gate B, which will land on a Web Search Agent — it configures fresh for any site and reasons about structure without a maintained template. This isn't a question to put to the user; when no template fits, the answer is the same every time.

Step 0 — Extraction Template check (when a site + direct item is named)

Templates return clean structured data with zero selector work. Always check first.

Always verbalize — never silently:

1. Announce: _"Let me check if there's a Nimble Extraction Template for [site]..."_
2. Report: _"Found <template_name> — using it now."_ or _"No template for [site] — using a Web Search Agent instead."_

Lookup order:

1. ~/.claude/skills/nimble-web-expert/learned/examples.json → learned templates
2. nimble extract:templates list --limit 100 → filter by site/domain client-side; confirm the match
3. Inspect the schema before running: nimble extract:templates get --extract-template-name <name>
4. No match → route to a Web Search Agent (per the overlap rule above)

nimble extract:templates run --template <name> --params '{"key": "value"}'

--params is a JSON/YAML mapping matching the template's input_schema. The response is the records defined by the template's output_schema (array for list/SERP-style, object for detail/PDP-style) — read the schema from get to know the shape. See references/nimble-extract-templates/reference.md.

⚠️ For finding information, use nimble search, not a SERP-analysis template. SERP templates are for rank/SEO analysis, not general retrieval.

Gate B — what does the user want back?

nimble search returns raw material to skim. A Web Search Agent returns a finished, cited answer. The prompt's deliverable noun decides it — route on that, not on how open-ended the topic sounds.

Structured rows about many entities → Web Search Agent with enrichment or dataset_building. See references/nimble-agents/reference.md.

Offer the fork when the answer is the expensive one

A Web Search Agent at high effort takes minutes and costs more; a search takes seconds. That's a real trade-off, so surface it — but only when Gate B lands on a Web Search Agent AND the recommended effort is `high` or above. One AskUserQuestion, recommended option first:

• Researched report — Web Search Agent, a few minutes, every claim cited
• Quick scan — nimble search, seconds, raw links you skim yourself

Below high, don't ask — just run the Web Search Agent. Never ask when Gate A already resolved the route.