nimble-agent-builder

What this skill does

# Nimble Agent Builder

Build, refine, and publish reusable extraction agents on the Nimble platform. Always finish with executed results or runnable code.

User request: $ARGUMENTS

## 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.

**Try CLI first** (exposes the full surface area — every flag, batch ops, file I/O):

```bash
nimble --version && echo "${NIMBLE_API_KEY:+API key: set}"
```

- CLI version + `API key: set` both print → proceed using `nimble ...` commands.

**Try MCP fallback** if CLI is missing:

```bash
claude mcp list 2>/dev/null | grep -q "nimble" && echo "MCP: connected" || echo "MCP: not connected"
```

- MCP connected → proceed using `mcp__plugin_nimble_nimble__*` tools instead of CLI.

**Neither available** → load `rules/setup.md`. The install path depends on the host:
- Any Claude product (Code, Cowork, claude.ai) → `/plugin install nimble` (one command, auto-registers MCP as a Connector, OAuth handles auth).
- Codex CLI or other terminal-only agents → `npm i -g @nimble-way/nimble-cli` + API key.
- Cursor / VS Code / generic MCP clients → paste the `mcp.json` snippet from `rules/setup.md`.

**Plugin installed but connector not connected** (typical Cowork / claude.ai): if `mcp__plugin_nimble_nimble__*` tools are listed, verify with one read-only `mcp__plugin_nimble_nimble__nimble_agents_list` probe before any work. An auth/not-connected error or an OAuth authorization URL means not connected — surface the verbatim connect steps from `rules/setup.md` and stop. Never substitute WebFetch, WebSearch, curl, or any other tool.

**If a tool returns 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 — no such step exists — and never claim tools "will activate" then call them in the same turn.

---

## Skill ecosystem

nimble-agent-builder and nimble-web-expert work as a pair in the Nimble toolkit:

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

### Stay in nimble-agent-builder for

- Generating a new agent for a domain
- Refining or updating an existing agent (add fields, fix selectors, change schema)
- Publishing an agent
- Running a published agent via `nimble agent run` (CLI)
- Validating agent output quality
- Any task phrased as "build", "refine", "update", "add a field to", "publish"

### When to route to nimble-web-expert

**After publishing an agent** — run it directly here via `nimble agent run` (CLI). Route to nimble-web-expert only when the workflow needs tools this skill doesn't have:

- Need a list of input URLs to feed into the agent? → Switch to nimble-web-expert, run `nimble map --url <site>` to crawl and generate the input list, then return here to run at scale.
- Need to search for input params? → Switch to nimble-web-expert, run `nimble search`, then return here with the results.

**When the task is not about building an agent:**

- One-off URL fetch, web search, site mapping, bulk crawl → nimble-web-expert
- Tell the user: _"This is a direct data access task, not an agent-building task. Use nimble-web-expert for this."_

### When agent generation needs site investigation

If `nimble_agents_generate` or `nimble_agents_update_from_agent` cannot produce a working agent because the site's data structure is unknown (wrong selectors, missing XHR patterns, unexpected JS rendering):

**Step 1 — Announce:** _"I can't generate a reliable agent without investigating the live page first. Spawning a site investigation..."_

**Step 2 — Spawn a Task agent** (`Task(subagent_type="general-purpose", run_in_background=False)`):

```
Investigate {url} to find CSS selectors and/or XHR API endpoints needed to extract: {fields_needed}.

Use Playwright to probe the live page:
python3 << 'EOF'
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    api_calls = []
    page.on("request", lambda req: api_calls.append(req) if req.resource_type in ("xhr","fetch") else None)
    page.goto("{url}")
    page.wait_for_timeout(5000)
    for sel in ["[data-price]",".price","h1","[data-testid*=title]","[data-testid*=price]",".product-title"]:
        el = page.query_selector(sel)
        if el: print(f"SELECTOR: {sel!r} -> {el.inner_text()[:80]!r}")
    for req in api_calls[:20]:
        print(f"XHR: {req.method} {req.url[:120]}")
    browser.close()
EOF

Also run a quick nimble extract to check raw rendered HTML:
nimble extract --url "{url}" --render --format markdown | head -100

Return a structured report:
- SELECTORS: working CSS selectors for each required field
- XHR_URLS: any relevant API endpoints found
- RENDER_REQUIRED: yes/no
- SUGGESTED_EXTRACT_COMMAND: the nimble extract command that would work
- NOTES: login walls, pagination, lazy loading, or anything unusual

Do NOT use AskUserQuestion.
```

**Step 3 — Use the report** to retry agent generation: pass the selector/XHR context and suggested extract command in the `nimble_agents_update_session` call.

**Step 4 — If investigation also fails:** Tell the user: _"This site requires complex browser automation that can't be captured in an agent at this stage. Use nimble-web-expert's Tier 4/5 commands with `--browser-action` or `--network-capture` to access the data directly."_

---

## Core principles

- **Fastest path to data.** Default route: discover agent → get schema → run → display results. Planning and generation are escalation paths.
- **Always search existing agents first.** Run `nimble agent list --limit 100 --search "<domain or vertical>"` (CLI) before considering generate. Hard rule.
- **Update over generate — always.** When a close-match agent exists (same domain/type, even if missing fields or different scope), update it rather than generating from scratch. Updating preserves proven extraction logic and is faster, cheaper, and more reliable. Only generate a new agent when the `--search` query returns 0 matches for the target domain. Never offer "Create new agent" as the recommended option when a close match exists.
- **AskUserQuestion at every decision point in the foreground — no exceptions.** Always present the standard `AskUserQuestion` prompts shown in each step. Never skip them, never auto-advance without asking. Never present choices as plain numbered lists. Constraints: 2–4 options, header max 12 chars, label 1–5 words. Recommended option goes first with "(Recommended)". Note: Task agents NEVER use AskUserQuestion — all decisions are pre-made before launching the Task.
- **Schema before run — always.** Run `nimble agent get --template-name <name>` (CLI) before `nimble agent run`. Present input parameters and output fields in markdown tables. This applies when switching agents too.
- **Script generation (Step 2B) is ONLY for large-scale, high-volume tasks.** Never generate code for normal interactive requests. Script mode requires ALL of: scale >50 items AND the user explicitly asks for code/script/CSV/batch output. Multi-source requests, dataset requests, and comparison requests do NOT automatically trigger script mode — run them int