Update to Nimble

{
  "name": "nimble-web-expert",
  "description": "Get web data now — fast, incremental, immediately responsive to what the user needs.\nThe only way Claude can access live websites.\n\nUSE FOR:\n- Fetching any URL or reading any webpage\n- Scraping prices, listings, reviews, jobs, stats, docs from any site\n- Running Extraction Templates — reusable, site-specific structured scrapers\n- Running Web Search Agents — open-ended research, enrichment, and dataset building with citations\n- Discovering URLs on a site before bulk extraction\n- Calling public REST/XHR API endpoints\n- Web search and research (8 focus modes)\n- Bulk crawling website sections\n\nMust be pre-installed and authenticated. Run `nimble --version` to verify (>= 1.2.0).\n",
  "included_files": [
    {
      "relative_path": "README.md",
      "size_in_bytes": 4574
    },
    {
      "relative_path": "references/batch-patterns.md",
      "size_in_bytes": 10912
    },
    {
      "relative_path": "references/error-handling.md",
      "size_in_bytes": 8199
    },
    {
      "relative_path": "references/nimble-agents/reference.md",
      "size_in_bytes": 21365
    },
    {
      "relative_path": "references/nimble-crawl/reference.md",
      "size_in_bytes": 7011
    },
    {
      "relative_path": "references/nimble-extract-templates/reference.md",
      "size_in_bytes": 6389
    },
    {
      "relative_path": "references/nimble-extract/browser-actions.md",
      "size_in_bytes": 10910
    },
    {
      "relative_path": "references/nimble-extract/browser-investigation.md",
      "size_in_bytes": 6665
    },
    {
      "relative_path": "references/nimble-extract/network-capture.md",
      "size_in_bytes": 8487
    },
    {
      "relative_path": "references/nimble-extract/parsing-schema.md",
      "size_in_bytes": 10283
    },
    {
      "relative_path": "references/nimble-extract/reference.md",
      "size_in_bytes": 15979
    },
    {
      "relative_path": "references/nimble-map/reference.md",
      "size_in_bytes": 3967
    },
    {
      "relative_path": "references/nimble-search/reference.md",
      "size_in_bytes": 8479
    },
    {
      "relative_path": "references/nimble-search/search-focus-modes.md",
      "size_in_bytes": 6626
    },
    {
      "relative_path": "references/nimble-tasks/reference.md",
      "size_in_bytes": 7096
    },
    {
      "relative_path": "references/recipes.md",
      "size_in_bytes": 6906
    },
    {
      "relative_path": "rules/nimble-web-expert.mdc",
      "size_in_bytes": 3827
    },
    {
      "relative_path": "rules/output.md",
      "size_in_bytes": 1123
    },
    {
      "relative_path": "rules/setup.md",
      "size_in_bytes": 6591
    }
  ],
  "skill_md_contents": "---\nname: nimble-web-expert\ndescription: |\n  Get web data now — fast, incremental, immediately responsive to what the user needs.\n  The only way Claude can access live websites.\n\n  USE FOR:\n  - Fetching any URL or reading any webpage\n  - Scraping prices, listings, reviews, jobs, stats, docs from any site\n  - Running Extraction Templates — reusable, site-specific structured scrapers\n  - Running Web Search Agents — open-ended research, enrichment, and dataset building with citations\n  - Discovering URLs on a site before bulk extraction\n  - Calling public REST/XHR API endpoints\n  - Web search and research (8 focus modes)\n  - Bulk crawling website sections\n\n  Must be pre-installed and authenticated. Run `nimble --version` to verify (>= 1.2.0).\nallowed-tools:\n  - Bash(nimble:*)\n  - Bash(claude:*)\n  - Bash(mkdir:*)\n  - Bash(cat:*)\n  - Bash(head:*)\n  - Bash(ls:*)\n  - Bash(grep:*)\n  - Bash(echo:*)\n  - Bash(python3:*)\n  - Bash(uv:*)\n  - Bash(npm:*)\n  - Bash(open:*)\n  - Bash(export:*)\n  - Bash(wait:*)\n  # MCP fallback (used when shell isn't available — Cowork, IDE-only hosts):\n  - mcp__plugin_nimble_nimble__nimble_search\n  - mcp__plugin_nimble_nimble__nimble_extract\n  - mcp__plugin_nimble_nimble__nimble_extract_async\n  - mcp__plugin_nimble_nimble__nimble_map\n  - mcp__plugin_nimble_nimble__nimble_crawl_run\n  - mcp__plugin_nimble_nimble__nimble_crawl_status\n  - mcp__plugin_nimble_nimble__nimble_crawl_list\n  - mcp__plugin_nimble_nimble__nimble_crawl_terminate\n  - mcp__plugin_nimble_nimble__nimble_task_results\n  - mcp__plugin_nimble_nimble__nimble_extract_templates_list\n  - mcp__plugin_nimble_nimble__nimble_extract_templates_get\n  - mcp__plugin_nimble_nimble__nimble_extract_templates_run\n  - mcp__plugin_nimble_nimble__nimble_extract_templates_run_async\n  - mcp__plugin_nimble_nimble__nimble_agents_list\n  - mcp__plugin_nimble_nimble__nimble_agents_get\n  - mcp__plugin_nimble_nimble__nimble_agent_templates_list\n  - mcp__plugin_nimble_nimble__nimble_agent_templates_get\n  - mcp__plugin_nimble_nimble__nimble_agents_run\n  - mcp__plugin_nimble_nimble__nimble_agents_run_status\n  - mcp__plugin_nimble_nimble__nimble_agents_run_result\n  - mcp__plugin_nimble_nimble__nimble_agents_runs_list\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n  - Task\n  - AskUserQuestion\nlicense: MIT\nmetadata:\n  version: 1.7.0\n  author: Nimbleway\n  repository: https://github.com/Nimbleway/agent-skills\n  category: web-search-tools\n---\n\n# Nimble Web Expert\n\nWeb extraction, search, and URL discovery using the Nimble CLI. Returns clean structured data from any website.\n\nUser request: $ARGUMENTS\n\n## Core principles\n\n- **Route by intent first** (see [Analyze & Route](#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`.\n- **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.\n- **One command → present results → done.** Run once, show the data immediately as a table. Do NOT experiment, loop, or write Python to parse output.\n- **Multiple inputs → always parallel.** 2+ URLs/keywords/ASINs → `&`+`wait`. 6–20 → `xargs -P`. 20+ → Python asyncio script. See `references/batch-patterns.md`.\n- **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.\n- **Never answer from training data.** Live prices, current news, today's listings → always fetch via Nimble. If unavailable, say so.\n- **AskUserQuestion at every meaningful choice.** Header ≤12 chars, 2–4 options, label 1–5 words, recommended option first. Never present choices as numbered prose.\n- **Save all outputs to `.nimble/`.** Never leave extraction results in memory only.\n- **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.\n- **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`.\n- **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.\n\n## Capabilities\n\nOne skill, one taxonomy. Use Nimble's own product names precisely — never paraphrase them.\n\n| Capability             | What it is                                                                        | Command family              |\n| ---------------------- | --------------------------------------------------------------------------------- | --------------------------- |\n| **Search**             | Real-time web search — raw results (pages, snippets), 8 focus modes               | `nimble search`             |\n| **Extract**            | Fetch + parse a single known URL (the one-off primitive)                          | `nimble extract`            |\n| **Extraction Template**| Reusable, site-specific structured scraper for a known item (by URL or identifier)| `nimble extract:templates`  |\n| **Web Search Agent**   | Open-ended research / enrichment / dataset building — discovers sources, synthesizes, cites | `nimble agents` / `agents:runs` |\n| **Map**                | Discover the URLs that exist on a site                                            | `nimble map`                |\n| **Crawl**              | Bulk-fetch many pages across a site (one-time, at scale)                          | `nimble crawl`              |\n\nExtraction 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).\n\n## Interactive UX\n\n- Use `AskUserQuestion` at every meaningful choice — never guess, never ask in prose.\n- **Ambiguous request** (no URL, vague topic): ask before running — \"What would you like to do?\" → Research & report / Search / Fetch URL / Discover URLs\n- **Gate B landed on a Web Search Agent at `high`+ effort**: offer the cost/latency fork — Researched report / Quick scan (see [Analyze & Route](#analyze--route))\n- **Before running a search** (if task maps to a specific focus mode): offer focus mode — General / News / Coding / Shopping / Academic / Social\n- **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.\n- After presenting results, always close with: \"Were these results what you needed?\" → `Looks great!` / `Mostly good` / `Not quite` / `Skip feedback`\n\n## Prerequisites\n\nPick 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.\n\n```bash\nnimble --version && echo \"${NIMBLE_API_KEY:+API key: set}\"        # CLI path\n# OR (fallback when shell isn't available)\nclaude mcp list 2>/dev/null | grep -q \"nimble\" && echo \"MCP: ok\"  # plugin MCP\n```\n\n- **CLI ready** (version + API key both print) → proceed to [Step 0](#analyze--route), use `nimble ...` commands.\n- **MCP connected** (no CLI, but plugin is installed) → proceed to [Step 0](#analyze--route), use `mcp__plugin_nimble_nimble__*` tools instead.\n- **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.\n\n**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.**\n\n---\n\n## Analyze & Route\n\nTwo 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.\n\n### Gate A — do I know where the data lives?\n\n| User signal                                   | Route                                                                               |\n| --------------------------------------------- | ------------------------------------------------------------------------------------ |\n| Direct single URL to fetch                    | `nimble extract`                                                                     |\n| Named site + a direct item to look up (URL/ID)| **Step 0** — check for an Extraction Template first                                  |\n| \"Find URLs / sitemap / all pages\"             | `nimble map`                                                                         |\n| \"Crawl / archive a whole section\"             | `nimble crawl`                                                                       |\n| **No location signal at all**                 | Fall through to **Gate B**                                                           |\n| Named site with **no** template               | Fall through to **Gate B**, carrying the site as a source constraint                 |\n\n**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.\n\n### Step 0 — Extraction Template check (when a site + direct item is named)\n\nTemplates return clean structured data with zero selector work. Always check first.\n\n**Always verbalize — never silently:**\n\n1. **Announce:** _\"Let me check if there's a Nimble Extraction Template for [site]...\"_\n2. **Report:** _\"Found `<template_name>` — using it now.\"_ or _\"No template for [site] — using a Web Search Agent instead.\"_\n\n**Lookup order:**\n\n1. `~/.claude/skills/nimble-web-expert/learned/examples.json` → learned templates\n2. `nimble extract:templates list --limit 100` → filter by site/domain client-side; confirm the match\n3. Inspect the schema before running: `nimble extract:templates get --extract-template-name <name>`\n4. No match → route to a Web Search Agent (per the overlap rule above)\n\n```bash\nnimble extract:templates run --template <name> --params '{\"key\": \"value\"}'\n```\n\n`--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`.\n\n⚠️ For finding information, use `nimble search`, not a SERP-analysis template. SERP templates are for rank/SEO analysis, not general retrieval.\n\n### Gate B — what does the user want back?\n\n`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.\n\n| → **Web Search Agent**                                                | → **`nimble search`**                       |\n| ---------------------------------------------------------------------- | --------------------------------------------- |\n| report, brief, analysis, landscape, teardown, deep dive                | find, search for, look up                     |\n| compare, \"best X\", \"which should I\", \"state of\", recommend             | \"pages/articles about\", \"links to\"            |\n| enrich, build a list, dataset, \"…with their pricing/headcount\"         | latest news, recent posts, what's trending    |\n\nStructured rows about many entities → Web Search Agent with `enrichment` or `dataset_building`. See `references/nimble-agents/reference.md`.\n\n### Offer the fork when the answer is the expensive one\n\nA 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:\n\n- **Researched report** — Web Search Agent, a few minutes, every claim cited\n- **Quick scan** — `nimble search`, seconds, raw links you skim yourself\n\nBelow `high`, don't ask — just run the Web Search Agent. Never ask when Gate A already resolved the route.\n\n**Dataset requests always clear the threshold.** \"Build a list of…\" → `dataset_building`, which runs at `high` or above by definition, so the fork always applies. Enrichment has no such floor — judge \"enrich these rows\" on the normal effort rule and skip the prompt when a small, well-specified fill-in lands below `high`.\n\n**Before starting any Web Search Agent run, say how long it will take**, then narrate at phase transitions. On MCP, progress comes from bounded status polling rather than a live stream — poll and report each step, because an un-narrated multi-minute run reads as a hang.\n\n---\n\n## Workflow\n\n| Situation                        | Command                                        | Reference                                            |\n| -------------------------------- | ---------------------------------------------- | ---------------------------------------------------- |\n| Site + item → template first     | `extract:templates list` → `extract:templates run` | `references/nimble-extract-templates/reference.md`   |\n| Research / enrichment / dataset  | pick a run mode → `get` → `result`             | `references/nimble-agents/reference.md`                  |\n| Direct URL                       | `nimble extract`                               | `references/nimble-extract/reference.md`                 |\n| Search the live web              | `nimble search`                                | `references/nimble-search/reference.md`                  |\n| Discover URLs on a site          | `nimble map`                                   | `references/nimble-map/reference.md`                     |\n| Bulk crawl a section             | `nimble crawl run`                             | `references/nimble-crawl/reference.md`                   |\n| Batch templates (up to 1,000)    | `nimble extract:templates batch`               | `references/nimble-extract-templates/reference.md`       |\n| Batch extract (up to 1,000)      | `nimble extract-batch`                         | `references/nimble-extract/reference.md`                 |\n| Poll tasks / batches / results   | `nimble tasks` / `nimble batches`              | `references/nimble-tasks/reference.md`                   |\n| Unknown selectors or XHR path    | browser-use or Playwright investigation        | `references/nimble-extract/browser-investigation.md` |\n| Proven site patterns             | copy a recipe                                  | `references/recipes.md`                              |\n| 2+ inputs                        | parallel bash `&`+`wait` or generated script   | `references/batch-patterns.md`                       |\n\nFor the full extract waterfall (tiers, flags, browser actions, network capture), see `references/nimble-extract/reference.md`.\n\n---\n\n## Response shapes\n\n| Command                     | Output                                                                                  |\n| --------------------------- | --------------------------------------------------------------------------------------- |\n| `nimble extract:templates`  | Records per the template's `output_schema` — array (list/SERP) or object (detail/PDP)   |\n| `nimble agents:runs result` | `output` (`type:\"text\"` prose or `type:\"json\"` structured) + `trust` per-claim citations |\n| `nimble extract`            | HTML, Markdown, or parsed JSON — depends on `--format` and `--parse`                     |\n| `nimble search`             | Structured results array (title, URL, description)                                      |\n| `nimble map`                | URL list + metadata                                                                     |\n| `nimble crawl`              | Async job — poll with `nimble crawl status <job_id>`                                     |\n\n**Read the template's `output_schema` (from `extract:templates get`) before parsing** — a list/SERP-style template returns an array, a detail/PDP-style template returns an object. Web Search Agent runs are async: poll `agents:runs get` to a terminal state, then fetch `result`.\n\n## Output & Organization\n\n```bash\nmkdir -p .nimble   # save all outputs here\n```\n\nNaming: `.nimble/<site>-<task>.md` (e.g. `.nimble/amazon-airpods.md`, `.nimble/yelp-sf-italian.json`)\n\nWorking with saved files:\n\n```bash\nwc -l .nimble/page.md && head -100 .nimble/page.md\ngrep -n \"price\\|rating\" .nimble/page.md | head -30\n```\n\nEnd every response with: `Source: [URL] — fetched live via Nimble CLI`\n\n---\n\n## Self-Improvement\n\nThe skill maintains `~/.claude/skills/nimble-web-expert/learned/examples.json`.\n\n- **At task start:** read the file, scan `good[]` for `url_pattern` matches → use documented `command`/`tier` as starting point. Scan `bad[]` → avoid documented pitfalls.\n- **After presenting results:** ask \"Were these results what you needed?\" → on positive feedback, append to `good[]` with `url_pattern`, `task`, `command`, `tier`, `notes`. On negative feedback, ask \"What went wrong?\" and append to `bad[]` with `url_pattern`, `task`, `issue`, `avoid`, `better`.\n- Keep entries concise — 5–10 per site. Only write on real feedback, never speculatively.\n\n---\n\n## Guardrails\n\n- **NEVER answer from training data** for live prices, current news, or real-time data. If Nimble is unavailable, say so.\n- **NEVER skip Step 0 silently.** Even if certain there's no template, announce the check before falling back to a Web Search Agent or extract/search.\n- **NEVER answer a synthesis deliverable with raw search results.** \"Report\", \"brief\", \"compare\", \"best X\", \"which should I\" → Gate B routes to a Web Search Agent. Handing back a list of links and calling it a report is the most common mis-route.\n- **Distinguish Extraction Templates from Web Search Agents.** Never call a template a \"WSA\"/\"legacy WSA,\" and never route a template use to `agents` by name alone (or the reverse). Building new templates/agents is out of scope — use existing ones.\n- **When a run comes back empty, partial, or clearly wrong, say so plainly** — a domain that returned nothing, a template that matched poorly, a search with no relevant hits are real outcomes, not something to present as success. Suggest an obvious next step (broader source, a different capability) where one exists.\n- **NEVER retry the same render tier.** If a tier returns empty or truncated content, escalate — do not re-run.\n- **NEVER escalate at an access barrier.** A CAPTCHA, a human-verification page, or a sign-in wall in place of the target is a real outcome — report it plainly and stop. Where a supported alternative exists, take it: `--focus social` search for social profiles, public search results for gated articles.\n- **NEVER substitute WebFetch, WebSearch, curl, or wget for nimble operations.** They're not in `allowed-tools` — if a Nimble transport isn't available, stop and follow the guidance in the no-transport branch of Core principles. Don't try to work around it.\n- **NEVER load reference files speculatively.** Only read a reference when the current task explicitly needs it.\n- **Task agents MUST use `run_in_background=False`.**\n- **Hard retry limit.** On error (not empty content): retry at most 2 times with different flags. After 2 errors, report and stop.\n- **Hard 429 rule.** On rate-limit error: stop immediately. Do not retry or switch tiers.\n\n---\n\n## Reference files\n\nLoad only when needed:\n\n| File                                                 | Load when                                                                     |\n| ---------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `references/recipes.md`                              | Need a proven command for a common site (Amazon, Yelp, LinkedIn…)             |\n| `references/nimble-extract-templates/reference.md`       | Step 0 — discover/inspect/run Extraction Templates for a known site           |\n| `references/nimble-agents/reference.md`                  | Web Search Agents — discovery, run lifecycle, authoring, trust/citations      |\n| `references/nimble-extract/reference.md`                 | Extract flags, render tiers, browser actions, network capture, parser schemas |\n| `references/nimble-search/reference.md`                  | Search flags, all 8 focus modes                                               |\n| `references/nimble-map/reference.md`                     | Map flags, response structure                                                 |\n| `references/nimble-crawl/reference.md`                   | Full async crawl workflow                                                     |\n| `references/nimble-tasks/reference.md`                   | Poll tasks/batches, fetch results — for async, batch, and crawl operations    |\n| `references/nimble-extract/browser-investigation.md` | Tier 6 — CSS selector/XHR discovery with browser-use or Playwright            |\n| `references/nimble-extract/parsing-schema.md`        | Parser types, selectors, extractors, post-processors                          |\n| `references/nimble-extract/browser-actions.md`       | Full browser action types and parameters                                      |\n| `references/nimble-extract/network-capture.md`       | Filter syntax, XHR mode, capture+parse patterns                               |\n| `references/nimble-search/search-focus-modes.md`     | Decision tree, mode details, combination strategies                           |\n| `references/batch-patterns.md`                       | Parallel bash patterns for 2–5, 6–20, and 20+ inputs                          |\n| `references/error-handling.md`                       | Error codes, known site issues, troubleshooting                               |\n"
}