Live web search for AI agents. Find current pages, read any URL, and run research agents that work across many sources and return findings with citations. Includes reusable Extraction Templates for consistently shaped records from known sites, and Web Search Agents for research, enrichment, and dataset building.

version
1.10.0
GitHub stars
75

Install

/plugin install nimble@nimble-plugin-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Nimbleway/agent-skills.

Contents

Discovered from source

Skills 36

Account brief

Writes a dated, sourced brief on one company before a sales meeting: what they do, priorities, challenges, changes in the last 90 days, key people and talking points.

What the user gets

A short brief: what the company does, current priorities and challenges with evidence, what changed in the last 90 days, key people, and talking points. Every item is dated and sourced.

Agent template

This skill runs the Nimble gallery template account-brief. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesName and domain-
What you sellnoOne line. It sharpens the talking pointsgeneral talking points
Meeting goalnoFor example a first call, a renewal or an exec introno specific goal
People in the meetingnoNames and titles, if they want a line on eachno named attendees
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your meeting preparation assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Prepare me for a meeting with <Company> (<domain>). I sell <one line>. The meeting is <goal>.

Example: Prepare me for a meeting with Attio (attio.com)

  • Always include the domain. It stops the agent from drifting to a company with a similar name.
  • If they name the people in the meeting, add them to the input.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="account-brief", agent_name="account-brief"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="account-brief", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="account-brief", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Brief another company. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as account-brief: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Challenges come from reviews, press and job posts. If none are found, the list is short on purpose.
  • Check the dates on recent changes. Anything older than 90 days should not be there.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Account deep research with Nimble Web Search Agents

A Web Search Agent takes one research question, plans its own searches, reads dozens of pages in parallel (company sites, newsrooms, careers pages, ATS boards, the press) and returns a cited answer, either free text or JSON that matches a schema. This skill runs the 12 GTM agents Nimble publishes (nine in its agent gallery, three from its GTM developer guide) and builds a custom agent when a request falls outside them.

1. Route before you spend a run

The requestUse
One closed fact ("Who is Gong's CFO?", "Did Clay raise this year?")account-fast-search (Search with an answer)
One known URL (a pricing page, a job post, a press release)account-fast-search (Extract)
A named account or question that needs several sources, a table or verificationThis skill: one agent run
Tens to thousands of rows to enrich or a list to build and push to a CRMaccount-lists-and-enrichment
Job postings, reviews or listings tracked over timegtm-data-at-scale

Use one run per account and question. Do not research first and then start a run, and do not split one question across several runs. Put every sub-question in the run's input. For a watchlist, put all accounts in one gtm-buying-trigger-monitor run rather than one run per account.

2. Pick the agent

Agent (agent_name)Use it when the user asks...Use caseSource
account-briefto prepare for a meeting or call: what the company does, its priorities and challenges, recent changes, key people, talking pointsresearchgallery
account-signalswhat changed at one account since a date: funding, hires and departures, launches, layoffs, pricing changes, hiring pushesresearchgallery
gtm-buying-trigger-monitorfor buying triggers across a watchlist in a window, graded High/Medium/Low for a stated seller, with an outreach angle per account and the rejected events listedresearchgallery (GTM guide)
decision-maker-identificationwho currently holds named roles at an account (CRO, head of RevOps, CTO...), with title, start date, past roles and public profilesenrichmentgallery
competitive-intelligencefor a side-by-side of named competitors: published pricing and plans, target customers, differentiators, recent announcementsresearchgallery
brand-intelligencehow a brand or product is being talked about (Reddit, X, LinkedIn, review sites): a sentiment score, themes, incidentsresearchgallery
social-media-monitorwhat named people or handles posted in a window, with engagement, and what went viraldataset_buildinggallery
account-enrichmentfor firmographics on one domain: legal name, HQ, industry, ownership, headcount, funding, leaders, tech stack usedenrichmentgallery
gtm-account-enrichmentto fill a CRM record from a domain: products, target customer, HQ, headcount, funding and investors, leadership, customer count, hiring, recent signals, with conflicts between sources keptenrichmentgallery (GTM guide)
account-discoveryfor companies matching an ICP description, each with why it fits and a sourcedataset_buildinggallery
gtm-icp-discoveryfor an ICP list where every hard criterion (HQ, category, size, stage, a live sales posting) is verified on a cited page, plus near-misses with the criterion they faileddataset_buildinggallery (GTM guide)
business-discoveryfor local businesses by category and place (clinics, salons, contractors, restaurants) with address, phone, website, rating and review countdataset_buildinggallery

Each agent's full spec (its skill, output schema, effort and example questions) is in agents/<agent_name>.json next to this file. Read the matching file before the first run; its suggested_questions show the input format the agent expects. The specs are snapshots of the gallery templates (2026-11-12). All 12 are in the Go-to-market section of the Nimble Web Search Agent gallery, each with a pre-run example answer. The three GTM-guide agents started in Nimble's cookbook (Nimbleway/cookbook, apps/gtm-*-agent) and were tightened for the gallery: their rules live in the skill and every schema object has non-null required fields.

If two agents fit, run the one closest to the user's words and the shape they need:

  • One account, a quick answer → the gallery agent (account-signals, account-enrichment, account-discovery), at medium effort where its spec says so.
  • A watchlist, CRM-ready fields or a verified list → the GTM-guide agent (gtm-buying-trigger-monitor, gtm-account-enrichment, gtm-icp-discovery) at high.
  • "Who should I call?" is decision-maker-identification; "prep me for Thursday" is account-brief; "is anything happening at X?" is account-signals.
  • Anything about a specific person (a brief on an attendee, a buying committee, whether a contact changed jobs) goes to people-research, which has fast Search patterns and people-focused agents.

For more than a handful of accounts to enrich or a list headed for a CRM, hand off to account-lists-and-enrichment, which batches these same agents and applies write-back rules. If none fits, go to section 5 and build a custom agent.

3. Get the agent into the account (reuse first)

Check in this order and stop at the first hit:

  1. Already in the account. nimble_agents_list (MCP) or GET /v2/agents. Look for an agent with the same agent_name (or gallery-<name>, gtm-<name>). If found, run it by agent_id.
  2. In the gallery. nimble_agent_templates_list (or GET /v2/agents/templates). If a template with the same template_name exists, create from it: nimble_agents_create(template="account-brief", agent_name="account-brief"). The gallery copy is maintained by Nimble, so prefer it over the bundled file. If the gallery does not list a template (an older deployment, or a custom agent), go to step 3.
  3. From the bundled spec. Create the agent from agents/<agent_name>.json. Pass its agent_name, display_name, description, use_case, effort, skill, output_schema and suggested_questions unchanged (omit output_schema when it is null: that agent returns free text).

MCP:

nimble_agents_create(
  agent_name="gtm-buying-trigger-monitor",
  display_name="GTM Buying Trigger Monitor",
  description=<description>, use_case="research", effort="high",
  skill=<skill>, output_schema=<output_schema>, suggested_questions=<suggested_questions>)

REST (any language, NIMBLE_API_KEY from the environment, never printed):

jq '{agent_name, display_name, description, use_case, effort, skill, output_schema, suggested_questions}
    | with_entries(select(.value != null))' \
  agents/gtm-buying-trigger-monitor.json |
curl -s -X POST https://sdk.nimbleway.com/v2/agents \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" -d @-

Create each agent once and reuse it. A new agent per account loses the agent's learned context (which sources and retrieval patterns worked) and clutters the account.

4. Run it and read the result

Write input in the shape of the agent's suggested questions: the company's name and domain (the domain stops namesake drift: there are many companies called Eve, Mercury or Clay), the window or "since" date, the roles or criteria, and the seller's context when grading matters ("the seller offers revenue software to B2B SaaS companies"). Keep it short. The agent's skill already holds the method.

nimble_agents_run(agent_id=<id>,
  input="Prepare me for a meeting with Gong (gong.io). I sell data infrastructure to revenue teams; the meeting is with their VP of RevOps.")
→ nimble_agents_run_status(run_id=<run_id>, agent_id=<agent_id>) # waits ~45 s per call; call again until it completes

REST: POST /v2/agents/{agent_id}/runs with {"input": ...} (enrichment agents also take input_data: the CRM record with the fields to fill set to null), poll GET /v2/agents/{agent_id}/runs/{run_id} while is_active, then GET .../runs/{run_id}/result. Set trust_mode: "full_trust" (MCP) when the user wants per-claim confidence and citations, for example before writing to a CRM.

Timing: medium runs take about 1 to 3 minutes, high about 3 to 8 (a five-account trigger watch took about 4.5 minutes, an ICP list about 7.5), x-high can run to 15 or more. Tell the user the run started and roughly how long it takes. Do not start a second run of the same question while one is active.

Check before you present. completed means finished, not correct:

  • Rows or sections returned against what was asked. An empty events list or trigger_count: 0 is a valid answer when nothing happened; a thin list on a busy company (a recent funding round you can find in one search is missing) means the agent stopped early; say so.
  • Entity drift: every source is about the right company (domain, HQ city, product), not a namesake, a parent or a former employer's page.
  • Open two or three citations. Each source_url must be the page that states the value, not a search page or a homepage.
  • Event dates, not article dates. "Since 2026-09-21" means the event happened after it; a feature re-covered this month about a 2025 round is excluded. Check the excluded_events list where the agent returns one.
  • People are current. A title counts only when a dated source in the last year or a current profile shows it; old bio pages and conference speaker pages go stale. Never present an email or phone number that a page did not publish.
  • Numbers carry their date and source type: "about 376 employees (LinkedIn, 2026-10)" and "1-10 (Crunchbase)" are a conflict to show, not average.
  • Required fields can come back null. The platform does not enforce the schema at run time, so check the required fields and say which are empty rather than filling them.
  • No internal references in text. Strings such as quote:/pages/..., .md#L12 or file paths inside a field are leaks; remove them and cite the source_url instead.
  • Lists are not padded: for gtm-icp-discovery, every row in companies should have a live sales_role_url and evidence for each criterion; a row that misses one belongs in near_misses.
  • Pricing: a vendor's own pricing page is the only source for its prices; "Not publicly listed" is a correct answer.
  • Social: logged-in or blocked platforms (X, LinkedIn feeds) may come back thin. Report a platform the agent could not reach as a coverage gap, not as "no posts".

Present the answer with its citations inline. Lead with what the seller acts on: the strongest trigger and its outreach angle, the two or three talking points for the meeting, the person to contact. Label anything that is a company's own claim (a customer count on its homepage) as the company's claim.

Follow-ups. For a narrower follow-up on the same account, run the same agent again with previous_interaction_id set to the earlier run's interaction_id (REST), or put the earlier answer's key facts into the new input. Rerunning account-signals or gtm-buying-trigger-monitor with a later "since" date produces the change log; schedule it weekly for a watchlist.

5. When nothing fits: build a custom research agent

Create one agent per repeatable question type, not per account. Name it gtm-custom-<topic> so it is found and reused next time.

  1. Classify use_case. research for a brief or a nested answer on one subject (an account, a deal, a market); dataset_building for a list of entities that meet criteria (every company exhibiting at a conference, every customer a competitor names, every clinic in a county); enrichment for adding fields to rows the user already has (a watchlist or CSV, at most 20 rows and 200 cells per run, practical batch about 5 rows for 6 researched fields).
  2. Write the skill as a playbook, in the style of the bundled specs: where the evidence lives (the company's newsroom, careers page, ATS boards, case studies, integration directories, trade press, registries), what each term means for this seller, the pitfalls, and the evidence rules. Copy the "Citations and evidence" block verbatim from account-brief or gtm-buying-trigger-monitor; it holds the citation, dating and entity rules every GTM agent needs.
  3. Write goals (REST only; some clients drop them, so also state them in the skill) as 3 to 8 checkable requirements, for example "Return accounts with no qualifying event with trigger_count 0 instead of padding with weak events".
  4. Design the output_schema. Flat, 5 to 8 described fields per object, ["string","null"] for anything uncertain, YYYY-MM-DD dates, numbers as numbers with the unit in the description, enums for judgments (trigger type, strength, fit), a source_url per value, and a missing_fields or excluded_events array so absence and rejections are reported, not hidden. Put the field a rep acts on first (strongest_trigger, outreach_angle, why_it_fits). Array root for lists. No format, pattern, min*, max* or free-form maps.
  5. Set sources when you know them: prioritize (company newsrooms, ATS boards, trade press for the vertical) and avoid (SEO listicles, "top 10" vendor posts, aggregators that re-date old news, job boards as evidence of an event).
  6. Effort. high for anything with a schema and for all dataset building (required). medium for a single-account brief or signals check. x-high for a multi-vendor comparison or an exhaustive single-site catalog. Never low when citations matter.
  7. Test on one account you already know the answer for, check it against section 4, then fix the skill or schema (not the effort) before running the rest.

One-shot create-and-run (MCP): nimble_agents_run(agent_name="gtm-custom-<topic>", use_case=..., effort="high", skill=..., output_schema=..., input=...). An unseen name creates the agent; a known name reuses it.

Example: "Which of Gong's customers named on its site are hiring RevOps leaders?" is dataset_building, with a skill that names Gong's customer stories and logo wall, the customers' own careers pages and ATS boards, and a schema of company, domain, customer_evidence_url, role_title, role_url, posted_date, location.

6. Rules that apply to every run

  • Public information only. No logged-in, paywalled or purchased data. Never construct an email address or phone number from a pattern; only publish contact details a page states, and only when the task needs them.
  • Facts, not guesses. A value nobody published is null. Pains, priorities and intent are reported only when a source shows them, with the source.
  • First-party sources win for what a company says about itself (product, pricing, leadership, open roles): its own site, newsroom, careers page and filings. Reputable press beats aggregators; aggregators are for discovery and corroboration.
  • Point in time. Every value carries the date it was published or happened. A headcount, a title or a price without a date is a lead, not a fact.
  • No padding. Fewer, verified rows beat a list filled to the requested count.
  • Web Search Agents read public pages. For LinkedIn, Glassdoor or social feeds, use gtm-data-at-scale (Extract Templates) or --focus social search.

Account discovery

Builds a list of companies that match an ideal customer profile (ICP), each with the reason it fits and a source.

What the user gets

A list of companies that match the profile. Each row has the company name, website, why it fits, and a source.

Agent template

This skill runs the Nimble gallery template account-discovery. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
Ideal customeryesWhat they sell or do, for example the industry or product-
GeographynoWhere they are basedany location
SizenoEmployee rangeany size
Hard rulesnoFor example "raised Series A or later since 2024". To leave companies out, ask for their names or domainsno extra rules
Best-fit examplesnoTwo or three customers or domains to find more likeno examples
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your prospecting assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Find <type of company> in <geography> with <size>, that <hard rules>. Companies like <examples>.

Example: Find US-based vertical SaaS companies for dental practices, 50-500 employees, that sell practice-management or patient-engagement software

  • Turn each criterion into a clear test. "Mid-market" is not a test. "200-2,000 employees" is.
  • Do not ask for a number of rows. The agent returns every company it can verify.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="account-discovery", agent_name="account-discovery"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="account-discovery", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="account-discovery", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Try a different profile. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as account-discovery: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Headcount for private companies is often a range. Accept a range, or good rows drop out.
  • Fewer rows than expected is a signal, not a finished list. Offer a deeper run or a wider profile.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Account enrichment

Fills a CRM record for a company from its domain: firmographics, current leadership, tech stack and funding, every field cited or left empty.

What the user gets

One record per company: legal name, HQ, founded, employees, industry, ownership, leadership, tech stack and funding. Each field has a source, or is left empty with a reason.

Agent template

This skill runs the Nimble gallery template account-enrichment. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesIts domain-
Extra fieldsnoAnything beyond the default fields, for example "SOC 2 status" or "uses Salesforce"standard fields only
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your CRM enrichment assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Enrich the company at <domain>

Example: Enrich the company at attio.com

  • One company at a time. If the user names several, run the first and offer the rest next.
  • Extra fields go in the input as one line each, for example: "Also return: SOC 2 status (yes/no, with source)."

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="account-enrichment", agent_name="account-enrichment"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="account-enrichment", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="account-enrichment", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Enrich another company. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as account-enrichment: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Tech stack means tools the company uses, not tools it sells.
  • A missing CFO or CRO is often real. Check missing_fields before calling it a gap.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Fast web search for GTM

Nimble gives three fast tools. Pick the cheapest one that answers the question, and answer in seconds rather than minutes.

ToolWhat it doesUse it for
Search (nimble_search, POST /v2/search)Live web results across engines; optional cited answer (include_answer), full page text (full_content)Finding the page: the press release, the job post, the leadership page, the article. One closed fact.
Extract (nimble_extract, POST /v2/extract)Clean markdown from one known URL, rendered and unblocked when neededReading the page you found: a pricing page, a careers page, an ATS board, a customer story, a newsroom post
Extract Template (nimble_extract_templates_*, POST /v2/extract/templates/run)Structured JSON from a supported site (Google Maps, Indeed, LinkedIn job search, Google Search, ChatGPT and Perplexity answers, YouTube, TikTok...)A known listing, job search, SERP or AI answer on a named site

Escalate to account-deep-research when the answer needs more than about three searches or pages, several sources reconciled, a table, or verification across sites (a meeting brief, a trigger check, a competitive comparison). For anything about a specific person beyond one quick fact (a brief, a buying committee, job changes), use people-research. For a list of accounts or a CSV to fill, use account-lists-and-enrichment. For hundreds of job posts, reviews or listings over time, use gtm-data-at-scale.

The fast loop

  1. Pin the entity. Write down the company name and its domain before searching (plus HQ city or ticker if it helps). Use the domain in every query or as include_domains. Watch for namesakes (Eve the legal AI vs. Eve the mattress, Mercury the bank vs. Mercury the insurer), rebrands and former names, parents and subsidiaries, and products whose name differs from the company's. For a person, pin name plus current company.
  2. Decide what kind of source answers it (see references/source-map.md) and aim the query there with include_domains or a site: operator.
  3. Search narrow. max_results 3 to 5, search_depth: "lite" when titles and URLs are enough to pick the page, the default (standard) when snippets may hold the answer.
  4. Read the primary page with Extract when the snippet is not enough or the value matters. Quote the value from the page, not from the snippet.
  5. Answer with the citation and its date: the value, the URL it was read on, and the date the source published it. Say what you checked and did not find, naming the pages and the period they cover.

Stop at the first first-party or primary source that answers the question. If after three searches you are reconciling conflicting pages, escalate to a Web Search Agent instead of searching more.

Writing queries

  • Quote exact phrases a page would contain: "appointed" "Chief Revenue Officer", "joins as", "Series B", "led by", "acquires", "now available", "partnership", "case study".
  • Scope by domain: the account's own domain for products, pricing, leadership and newsroom; ATS boards for hiring (job-boards.greenhouse.io, boards.greenhouse.io, jobs.ashbyhq.com, jobs.lever.co, apply.workable.com, jobs.gem.com); press wires (prnewswire.com, businesswire.com, globenewswire.com) for announcements; g2.com, capterra.com, trustradius.com for reviews. Up to 50 domains; exclude_domains drops listicles, content farms and data-broker pages.
  • Scope by time: time_range (day, week, month, year) for "latest" questions, or start_date / end_date (YYYY-MM-DD) for a window such as "since our last call". They cannot be combined.
  • Pick the focus (focus modes work only with search_depth: "lite"): focus: "news" for what happened recently; focus: "general" with content_type: ["pdf"] (or presentations) for case studies, annual reports and investor decks; focus: "location" for offices and stores; up to 10 Extract Template names in focus to fan one keyword across sites.
  • One question per search. Run independent searches in parallel rather than one long query.

Patterns that travel across most tasks:

NeedQuery sketch
Who holds a role"<Company>" "VP of Sales" OR "Chief Revenue Officer" with the company's domain; then a date-scoped search on the person's name to confirm the title is still current (see people-research)
A new executive"<Company>" <domain> appoints OR "joins as" OR hires CRO OR CMO OR "VP", time_range: "month"
Funding"<Company>" <domain> raises Series, focus: "news" with search_depth: "lite", start_date set to the window
Acquisitions and partnerships"<Company>" acquires OR "acquired by" OR partnership, focus: "news"
Product launchesinclude_domains: [<domain>] + launch OR "now available" OR "introducing", time_range: "month"; or Extract the changelog or blog
Hiring (and what they are building)"<Company>" jobs with include_domains set to the ATS boards plus their careers domain, search_depth: "lite", max_results: 20; Extract the board to count open roles by function
Tech stack they use"<Company>" "experience with" Salesforce OR HubSpot OR Snowflake on ATS boards (job posts name tools); vendor case studies naming the account; their integrations page
Pricing and packagingExtract the account's or competitor's /pricing page; web.archive.org/web/<YYYYMMDD>/<url> for the earlier version
Customers they announced"<Company>" "case study" OR "customer story" OR "selects", or Extract their customers page
Reviews and reputation"<Product>" reviews with include_domains: ["g2.com","capterra.com","trustradius.com"]; google_maps_reviews template for local businesses
Events and sponsors"<Conference> 2026" sponsors OR exhibitors, then Extract the sponsor page
What AI assistants say about a brandchatgpt, perplexity, google_ai or gemini template with the buyer's prompt
Public company priorities"<Company>" "earnings call" OR "investor day" 2026; 10-K and 8-K on sec.gov (include_domains: ["sec.gov"])

For a single closed fact, set include_answer: true (Nimble Answer) and still check that the answer cites a first-party or reputable page.

Reading pages with Extract

  • Pass the exact URL. Default output is markdown, which is what an agent should read.
  • If the page comes back empty or truncated, retry with a JS-rendering driver (vx8) or a full-browser driver (vx10) before giving up; add wait (ms) for pages that load data late (many careers pages and ATS embeds do).
  • Use country (and locale) for region-specific pricing.
  • A PDF case study, annual report or deck can be parsed to markdown through the REST API or CLI with file_parsing_options ({"mode": "light"}); the MCP server does not expose that option.
  • On sites Nimble maintains a template for, use the template: it returns stable fields instead of page text. Find it with nimble_extract_templates_list(query="<site>"), inspect params with nimble_extract_templates_get, run with nimble_extract_templates_run. Prefer templates managed_by: "nimble"; community templates vary in quality.

Source priority

Use secondary pages to find facts and primary pages to cite them.

  1. The company's own pages: site, newsroom and blog, leadership page, careers page and ATS board, pricing, docs and changelog, customers page. Authoritative for what the company says about itself; note that customer counts and growth claims are the company's claims.
  2. Official records: SEC filings for public companies, state and national company registries, court dockets, government contract awards.
  3. Press releases and reputable press: press wires, business and trade press.
  4. Aggregators and data sites (Crunchbase, PitchBook, Tracxn, review aggregators): useful for discovery; often stale on headcount, funding totals and titles.
  5. Social posts and forums: signals and context, not facts on their own. Verify against a first-party page.

When two sources disagree, show both with their dates; for fast-moving values (headcount, open roles, titles) the most recent dated first-party value usually wins.

Timing and point-in-time

  • Date events by when they happened, not when an article was published. Republished or roundup coverage of old news is the most common false "new" signal.
  • Titles go stale quickly. A role counts as current only with a dated source in the last year or a page that shows it as current today.
  • Job posts come and go. Record the date you saw a posting and its URL; a closed posting is not evidence of current hiring.
  • Prices change without announcement. Quote the pricing page with the date you read it; use web.archive.org for the earlier version.
  • Check whether something was reversed: an announced partnership that ended, an executive who has since left, a product that was sunset.

Privacy and compliance guardrails (apply to every lookup)

  • Public information only. Do not use logged-in, paywalled or purchased data, and do not try to get past logins, paywalls or CAPTCHAs or create accounts to see data.
  • Personal data is minimal. Name, title, company and a public profile URL are usually enough. Never construct email addresses or phone numbers from patterns, and do not collect home addresses, personal social accounts or sensitive data.
  • Respect opt-outs: if the user's own tools mark a person or company as do-not-contact, that wins over anything found on the web.
  • Report a vendor's or analyst's claims (market share, "leader in") as attributed claims, not facts.

Answer format

Lead with the answer, then the evidence:

Answer: Datadog's Chief Revenue Officer is , in the role since . Source: Datadog leadership page, https://..., read 2026-11-12; appointment release, https://..., published . Checked, nothing found: Datadog newsroom and press wires from to today; no later change.

Keep numbers with their units and dates, include every URL, and say how fresh each source is.

See references/source-map.md for the full map of GTM research questions to sources and how fast each goes stale.

Account lists and CRM enrichment with Nimble

Two jobs fill most of a pipeline: find the accounts that match an ideal customer profile (ICP), and fill the fields a rep needs on accounts you already have. Nimble does both two ways:

Web Search Agent (Agent API)Search API pipeline
Who owns the workflowNimble: you give the objective, the rules and the output shape; the agent plans searches, navigates newsrooms, careers boards and registries, cross-checks and returns JSON with per-claim confidenceYour code: you choose each query, its sources and depth, run an LLM step over the results and apply your own rules
Best forMost lists and enrichment: fastest to good results, finds evidence on pages a fixed query list missesVery large or very cheap runs, strict control of every source, or when results must be reproducible query by query
Typical timeEnrichment about 3 to 5 minutes per batch; an ICP list about 7 to 8 minutes per run (both at high)Seconds per search; you pay for your own LLM step

They find different things. In Nimble's GTM guide, the agent found a company through a Gem-hosted careers board the Search pipeline's fixed ATS list missed, and the Search pipeline found another company's sales roles on Ashby and Lever that the agent did not verify. For a list that matters, run the agent and a short Search sweep, then merge and verify.

1. Get the agents into the account

These skills use six agents. Check in this order: an agent with the same agent_name already in the account (nimble_agents_list) → the Nimble gallery (nimble_agent_templates_list, then nimble_agents_create(template=<name>, agent_name=<name>)) → the bundled spec.

AgentJobGallery templateBundled spec
gtm-icp-discoveryICP list where every hard criterion is verified on a cited page, plus near-missesyesaccount-deep-research/agents/gtm-icp-discovery.json
account-discoveryQuick ICP list from a description, each with why it fits and a sourceyesaccount-deep-research/agents/account-discovery.json
business-discoveryLocal businesses by category and place, with address, phone, website, rating, review countyesaccount-deep-research/agents/business-discovery.json
gtm-account-enrichmentCRM-shaped profile from a domain, with conflicts between sources keptyesaccount-deep-research/agents/gtm-account-enrichment.json
account-enrichmentFirmographics on one domain: legal name, HQ, industry, ownership, headcount, funding, leaders, tech stackyesaccount-deep-research/agents/account-enrichment.json
decision-maker-identificationWho holds named roles at an account nowyesaccount-deep-research/agents/decision-maker-identification.json

The bundled specs ship in the account-deep-research skill of this repo. If only this skill is installed, read them from https://raw.githubusercontent.com/Nimbleway/agent-skills/main/skills/account-deep-research/agents/<agent_name>.json. All six are in the Go-to-market section of the Nimble gallery, so nimble_agents_create(template=<name>, agent_name=<name>) works for each; use the bundled spec only if the gallery does not list one. Create each agent once and reuse it; never one agent per account.

People at those accounts. Once the account list is final, people-research finds the contacts: people-discovery for people who match a role and seniority across the list, buying-committee-map for the committee at one target account, and contact-job-change-monitor to keep the contact list current.

2. Build a list

Frame the ICP as hard criteria before running anything. Write down with the user:

  1. Firmographics: HQ country or region, category in plain words ("builds AI software sold to law firms or in-house legal teams, not a law firm itself"), headcount range, ownership.
  2. Stage and timing: latest priced round and the date it must be after, or "public", or "PE-backed".
  3. A live signal: hiring for a function (a quota-carrying sales role in the US), a technology they use, a recent launch, an event they sponsor.
  4. Count and exclusions: how many, and the domains already in the CRM or already customers (pass them in so they are not returned).

Then run gtm-icp-discovery with the criteria as a bulleted list and "Treat every criterion as a hard constraint. List near-misses with the criterion they failed." Use its suggested question as the template. Ask for 15 to 50 rows per run; for a bigger TAM, split by region, sub-category or funding stage and run each scope separately (one run over a whole market truncates). Pass domains already found as input_data with "exclude the domains in input_data" so top-up runs find new ones.

Check the list before you show it:

  • Every row in companies has a live sales_role_url (or the user's signal), a dated headcount source and evidence_urls for each criterion. A row that misses one is a near-miss, not a match.
  • Headcount gate. Headcount is the field agents infer most. For each row, run one nimble_search ("<company> <domain> employees headcount", search_depth: "lite", max_results: 5) and drop rows whose only figure is older than a year or outside the range.
  • Domains resolve to the named company (open one or two).
  • Near-misses are useful: show them with the failed criterion ("HQ is Toronto, not the US"). They are often next quarter's accounts.
  • No padding. If fewer companies qualify than asked, the shorter list is the right answer.

Local and SMB lists (dentists in Austin, HVAC contractors in three counties): run business-discovery per city or county and category, at least 10 rows per run. For thousands of listings or a refresh every month, use the google_maps_search Extract Template in gtm-data-at-scale instead; it returns stable fields per listing and runs as a batch or a scheduled Job.

3. Enrich a list

Send the rows you have in input_data, with the fields to fill set to null. Your values pass through untouched (pre_existing in the trust block); only the blanks are researched.

Pick the shape. gtm-account-enrichment and account-enrichment return one profile per run (an object schema): send one record per run and run several in parallel. To fill a few columns across many rows in one run, create a custom enrichment agent with an array-root schema (one output row per input row, input values carried through) as in section 5 of account-deep-research.

Batch size is the lever for array-root agents. At high, about 5 rows with 6 researched fields per run; 10 rows with 2 or 3 fields; 1 to 3 rows at x-high for hard fields (financials of private companies, named executives). The hard cap is 20 rows and 200 input cells, but a 10-row, 6-field batch at high once ran 21 minutes and researched only half its rows.

curl -s -X POST https://sdk.nimbleway.com/v2/agents/runs \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_name": "gtm-account-enrichment",
    "input": "Enrich this CRM account into a current company profile. Resolve it from its domain (eve.legal), not its name.",
    "input_data": {"company_name": "Eve", "domain": "eve.legal", "headquarters": null,
                   "employee_count": null, "last_round": null, "leadership": null, "currently_hiring": null}
  }'

Then poll GET /v2/agents/{agent_id}/runs/{run_id} while is_active and read GET .../runs/{run_id}/result (MCP: nimble_agents_run → nimble_agents_run_status). For more than a few batches, write a small loop rather than calling tools one by one:

  • Concurrency about 10 runs at a time (account defaults: 30 concurrent agents, 200 runs a day; ask Nimble to raise them for a large backfill).
  • A ledger keyed on the user's identifier (domain or CRM ID), not on run IDs: which rows came back, which did not. Resubmit missing rows once in a new batch.
  • A stuck threshold: a run still active after 30 minutes is resubmitted once, not looped.
  • Dedupe after every merge on the domain.
  • Write results to a file (CSV or JSONL), not into the chat. Show the user a sample and the fill rate per field.

For people, run decision-maker-identification per account with the exact roles ("current CRO, head of RevOps, VP Marketing") after the account list is final. Titles differ by company size; the agent maps "Head of", "VP" and "Director" to the same scope and reports missing_roles. Never generate emails or phone numbers from patterns; if the user needs contact data, that comes from their licensed contact provider, matched on name, company and LinkedIn URL.

4. Write back to the CRM safely

Most damage happens at write-back, not research. Agree on these rules with the user before touching Salesforce or HubSpot, and keep the raw results file:

  • Never overwrite a value a person entered unless the user says so. Fill blanks; send conflicts to a review queue.
  • Gate on confidence. Run with trust_mode: "full_trust" (MCP) or read the trust.claims block: write high confidence fields automatically, queue medium, drop low and null.
  • Store the source and date with the value (a source_url and as_of field, or a note) so reps can see why a field says what it says.
  • Precedence when sources disagree. For fast-moving fields (headcount, customer count, open roles, titles) the most recent dated value wins. For everything else the most trusted tier wins: the company's own site and ATS boards → press releases and reputable press → everything else → aggregators (Crunchbase, PitchBook, Tracxn). gtm-account-enrichment returns data_conflicts with every value found; show them rather than silently picking one.
  • Match on domain, not company name, and normalize to the bare hostname before matching.
  • Dry run first: write 10 records, have the user check them in the CRM, then the rest.

Enrichment goes stale. Re-run headcount, leadership and hiring every quarter, and buying signals weekly (gtm-buying-trigger-monitor in account-deep-research).

5. The Search API pipeline (when your code owns the workflow)

Use this when the user wants full control, a very large list, or no agent runs. The pattern from Nimble's GTM guide:

Enrichment, one account: one focused search pass per attribute group, each with its own sources and depth, then an LLM step that fills a fixed profile and keeps every conflicting value with its source and date, then code-side precedence rules.

PassParameters
Identity and productsinclude_domains: [<domain>], search_depth: "standard", max_results: 5
Funding and investorssearch_depth: "standard", max_results: 6
Leadership, HQ, headcountsearch_depth: "standard", max_results: 5
Hiringinclude_domains: ["job-boards.greenhouse.io","jobs.ashbyhq.com","jobs.lever.co", <domain>], search_depth: "lite", max_results: 20
Recent newstime_range: "year", search_depth: "lite", max_results: 8

List building: broaden, then narrow. Five or six lite discovery queries from different angles (funding stage, buyer type, trade press via include_domains, investor portfolios) with start_date set to the funding window and max_results: 10; dedupe candidates; one lite firmographic search per candidate (5 results); a hiring search on ATS boards plus the company's own domain only for candidates that pass; an LLM judges each criterion from the evidence, and code makes the pass/fail decision and records the failed criterion.

Buying triggers for a watchlist: three focus: "news", search_depth: "lite", max_results: 8 queries per account (funding and acquisitions; executive hires; launches, expansions and partnerships) with start_date at the window start; an LLM step dates each event by when it happened, types and grades it; code keeps events inside the window, merges duplicate coverage and picks the strongest trigger per account.

Full runnable versions of all three (Search pipeline and agent, with post-processing that guarantees the output shape) are in Nimbleway/cookbook under apps/gtm-account-enrichment-agent, apps/gtm-account-discovery-agent and apps/gtm-buying-trigger-agent.

6. Rules that apply to every list

  • Public information only. No logged-in, paywalled or purchased data. No emails or phone numbers constructed from patterns; personal data limited to name, title, company and a public profile URL unless the task needs more.
  • Respect the user's suppression lists: existing customers, open opportunities, do-not-contact flags and regional privacy rules (GDPR, CASL) decide who goes into an outbound sequence, not the web data.
  • Every value has a source and a date; a value nobody published is null.
  • No padding: fewer verified rows beat a list filled to the requested count.
  • Lists are a snapshot. Say the date the list was built, and re-verify hiring and headcount before a campaign that starts weeks later.

Account signals

Lists what changed at an account since a date: funding, exec moves, launches, pricing changes and hiring pushes, each dated and cited.

What the user gets

Only events dated after the since date, each with date, type, headline, summary and source. If nothing changed, an empty list and the sources it checked.

Agent template

This skill runs the Nimble gallery template account-signals. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
AccountyesName and domain-
SincenoA date in YYYY-MM-DDlast 30 days
Signal typesnoFor example "only exec hires and funding"all signal types
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your account monitoring assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Check <Company> (<domain>) for changes since <YYYY-MM-DD>

Example: Check Mercury (mercury.com) for changes since 2026-09-21

  • One account at a time. If the user names several, run the first and offer the rest next.
  • Always pass an explicit date in YYYY-MM-DD form. A skipped Since means the date 30 days before today. Take today's date from the host or by running date, and if you have neither, ask the user for the date.
  • If they only care about some signal types, add one line to the input.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="account-signals", agent_name="account-signals"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="account-signals", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="account-signals", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Check another account. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as account-signals: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Events on the since date itself can slip in. Keep only events strictly after it.
  • For repeat checks, keep the sources you already showed and drop them next time.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Alternative data at scale with Nimble Extract Templates

An Extract Template is a maintained scraper for one page type on one site (an Amazon product page, a Walmart search page, a Google Maps reviews page, an Indeed search). You pass parameters (an ASIN, a keyword, a place ID, a zip code) and get the same JSON fields every time. That consistency is what turns web pages into a panel a fund can trade on.

ScaleModeEndpoint
1 to a few inputs, need it nowRealtime runPOST /v2/extract/templates/run (MCP nimble_extract_templates_run)
One input, deliver laterAsyncPOST /v2/extract/templates/async (MCP nimble_extract_templates_run_async)
Up to 1,000 inputs at onceBatchPOST /v2/extract/templates/batch
Thousands to millions of inputs, on a scheduleExtract JobPOST /v2/jobs or online.nimbleway.com/jobs
A site with no templateTemplate generationPOST /v2/extract/templates/generations

Base URL https://sdk.nimbleway.com, header Authorization: Bearer $NIMBLE_API_KEY (never print the key). For large pulls prefer the CLI, SDKs or REST over MCP, so results go to files, not the context window.

1. Frame the dataset like an analyst

Before running anything, write down with the user:

  1. The question and the ticker(s). For example: "Is Celsius losing shelf share to Alani Nu at Walmart and Target?" or "Are Chipotle's delivery menu prices rising slower than peers'?"
  2. The universe. The exact SKUs, stores, place IDs, keywords or company names, each mapped to a brand, company and ticker. A fixed universe is a panel; a moving one is noise.
  3. The metrics: average and median price, discount depth and frequency, in-stock rate, rank or position, review count velocity, average rating and its trend, postings count by function and location, new store count.
  4. Geography and cadence. Which zip codes or stores (prices and stock vary by location) and how often (daily for prices, weekly for reviews and postings).
  5. History. Web data mostly starts the day you begin collecting. Start early; use web.archive.org snapshots or review timestamps for partial backfill, and say clearly what is backfilled. A baseline is the same page, product, place and unit on the earlier date. Never invent or approximate one to fill a gap; with too few, the answer is "insufficient evidence". A year-over-year figure is not a comparison with your since date.

Pilot on 20 to 50 inputs, check the fields, then scale.

2. Find the template

  1. List: nimble_extract_templates_list(query="walmart") or GET /v2/extract/templates?limit=200&offset=0 (paginate through about 850). Each item has name, managed_by (nimble or community), and metadata (vertical, entity type, description).
  2. Inspect: nimble_extract_templates_get(template_name=...) or GET /v2/extract/templates/{name}. Read published_version.input_schema (required params and their exact names), output_schema (the fields you will get) and samples.
  3. Prefer managed_by: "nimble" templates: Nimble maintains them around the clock and they auto-heal when sites change. Community templates work but vary; check a sample run before building on one.
  4. Param names differ between templates: walmart_pdp takes product_id and zipcode; amazon_pdp takes asin and zip_code; google_maps_reviews takes place_id, sort, num_results; indeed_serp takes keyword and location. Always copy names from the input_schema.

references/template-catalog.md lists the alt-data templates in the catalog as of 2026-11-11, grouped by signal. Typical starting points:

SignalTemplates to start with
Prices, promotions, availabilityamazon_pdp, walmart_pdp, best_buy_pdp, target_serp, homedepot_serp, lowes_pdp, kroger_serp, sams_club_pdp, heb_pdp, aldi_pdp, tesco_pdp, zara_*, hm_pdp
Rank and share of shelfamazon_serp, amazon_best_sellers, amazon_plp, walmart_serp, walmart_clp, target_serp, bestbuy_serp
Reviews and ratingsgoogle_maps_reviews, Amazon review templates by marketplace, bestbuy_com_product_reviews_*, glassdoor_company_reviews_*, g2_product_profile_*, bbb_org_customer_reviews_*, booking_com_property_reviews_*, doordash_store_reviews_*
Hiringindeed_serp, linkedin_job_search_*, dice_com_company_jobs_*
Footprintgoogle_maps_search, store locator templates
Restaurants and deliverydoordash_pdp, uber_eats_pdp, doordash_restaurant_menu_*
Travel and live eventsbooking_com_*, airbnb_*, expedia_hotel_search_*, stubhub_event_get_page, ticketmaster_offers_details, vividseats_json
Housingzillow_plp, zillow_pdp, zillow_serp_region
Social and creatorstiktok_account, tiktok_shop_pdp, youtube_channel, instagram_profile_by_account, facebook_page
Brand visibility in AI answerschatgpt, perplexity, gemini, google_ai
Clinical and regulatoryclinicaltrials_gov_*, fda_recall_alerts_*, fda_510k_device_search_*

Search can also run templates: nimble_search with focus set to up to 10 template names (for example ["amazon_serp","walmart_serp","target_serp"]) fans one keyword across retailers for a quick cross-retailer snapshot.

3. Run it

Realtime (pilot and spot checks)

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/run \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{"template": "walmart_pdp", "params": {"product_id": "<walmart_item_id>", "zipcode": "10001"}}' \
  | jq '.data.parsing'

Structured fields are in data.parsing. Add "formats": ["markdown"] or ["html"] only when you need the raw page too (for audit). Every template also accepts the shared params country, locale, tag and parse inside params. Set "localization": true when passing a zip code or store ID to templates that support local pricing.

Batch (up to 1,000 inputs per request)

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/batch \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "shared_inputs": {"template": "amazon_pdp", "params": {"zip_code": "10001"}},
    "inputs": [ {"params": {"asin": "B0DLKFK6LR"}}, {"params": {"asin": "B08N5WRWNW"}} ]
  }'
  • shared_inputs.template is required and applies to every item; per-item params merge over shared_inputs.params (per-item wins). localization and formats can be set shared or per item.
  • Delivery options go in shared_inputs.params: storage_type (s3 or gs), storage_url, storage_compress, callback_url.
  • Poll GET /v2/batches/{batch_id}/progress until completed: true, then GET /v2/batches/{batch_id} for each task's state and download_url, and fetch each success task's download_url (or GET /v2/tasks/{task_id}/results). The progress counter can trail the task states, so also read task states from GET /v2/batches/{batch_id} and collect finished tasks as they land; retry error tasks once in a new batch.
  • Put a tag in params (for example celh_panel_2026-11-11) so rows can be traced to a collection run.

Async (single input, delivered): POST /v2/extract/templates/async with template, params, and optional storage_type, storage_url, storage_object_name, storage_compress or callback_url. Poll GET /v2/tasks/{task_id} until state is success, then GET /v2/tasks/{task_id}/results. Results land as {task_id}.json (or your object name) in the bucket. The callback carries task metadata only, not data.

Extract Jobs (recurring panels): the right tool once the pilot works. A job binds one template to an input set, a schedule and a destination, then fans out one run per input row with retries and concurrency handled by Nimble.

curl -s -X POST https://sdk.nimbleway.com/v2/jobs \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "daily-energy-drink-shelf-walmart",
    "extract_template_name": "walmart_pdp",
    "schedule": {"cron": "0 7 * * *", "enabled": true},
    "inputs": {"type": "inline", "data": [{"product_id": "<walmart_item_id>", "zipcode": "10001"}]},
    "destination": {"type": "s3", "path": "s3://alt-data/energy-drinks/walmart/", "format": "parquet"}
  }'
  • Inputs: inline JSON, an uploaded CSV or Parquet whose column names match the template params, an S3 file or folder (latest file is used), or a Databricks table via Delta Sharing. Rows may include country, locale and tag.
  • Destinations: download from Nimble, S3, or Databricks (Delta Sharing, 14-day retention: materialize into your own table). Formats JSON, CSV or Parquet. Turn on include input so each output row carries its input keys for joins.
  • Schedule: cron in UTC, or Day / Week / Month presets; manual triggers (POST /v2/jobs/{job_id}/runs) add runs without changing the schedule.
  • Monitor: GET /v2/jobs/runs/{run_id} for status; artifacts hold the input set, valid rows and invalid rows, with success rate and error samples per run. Edits take effect on the next run. One job runs one template; use one job per retailer or site.

4. When no template exists: generate one

Use generation only when the catalog has nothing for the site and the data will be pulled repeatedly. For a one-off, use Extract or a Web Search Agent instead.

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/generations \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example-retailer.com/p/energy-drink-12pk/12345",
    "prompt": "Product detail page. Extract product name, brand, size, list price, sale price, promo text, in-stock status, rating, review count. Prices as numbers in USD.",
    "name": "example_retailer_pdp",
    "output_schema": {"type": "object", "properties": {"product_name": {"type": "string"}, "price": {"type": "number"}}}
  }'
  • Required: url (a representative example page) and prompt. Optional: name (lowercase, digits and underscores), input_schema, output_schema, metadata.
  • Poll GET /v2/extract/templates/generations/{generation_id} until status is terminal. On success it reports generated_version with its input_schema, output_schema and samples. Check the samples on two or three other pages of the same type before trusting it.
  • Refine with POST /v2/extract/templates/generations and {"from_extract_template": "<name>", "prompt": "Also capture unit price; price was missing on sale items"}.
  • Manage: GET /v2/extract/templates/{name}/versions and /versions/{version_id} to compare versions, PATCH /v2/extract/templates/{name} (JSON Patch: [{"op": "replace", "path": "...", "value": ...}]), DELETE /v2/extract/templates/{name}.
  • MCP equivalents: nimble_extract_templates_generate, nimble_extract_templates_generation_status, nimble_extract_templates_update_from_template. Only generate when the user asked for a reusable template.

5. Make the data research-grade

  • Keys and timestamps. Store every row with input key, template name and version, collection timestamp (UTC), zip or store, and tag. Keep raw JSON next to the cleaned table so fields can be re-derived.
  • Same panel every run. Changes to the universe, zip codes or templates break time series. Version the input list and log every change.
  • Company statements are not observations. Promotions or prices the company announced (releases, earnings calls) are what the company said; measure them on the live page before counting them.
  • Missing is not zero. A failed or empty fetch is a gap, not "out of stock" or "price 0". Track success rate per run and per site; alert when it drops.
  • Normalize: currency, unit price (per oz, per count), pack size, sale versus list price, sponsored versus organic rank.
  • Entity mapping. Map product to brand to company to ticker, and keep the map under version control. Private-label and licensed brands are common traps.
  • Sanity checks: day-over-day jumps, duplicate rows, template field drift after a site redesign (Nimble-managed templates heal, but check the fields you depend on).
  • Survivorship. Keep discontinued SKUs and closed stores in the panel with their status rather than dropping them.
  • Review data: dedupe on review ID, use the review timestamp rather than the collection date, and drop reviewer names and profile links that the analysis does not need.

6. Compliance

  • Collect public pages only: no logins, created accounts, paywalls or CAPTCHA bypassing. Logged-out collection of public pages is the position courts have treated most favorably; logged-in collection that breaches terms is not.
  • Minimize personal data (reviewer and job-poster identities); anonymize or drop it.
  • Document lineage for the compliance team: the sites, the templates, the cadence, what is and is not collected, and that no MNPI is involved. Regulators have asked advisers to show this diligence for alternative data.
  • Keep request volume proportionate; Jobs and batches handle pacing, so do not hand-roll parallel floods on top of them.

Brand Mention Monitor

Scans the web and social media for brand mentions, scores each one on reach, velocity, sentiment, and risk-topic match, and surfaces the ones that need attention — bucketed into Crisis / Watch / Engage / Log with a suggested owner.


Onboarding message

When this skill is triggered for the first time in a session, send this message:

👋 Brand Mention Monitor is ready.

This skill scans Reddit, X, LinkedIn, Instagram, TikTok, YouTube, blogs, news, and review platforms for mentions of your brand — scoring each one across reach, velocity, sentiment, and risk so you see what matters before it spirals, and telling you exactly who should respond and how fast.

To start, just say: "Monitor mentions of [brand name]"

Or try:

  • "What are people saying about [brand] this week?"
  • "Run a brand sweep for [brand] — last 30 days"
  • "Find high-risk mentions of [brand]"
  • "How does [brand] compare to [competitor] in the conversation?"

Would you like me to save your preferences so I skip the questions next time?


Preflight

Follow the transport selection and standard preflight from references/nimble-playbook.md: pick CLI vs MCP at session start, then run the parallel preflight calls (date, profile, memory index) simultaneously. Tag every Nimble CLI call: nimble --client-source nimble-agent-skills <subcommand>.

From the profile (~/.nimble/business-profile.json): load brand name, competitors, routing preferences, and last_runs.brand-mention-monitor for date windowing. Pre-populate setup questions so the user confirms rather than re-enters. If no profile exists, follow the first-run onboarding flow in references/profile-and-onboarding.md and create a stub after the first run. Check ~/.nimble/memory/index.md to understand what mention data already exists before sweeping.


How to start

Before asking anything, do two quick research steps:

Step A — Resolve brand variants automatically: Search for the brand the user named to discover all alternate spellings, hashtags, product names, handles, and common misspellings. Do not ask the user for this. Use what you find to build a comprehensive search term list for the sweep.

  • Search: "[brand name]" official name OR handle OR "also known as" OR hashtag
  • Check the brand's main product names and any sub-brands that get mentioned independently
  • For brands with common-word names, find the disambiguating terms (industry, founder, domain) so the sweep doesn't pull unrelated noise
  • Add all confirmed variants to your search queries silently — the user never needs to see this step

Step B — Profile the brand automatically: Search to establish the brand's industry, business model (B2B/B2C), geography, language, and audience before asking the user. This selects the market-specific source profile (see Step 0) and calibrates scoring — what counts as "high reach" differs for a niche B2B tool vs a consumer app with millions of users. Surface what you find and fold it into the confirmation question rather than asking blind.

  • Search: "[brand name]" company OR product industry OR category
  • Determine: B2B vs B2C, industry vertical, primary geography/language, rough audience size
  • Use this to pick the source profile and the default risk-topic dictionary for the industry

Then ask in a single message:

"Before I run — just confirming a few things:

  1. Brand: I found [brand] — a [category] [B2B/B2C] company targeting [audience]. Is that right, and any competitors to track alongside it?
  2. Date range: How far back should I look? (default: last 7 days — or give me a window like 'June 1–15' or 'since the launch')
  3. Depth: Quick scan (faster) or deep sweep (more thorough, more sources)? (default: deep)
  4. Routing: When I find a Crisis-tier mention, who should I flag it for? (default: marketing team — or name a PR lead, legal, founder, etc.)"

Output is always the triage console rendered directly in Claude. Do not ask about format or output options.

Exceptions — skip asking entirely if:

  • The user provided all the above in their initial message
  • The user has run this skill before in the session (use prior config)

Defaults if user says "just run it":

  • Date range: last 7 days
  • Depth: deep
  • Risk topics: auto-detected for the industry
  • Routing: flag to marketing team

Disambiguation: If the brand name is ambiguous after research, confirm before proceeding:

"Just to confirm — by [brand], do you mean [Option A] or [Option B]?"


Step 0 — Source profile (market-specific, not fixed list)

This is the most important configuration step. Source selection must match where the brand's audience actually talks. Do not scan all platforms equally — weight the channels that matter for this company type.

B2B enterprise software / SaaS

Primary (run every pass): LinkedIn, G2, Capterra, Hacker News, r/sysadmin, r/devops, r/[category], trade press (InfoQ, TechCrunch, ZDNet, The Register), Glassdoor (employee signal) Secondary: Reddit broad, X/Twitter (exec accounts, analysts), Medium/Substack Deprioritize: TikTok, Instagram, Facebook (low-signal for B2B buyers)

Consumer brand / e-commerce

Primary (run every pass): TikTok, Instagram, X/Twitter, Reddit, YouTube, Facebook, Trustpilot, Google Play / App Store Secondary: News press, blogs, Pinterest Deprioritize: HN, LinkedIn (low signal for consumer sentiment), trade press

Regulated industry (finance, healthcare, pharma, insurance)

Primary: News press (Reuters, AP, Bloomberg, sector-specific), regulatory watchdog sites, journalist Twitter accounts, LinkedIn exec commentary, formal review platforms (BBB, Consumer Financial Protection Bureau) Secondary: Reddit, X, forums Deprioritize: TikTok, Instagram (reputational risk from user-gen content is lower priority than press/regulatory)

Regional / non-English brand

Primary: Local-language news, regional forums and social platforms (e.g. Weibo for China, VK for Russia, Naver for Korea), local-language Twitter/Instagram Secondary: English-language global platforms only if relevant Note: Use Nimble locale and country parameters to surface local-language results

Startup / developer tool

Primary: HN, Reddit (r/programming, r/webdev, r/[category]), GitHub discussions, Dev.to, X/Twitter (developer influencers), ProductHunt Secondary: LinkedIn, Medium, TechCrunch


Step 1 — Mention sweep

For deep sweeps, fan out across source tiers using parallel sub-agents (max 4 concurrent) via the Agent tool — one agent per source group (e.g., social, review platforms, news, community). Follow the parallel-gathering pattern in references/nimble-playbook.md. Always include a fallback: if a sub-agent fails, continue with remaining agents and note the gap in the output.

Run sources matching the brand's profile (Step 0). Use --search-depth lite for discovery; use --search-depth deep for full content on high-score candidates. Apply --start-date / --end-date from the user's date range on every search call. Tag every call: nimble --client-source nimble-agent-skills search ...

Core queries (run for every brand type)

  • "[brand name]" site:reddit.com
  • "[brand name]" site:x.com
  • "[brand name]" news
  • "[brand name]" review OR complaint OR "doesn't work" — risk sweep
  • "[brand name]" love OR recommend OR "game changer" — opportunity sweep
  • Nimble focus:"social" query "[brand name]" — broad social

Risk-specific queries (run every pass)

Build from the risk topic dictionary for this brand type plus any user-specified topics:

  • "[brand name]" [risk topic 1]
  • "[brand name]" [risk topic 2]
  • "[brand name]" lawsuit OR legal OR "class action"
  • "[brand name]" outage OR "not working" OR down (for SaaS/tech)
  • "[brand name]" recall OR safety OR "side effects" (for consumer/pharma)
  • "[brand name]" scam OR fraud OR fake

Velocity check (run on high-score candidates — re-runs only)

For any mention that scored above 50 on a previous run, re-fetch the post to compare engagement counts. If this is a first-pass sweep with no prior baseline, skip hourly-rate velocity scoring — proxy signals only (see Step 2 velocity gating rules).


Step 2 — Scoring each mention (four dimensions)

Score every mention 0–100 on each dimension, then compute composite.

Reach / Visibility (0–100)

How many people can see this?

SignalPoints
500K+ followers / major publication+35
100K–500K followers+25
10K–100K followers+15
1K–10K followers+8
Under 1K+3
Thread with 100+ replies/comments+20
Post going viral (100+ reposts in <1h)+25
High-authority domain (TechCrunch, Reuters, etc.)+25
Reddit front page / 1K+ upvotes+25

Velocity (0–100) — the differentiator

How fast is this gaining ground? This is what separates "viral forming" from "stale."

Baseline requirement: Hourly-rate rows (+40/+25/+10) require two data points — a prior engagement count and the current count — to compute a real rate. On a first-pass single sweep you do not have a baseline. Apply the following rules:

  • Re-run with prior data (baseline available): use the full table below.
  • First-pass single sweep (no baseline): skip hourly-rate rows; score only observable proxy signals (cross-platform pickup, press pickup, absolute engagement thresholds). Set velocity label to ~estimated on the card so the user knows it is inferred, not measured.
SignalPointsRequires baseline?
Engagement climbing 50%+/hour vs. baseline+40Yes
Engagement climbing 20–50%/hour+25Yes
Engagement climbing 5–20%/hour+10Yes
Flat engagement+0Yes
Cross-platform pickup (mention appearing on 2+ platforms)+20No
Press picking up a social post+25No
2.3K+ reposts in 40 minutes (crisis velocity)+40No — observable in single sweep

Tier upgrade on rapid re-check: if re-running within 2 hours of a previous run, re-fetch every mention that scored Watch or higher and compare engagement counts. If engagement has grown 20%+ since last check, upgrade the tier and flag it ↑ accelerating. If flat or declining, note → stable or ↓ declining.

Sentiment (0–100 risk score; 0–100 opportunity score)

Negative signals (risk)Points
Explicit negative sentiment+20
Complaint + product/service failure language+20
Sarcasm detected ("great job [brand]…")+15
All-caps, exclamation marks, profanity+10
Replies amplifying the negative tone+15
Positive signals (opportunity)Points
Organic praise, unprompted+20
Purchase intent or recommendation+20
User-generated content shareable by brand+15
Journalist / analyst positive mention+20

Risk topic match (0–100)

Does this hit a flagged risk category?

Topic categoryPoints
Legal / regulatory / lawsuit / class action+40
Safety / health / injury / recall+40
Executive misconduct or controversy+35
Product outage or critical failure+30
Pricing / billing complaint (if viral)+20
Competitor comparison framing brand negatively+15
False claim / misinformation about brand+25

Composite score

composite = (reach × 0.30) + (velocity × 0.30) + (max(risk_sentiment, risk_topic) × 0.25) + (opportunity × 0.15)


Step 2.5 — Memory dedup (filter already-known mentions)

Before assigning tiers, run the dedup lifecycle from references/memory-and-distribution.md against prior brand-mention-monitor reports in ~/.nimble/memory/reports/.

Skill-specific rules:

  • Fingerprint: {url, platform, published_date} — normalize URLs (strip query params, trailing slashes).
  • Returning with score shift ≥10: keep in feed, mark with ↩ returning · score changed badge.
  • Already known, score unchanged: move to Log tier; suppress from Crisis/Watch/Engage unless user requested full history.
  • Summary line: show at top of triage console: X net-new · Y returning (score changed) · Z suppressed (already logged).
  • Persist: after the run, save mention fingerprints to ~/.nimble/memory/reports/brand-mention-monitor-{BRAND}-{YYYY-MM-DD}.md and append a log.md entry per references/memory-and-distribution.md.

Step 3 — Tier assignment and routing

Assign every mention to exactly one tier. Teams act on tiers, not numbers.

TierScoreColorActionSuggested ownerWindow
Crisis80–100🔴Route immediatelyPR + Legal + LeadershipRespond <2h
Watch50–79🟠Assign owner, monitor velocityMarketing / CommsRespond <24h
EngageAny score, positive high-reach🟢Amplify / thank / shareMarketing / Social teamAct within 48h
Log<50, no risk signals⚪No action, searchable record——

Crisis-tier mentions must surface immediately — they should appear at the very top of the output with a full decision card showing: excerpt, reach, velocity, reason for flagging, suggested owner, response window, and suggested draft action.


Output template (REQUIRED)

Claude MUST follow references/template.html exactly. Load the template, substitute real data, keep all CSS, JS, and interaction patterns identical.

Response structure (wrap the widget)

The chat response must follow the standard contract: open with a TL;DR and close with a What This Means section, with the triage console in between.

  1. TL;DR (first, 2–4 lines): total mentions, the tier breakdown (X Crisis · Y Watch · Z Engage), and the single most urgent item with its response window.
  2. The triage console — the interactive widget, rendered inline per the rules below.
  3. What This Means (final top-level section): what the sweep signals for the brand right now and the top 1–3 recommended actions, each tied to a tier and owner.

Rendering — INLINE FIRST, ALWAYS (read this before producing output)

The triage console is an interactive widget that must be rendered inline in the chat. A downloadable file is a secondary artifact, never the primary deliverable. Follow this sequence exactly, every run:

  1. Render the triage console inline FIRST. Write the fully-populated brand-mention-monitor-{YYYY-MM-DD}.html to ~/.nimble/ using the Write tool, then emit the HTML content inline in the conversation so the user sees the interactive widget immediately. This inline output is the main deliverable and must happen before anything else is offered.
  2. Then, and only then, offer downloads. After the inline output is on screen, confirm that ~/.nimble/brand-mention-monitor-{YYYY-MM-DD}.html and ~/.nimble/brand-mention-monitor-{YYYY-MM-DD}.md have been saved and offer them to the user for download or sharing.

Hard rules:

  • Never respond with only a file path. If the user sees a path but no inline triage console, the run has failed its primary job.
  • Do not ask the user whether they want it inline or as a file, and do not ask about format — inline is always the default and the file always accompanies it.
  • The inline output and the saved HTML are the same artifact — render the identical template, do not produce a stripped-down inline version.

If the inline output genuinely cannot be produced:

  1. Say so explicitly in one short line — e.g. "I couldn't render the triage console inline this time, so here's the file instead."
  2. Confirm the file has been saved to ~/.nimble/brand-mention-monitor-{YYYY-MM-DD}.html as the fallback.

Never silently fall back to a file — if inline fails, name the failure so the user knows it was the environment, not the intended behavior.

Output template spec (brand-mention-monitor-{YYYY-MM-DD}.html)

Visual identity — distinct from all other skills:

  • Triage console aesthetic — dense, action-oriented, not a report
  • Crisis-tier mentions get a full-width alert card at the top before the feed
  • Four score pips per card: Reach / Velocity / Sentiment / Risk — not just one urgency signal
  • Tier badge replaces composite number as the primary visual label
  • Sources searched panel (collapsible) showing exactly what was queried this run
  • Date range picker (custom From/To date inputs) that re-filters the feed client-side
  • Platform filter + Tier filter stacked
  • Velocity indicator on each card: ↑ accelerating / → stable / ↓ declining

Score pip colors:

  • Reach: #185FA5 (blue)
  • Velocity: #854F0B (amber — urgency signal)
  • Sentiment: #A32D2D (red for risk) / #3B6D11 (green for opportunity)
  • Risk topic: #A32D2D (red)

Tier colors:

  • Crisis 🔴: red left border + red tier badge
  • Watch 🟠: amber left border + amber tier badge
  • Engage 🟢: green left border + green tier badge
  • Log ⚪: gray border

Required sections (in this render order):

  1. Brand header bar — brand name · date range (from onboarding, read-only label e.g. "Window: Jun 11–18, 2026") · total mentions
  2. Sources searched — collapsible panel showing every source queried this run with ✓ marks + mention-count badges; click a source to filter the feed by platform
  3. Score summary row — four aggregate meters: avg Reach / top Velocity / top Sentiment risk / top Opportunity
  4. Market visibility (share of voice) — donut chart (white center) + legend showing the brand's share of conversations vs competitors in this window. Hovering a segment or legend row highlights it and shows that brand's share in the donut center. CLICKING a segment or row opens a detail panel with critical intelligence for that brand: mention count, trend vs last window (color-coded red rising / green falling), estimated reach, a positive/neutral/negative sentiment split bar, and a one-line Signal takeaway explaining what's driving that brand's share. Use mvBrands[]: first entry is the user's brand; each entry is {name, pct, fill, stroke, mentions, trend, reach, pos, neu, neg, signal}. Percentages sum to ~100 (include an "Other" bucket); pos+neu+neg sum to 100.
  5. Crisis alert cards — full-width, only shown if tier = Crisis; includes excerpt, all 4 scores, published date, reason, owner, window, suggested action
  6. Mentions by platform — horizontal bars, clickable to filter feed (synced with sources panel)
  7. Geographic breakdown — interactive world map with mention hotspots. Use geoPoints[]: each point {name, lat, lng, tier, sources} where tier is 'high'/'med'/'low' (drives dot color red/amber/blue, size, pulse ring on high-tier). Mention count is derived from the length of sources. Each entry in sources is {head, plat, meta, url, tier} — head = headline, plat = platform key, meta = followers/upvotes and date, tier = that mention's own tier, and url MUST be the EXACT Nimble result URL (article/post/thread), never a homepage. Hovering a point shows a summary tooltip; CLICKING pins a detail panel below the map listing every source from that location with an open link to the exact URL. Map geometry loads from world-atlas via D3 (jsDelivr/unpkg/cdnjs fallbacks; shows "Map unavailable" if all blocked). lat/lng = country centroid.
  8. Mention feed (2-column grid) — sorted by composite score, each card with 4 score pips + tier badge + velocity arrow + platform tag + publish date + source link
  9. Filter bar — Tier (All / Crisis / Watch / Engage / Log) + Score range, stacked with dismissable chips

Interaction:

  • Click any card to expand: full quote, score breakdown explaining each score, routing suggestion, suggested action text
  • Click "Sources searched" header to expand/collapse the sources panel; click a source row to filter the feed by platform
  • Market visibility donut: hover a segment or legend row to highlight and preview share; click to open the detail panel with that brand's mentions, trend, reach, sentiment split, and signal
  • Platform bars clickable to filter feed (synced with sources panel)
  • Geographic map: hover a hotspot for the summary; click it to pin a panel listing the exact sources (with open links) from that location
  • All filters stack with dismissable chips

Visualization libraries: The template loads D3 (d3.min.js) and topojson (topojson.min.js) from cdnjs for the geographic map, plus world-atlas country geometry from jsDelivr/unpkg/cdnjs (with fallbacks). The market visibility donut uses a plain <canvas> with no dependency. Keep these script tags.

Source URL rule: Every mention must include <a href="[EXACT_NIMBLE_URL]" class="src-link">↗ source</a> with the exact article/post URL from Nimble. Never use a homepage.

  • CORRECT: https://reddit.com/r/SaaS/comments/abc123/title
  • CORRECT: https://x.com/username/status/1234567890
  • WRONG: https://reddit.com WRONG: https://x.com

Markdown output spec (brand-mention-monitor-{YYYY-MM-DD}.md)

# Brand Mention Monitor — [Brand Name]
**Date range:** [DATE RANGE]
**Generated:** [TIMESTAMP]
**Total mentions:** [N]
**Sources searched:** [list]

## TL;DR
[2–4 lines: total mentions · tier breakdown (X Crisis · Y Watch · Z Engage) · the single most urgent item + its response window]

## Crisis tier (80–100) — respond <2h
- **[Tier] Score:[N]** | [Platform] | [Author] | R:[N] V:[N] S:[N] RT:[N]
  "[Excerpt]"
  Owner: [PR/Legal/Marketing] · Window: <2h
  Action: [Suggested action]
  Source: [EXACT_NIMBLE_URL]

## Watch tier (50–79) — respond <24h
...

## Engage tier — amplify within 48h
...

## Log (no action required)
...

## What This Means
[What the sweep signals for the brand right now + the top 1–3 recommended actions, each tied to a tier and owner]

Source URL rule

Every mention must include the exact Nimble result URL. CORRECT: https://reddit.com/r/SaaS/comments/abc123/title WRONG: https://reddit.com


Distribution

After output is rendered inline and files are saved, offer sharing following references/memory-and-distribution.md (connector detection, AskUserQuestion flow, Notion/Slack options).

Skill-specific routing: push brand-mention-monitor-{YYYY-MM-DD}.md to Notion (full report); post Crisis + Watch tiers only to Slack (not the full feed). Use destination from integrations in ~/.nimble/business-profile.json if set; otherwise ask and save for next time.


Saved preferences

After first run, ask:

"Save preferences? I'll remember [brand], source profile, risk topics, and routing so future runs skip setup."

Say "change settings" to update anytime.


Re-run behavior

For date window calculation, follow the Smart Date Windowing pattern in references/nimble-playbook.md — use last_runs.brand-mention-monitor from the profile.

"Sweeping for new mentions since [last run]. Anything to add to the watch list?"

Net-new mentions only. Crisis and Watch items carry forward until marked handled.


End-of-run next steps

After delivering the triage console and confirming distribution, suggest the most relevant follow-on action based on what the sweep surfaced:

  • If any Watch or Crisis mentions came from competitors framing your brand negatively: → "Want to go deeper on what competitors are saying about you? Try the competitor-positioning skill — it maps competitor messaging, positioning gaps, and attack vectors in detail."
  • If the brand appeared in funding, hiring, or M&A context: → "There are signals here that go beyond brand sentiment — the competitor-intel skill tracks business moves, hiring signals, and strategic shifts that could affect your market position."
  • If the sweep found mostly positive mentions worth amplifying: → "Some of these are worth turning into content or outreach — the competitor-positioning skill can help you identify the messaging angles your audience is already responding to."
  • If this is the first run (no prior memory): → "Run this again in 7 days to get velocity data and start seeing trends. I'll have a baseline for comparison on the next pass."

Present only the suggestions relevant to this run — do not list all four if only one applies.

Company Deep Dive

360° company research powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

From the results:

  • CLI missing or API key unset → references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists → note it for context (company name helps frame the research). Read ~/.nimble/memory/companies/index.md to check if the target company already has prior research. Follow [[path/entity]] cross-references to load related context.
    • Prior research exists: Load it. Run in refresh mode — focus on what's new since the last report date. Tell the user: "I have prior research on [Company] from [date]. Refreshing with latest data."
    • No prior research: Run in full mode — comprehensive across all dimensions.
  • No profile → that's fine. Company deep dive doesn't require onboarding (unlike competitor-intel). Proceed directly to Step 1.

Step 1: Identify Target Company

Parse the target company from $ARGUMENTS or the user's message.

If clear (e.g., "research Stripe", "tell me about Datadog"):

  • Extract the company name
  • Run two Bash calls simultaneously to confirm identity:
    • nimble search --query "[Company] official site" --max-results 3 --search-depth lite
    • nimble search --query "[Company] company overview" --max-results 5 --search-depth lite
  • Confirm briefly: "Researching [Company] ([domain])..."

If ambiguous (e.g., "research Mercury" — could be bank, auto, or other):

  • Ask one clarifying question with the top candidates

If missing — ask: "Which company would you like me to research?"

Scope selection — if the user hasn't specified depth, default to full deep dive. If they say "quick overview", "brief", or "summary", run a quick mode that skips the Deep Extraction step and produces a shorter report.

Step 2: WSA Discovery

Discover available WSAs for the target company's domain. Run both searches simultaneously:

nimble extract:templates list --limit 100  # then filter items for "{company-domain}"
nimble extract:templates list --limit 100  # then filter items for "{company-name}"

From the results, filter for WSAs with entity_type matching SERP or PDP, and prefer managed_by: "nimble". Validate each with nimble extract:templates get --extract-template-name {name}, then cache discovered WSA names + params for the run. Pass them to dimension agents in Step 3 for enrichment alongside nimble search. If no WSAs found, continue with nimble search alone.

Step 3: Parallel Research Across Dimensions (sub-agents)

Read references/dimension-agent-prompt.md for the full agent prompt template. Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn nimble-researcher agents (agents/nimble-researcher.md) with mode: "bypassPermissions". Each agent researches one dimension of the company. Pass discovered WSA names from Step 2 to each agent so they can use them for enrichment alongside nimble search.

Important: The Nimble API has a 10 req/sec rate limit per API key. With each agent running 4-5 searches in parallel, limit concurrent agents to 2 per batch to stay under the limit. Run overview searches in their own phase, not alongside agent batches.

Call estimation & Scaled Execution: Before launching agents, estimate total API calls: 2 overview searches + ~5 searches per agent × 5 agents = ~27 calls. Each agent should use extract-batch or agent run-batch for 11+ calls instead of individual calls. See the Scaled Execution pattern in references/nimble-playbook.md for tier selection.

Phase A — Overview searches (run directly, before agents):

  • nimble search --query "about" --include-domain '["[domain]"]' --max-results 3 --search-depth lite
  • nimble search --query "[Company] Wikipedia OR Crunchbase OR Pitchbook" --max-results 5 --search-depth lite

These give foundational context (founding date, HQ, employee count, mission) that frames all dimensional findings.

Phase B — Batch 1 (2 agents simultaneously):

AgentDimensionFocus
1Funding & FinancialsFunding rounds, valuation, revenue signals, investors, financial health
2Product & TechnologyProducts, tech stack, recent launches, engineering blog, open-source

Phase C — Batch 2 (2 agents simultaneously):

AgentDimensionFocus
3Leadership & TeamFounders, C-suite, key hires, departures, team size, culture signals
4Recent News & EventsPress coverage, announcements, partnerships, awards, conferences

Phase D — Batch 3 (1 agent):

AgentDimensionFocus
5Market PositionCompetitors, market share, positioning, analyst coverage, customer reviews

Refresh mode adjustment: If prior research exists, pass the known facts to each agent as context so they focus on what's new. Agents should use --start-date to filter for recent data only.

Fallback: If any agent fails or returns empty, run those dimension searches directly from the main context. Don't leave gaps in the report.

Step 4: Deep Extraction

From all agents' results, identify the top 5-8 most informative URLs across dimensions. Prioritize:

  • Funding announcements with specific amounts
  • Official product/feature pages
  • Executive interviews, podcast appearances, or conference talks
  • In-depth analyst or journalist profiles
  • The company's own about/team page

Make one Bash call per URL, all simultaneously:

nimble extract --url "https://..." --format markdown

For extraction failures, follow the fallback in references/nimble-playbook.md.

Quick mode: Skip this step entirely. Report from search snippets only.

WSA enrichment: If WSAs were discovered in Step 2, use them here for richer extraction on key URLs before falling back to nimble extract.

Step 5: Synthesize Report

Structure the output as a 360° Company Report:

# [Company Name] — Deep Dive
*As of [today's date]*

## Quick Assessment
[2-3 sentence verdict: what this company is, where they stand, and the one thing
that matters most right now. This is the "if you read nothing else" paragraph.]

## Company Overview
- Founded: [year] | HQ: [location] | Employees: [estimate]
- Domain: [domain] | Industry: [industry]
- Mission/focus: [one line]

## Funding & Financials
[Latest round, total raised, key investors, valuation signals, revenue indicators.
Every claim dated and sourced.]

## Leadership & Team
[Founders, C-suite, notable recent hires or departures. Executive perspectives
on company direction — direct quotes when available from interviews or talks.]

## Product & Technology
[Core products, recent launches, tech stack signals, engineering culture,
open-source contributions. What they're building and how.]

## Market Position
[Key competitors, differentiation, market share signals, analyst perspectives,
customer sentiment from reviews (G2/Capterra/Reddit).]

## Recent News & Events
[Chronological, most recent first. Each entry dated with source.]

## Strategic Outlook
[Synthesis across all dimensions: where the company is heading, key risks,
growth signals, and strategic bets. This is insight, not summary.]

## Sources
[Numbered list of all URLs cited in the report]

Core rules:

  • Every factual claim must have a date and source URL.
  • Lead with the Quick Assessment — most readers stop there.
  • Say "no public data found" for a dimension rather than speculating.
  • Distinguish between confirmed facts and inferred signals.
  • Executive quotes add credibility — include direct quotes from interviews, earnings calls, or conference talks when found.
  • In refresh mode: lead with "What's New Since [last date]" before the full sections.

Step 6: Save to Memory

Make all Write calls simultaneously:

  • Report → ~/.nimble/memory/reports/company-deep-dive-[date].md
  • Company profile → ~/.nimble/memory/companies/[company-name-slug].md (use the format in references/memory-and-distribution.md). Add [[path/entity]] cross-references for key people discovered (e.g., [[people/jane-smith]]), competitors in the same space (e.g., [[competitors/widgetco]]), and any other related entities.
  • If profile exists → update last_runs.company-deep-dive in ~/.nimble/business-profile.json
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.

The company profile in companies/ should contain structured key facts (overview, financials, leadership, products) that can be loaded by future runs of any skill that needs context on this company.

Step 7: Share & Distribute

Always offer distribution — do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Step 8: Follow-ups

  • Go deeper on a dimension → focused searches on that topic
  • Compare with another company → side-by-side analysis
  • "What about [specific topic]?" → targeted search + extraction
  • "Looks good" → done

Sibling skill suggestions:

Next steps:

  • Run competitor-intel to track this company as a competitor over time
  • Run meeting-prep if you're meeting with someone at this company
  • Run competitor-positioning to analyze their messaging vs yours

Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn 3 teammates instead of sub-agents. Each teammate covers related dimensions and can message the others to cross-check findings.

TeammateDimensionsCross-checks with
Financials & NewsFunding, revenue, recent news, eventsMarket (valuation vs positioning)
Product & LeadershipProducts, tech stack, founders, key hiresFinancials (pivots vs funding)
MarketCompetitors, positioning, reviews, analystsProduct (differentiation claims)

Lead (you): Create shared tasks, wait for all teammates to complete, then synthesize the final report. When a teammate finds a claim that another should verify (e.g., a funding amount that implies a valuation), it posts a task for the relevant teammate.

Solo mode (flag not set): Standard sub-agent flow from Step 3.


What This Skill Is NOT

  • Not competitor monitoring. For tracking multiple competitors over time, use competitor-intel. This skill goes deep on ONE company.
  • Not meeting prep. For researching people you're meeting with, use meeting-prep. This skill researches companies, not individuals.
  • Not financial advice. This is intelligence gathering from public sources, not investment analysis or due diligence certification.
  • Not real-time monitoring. This produces a point-in-time report. For ongoing tracking, run it again later or use competitor-intel with the company added.

Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • Search 500: Retry once without --focus flag. If still failing, retry with a simplified query (shorter terms, no date filter). Log the failure but don't skip the dimension.
  • Search timeout: Retry once, then skip that call and continue — consistent with the playbook's timeout policy.
  • Company not found: Retry with domain, alternative names, or parent company
  • Empty results for a dimension: Note "No public data found" — don't speculate

Company deep research with Nimble Web Search Agents

A Web Search Agent takes one research question, plans its own searches, reads dozens of pages in parallel and returns a cited answer, either free text or JSON that matches a schema. This skill runs the 13 hedge fund research agents Nimble published in its agent gallery, and builds a custom agent when a request falls outside them.

1. Route before you spend a run

The requestUse
One closed fact ("Who is CRWV's CFO?", "When is NVDA's next earnings date?")company-fast-search (Search with an answer)
One known URL or filingcompany-fast-search (Extract) or filings-media-pdfs
A named question that needs several sources, a table or verificationThis skill: one agent run
Thousands of product, review or job rowsalt-data-at-scale

Use one run per company and question. Do not research first and then start a run, and do not split one question across several runs. Put every sub-question in the run's input.

2. Pick the agent

Agent (agent_name)Use it when the user asks...Use case
hf-fundamental-deep-divefor a full underwriting brief tied to a strategy: business, financials, moat, alpha signals, management, risks, catalysts, variant viewresearch
hf-catalyst-calendarwhat dated events could move the stock (earnings, FDA, trials, lockups, maturities, votes, index changes)research
hf-filing-changeswhat changed in the latest 10-K or 10-Q against the prior one (new risks, dropped language, moved numbers)research
hf-forensic-red-flagsabout accounting or governance risk: auditor changes, restatements, related parties, SEC letters, short reportsresearch
hf-management-track-recordwhether management delivers on guidance and commitments, plus leadership changes and insider tradesresearch
hf-channel-checka specific "what does the web show today versus a past date" question: prices, promotions, stores, hiring, public databases, each measured against an archived baselineresearch
hf-customer-supplier-mapwho the company sells to and buys from, with evidencedataset_building
hf-competitor-momentumwhich rivals (public or private) are gaining ground, as dated signalsdataset_building
hf-government-contractsfor federal awards, task orders and bid protests, with obligated amounts against ceilingsdataset_building
hf-deal-termsfor the terms of a merger agreement: consideration, outside date, break fees, regulatory covenants, conditionsresearch
hf-deal-trackerwhere a pending merger stands with each regulator and court: approvals, lawsuits, votes, rival bids, next dates, and the outside date from the merger agreementresearch
hf-credit-profilefor a credit file on a public or private borrower: capital structure, ratings, lender marks, financials, key termsresearch
hf-credit-early-warningfor stress signals around a borrower since a date: lender actions, debt quotes, lawsuits, liens, WARN notices, adviser hires, each marked active, cured or historical, plus capital structure and liquidityresearch

Each agent's full spec (its skill, output schema, effort and example questions) is in agents/<agent_name>.json next to this file. Read the matching file before the first run; its suggested_questions show the input format the agent expects.

The three monitors (hf-deal-tracker, hf-credit-early-warning, hf-channel-check) were tightened after live tests and open with a bottom_line object: summary, key_risk, next_catalyst and next_catalyst_date (plus stress_level for credit, from active signals only). If an account copy of one of these agents was created before 2026-11-11, update it from the gallery template or the bundled spec (nimble_agents_update or PATCH /v2/agents/{agent_id}) so it gets the new skill and schema.

If two agents fit, run the one closest to the user's words. "Is this a short?" is hf-forensic-red-flags; "build me the bull and bear case" is hf-fundamental-deep-dive. Credit desks start with hf-credit-profile, then monitor with hf-credit-early-warning. Merger arb starts with hf-deal-terms, then monitors with hf-deal-tracker.

If none fits, go to section 5 and build a custom agent.

3. Get the agent into the account (reuse first)

Check in this order and stop at the first hit:

  1. Already in the account. nimble_agents_list (MCP) or GET /v2/agents. Look for an agent named hf-<name> or gallery-hf-<name>. If found, run it by agent_id.
  2. In the gallery. nimble_agent_templates_list (or GET /v2/agents/templates). If a template with the same template_name exists, create from it: nimble_agents_create(template="hf-catalyst-calendar", agent_name="hf-catalyst-calendar"). The gallery copy is maintained by Nimble, so prefer it over the bundled file.
  3. From the bundled spec. Create the agent from agents/<agent_name>.json. Pass its agent_name, display_name, description, use_case, effort, skill, output_schema and suggested_questions unchanged.

MCP:

nimble_agents_create(
  agent_name="hf-catalyst-calendar",
  display_name="Catalyst calendar",
  description=<description>, use_case="research", effort="high",
  skill=<skill>, output_schema=<output_schema>, suggested_questions=<suggested_questions>)

REST (any language, NIMBLE_API_KEY from the environment, never printed):

jq '{agent_name, display_name, description, use_case, effort, skill, output_schema, suggested_questions}' \
  agents/hf-catalyst-calendar.json |
curl -s -X POST https://sdk.nimbleway.com/v2/agents \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" -d @-

Create each agent once and reuse it. A new agent per question loses the agent's learned context and clutters the account.

4. Run it and read the result

Write input in the shape of the agent's suggested questions: the company's legal name, ticker and domain (two identifiers stop namesake drift), the window or "since" date, and the strategy or question. Keep it short. The agent's skill already holds the method.

nimble_agents_run(agent_id=<id>,
  input="Build a catalyst calendar for Rocket Lab (RKLB, rocketlabusa.com) for the next 12 months.")
→ nimble_agents_run_status(run_id=<run_id>, agent_id=<agent_id>) # waits ~45 s per call; call again until it completes

REST: POST /v2/agents/{agent_id}/runs with {"input": ...}, poll GET /v2/agents/{agent_id}/runs/{run_id} while is_active, then GET .../runs/{run_id}/result. Set trust_mode: "full_trust" (MCP) when the user wants per-claim confidence and citations.

Timing: high runs take about 5 to 15 minutes and can run to 30. Tell the user the run started and roughly how long it takes. Do not start a second run of the same question while one is active.

Check before you present. completed means finished, not correct:

  • Rows or sections returned against what was asked. A thin checked_no_finding list on a hard question means the agent stopped early; say so.
  • Entity drift: every source is about the right company (ticker, CIK, domain), not a parent, subsidiary or namesake.
  • Open two or three citations. Each source_url must be the page that states the value, not a search page.
  • Dates are event dates, not today's date. A window ("third or fourth quarter of 2027") stays a window: date is null and the window is in date_text with date_precision. Never turn a window into a day.
  • Status is current. In hf-credit-early-warning, read each signal's status: a cured signal (see cured_by) or a historical one is not live stress. A cured exchange-listing deficiency shown as active is the classic error.
  • Required fields can come back null. The platform does not enforce the schema at run time, so check the required fields and say which are empty rather than filling them.
  • No internal references in text. Strings such as quote:/pages/..., .md#L12 or file paths inside a field are leaks; remove them and cite the source_url instead.
  • A value whose only source is a paywalled page is unverified; say so.
  • Prices name the instrument, the date and the quote type (price_note). A fair value disclosed in a filing is not a market quote.
  • checked_no_finding names the exact registers, dockets or pages searched and the period. A news search that never reached the register is not evidence that nothing exists.
  • For hf-channel-check, evidence_direction: insufficient means too few like-for-like baselines. Report it as insufficient, not as "no", and say how many observations had a baseline.

Present the answer with its citations inline. Lead with the bottom_line when the agent returns one, otherwise with what matters for the position (the variant view, the nearest catalyst, the highest-severity flag), and keep analyst opinions labeled as opinions.

Follow-ups. For a narrower follow-up on the same subject, run the same agent again with previous_interaction_id set to the earlier run's interaction_id (REST), or put the earlier answer's key facts into the new input. Rerunning monitors such as hf-credit-early-warning or hf-deal-tracker with a later "since" date produces the change log.

5. When nothing fits: build a custom research agent

Create one agent per repeatable question type, not per company. Name it hf-custom-<topic> so it is found and reused next time.

  1. Classify use_case. research for a brief or a nested answer on one subject; dataset_building for a list of entities that meet criteria (all suppliers, all lawsuits, every store opening); enrichment for adding fields to rows the user already has (a watchlist or CSV, at most 20 rows and 200 cells per run, practical batch about 5 rows for 6 researched fields).
  2. Write the skill as a playbook, in the style of the bundled specs: where the evidence lives (name the regulators, registries and filing types), what each term means, the pitfalls, and the evidence rules below. Copy the "Citations and evidence" and "What was not found" blocks verbatim from hf-deal-tracker, hf-credit-early-warning or hf-channel-check (the latest versions, which also ban internal references in text and paywalled-only sources); they hold the MNPI and citation rules every investment agent needs.
  3. Write goals (REST only) as 3 to 6 checkable requirements, for example "Every row cites the primary record (filing, docket, regulator page) when one exists".
  4. Design the output_schema. Flat, 5 to 8 described fields per object, ["string","null"] for anything uncertain, YYYY-MM-DD dates, numbers as numbers with the unit in the description, enums for judgments, a source_url per value, and a checked_no_finding array so absence is reported, not hidden. For a research object, put a bottom_line object first (summary, key risk, next catalyst). Dates that may be windows get date (null unless exact) plus date_text and date_precision. Monitoring signals get status (active, cured, historical), cured_by and severity_reason. Keep roles apart in separate fields (a lender is not an owner). Array root for lists. No format, pattern, min*, max* or free-form maps.
  5. Set sources when you know them: allow tiers (for example SEC EDGAR, the company's IR domain, the relevant regulator), block mirrors and scraped-filing sites, and prioritize such as "primary records beat press; press beats aggregators".
  6. Effort. high for anything with a schema and for all dataset building (required). medium only for a free-text brief. x-high for an exhaustive single-site catalog or hard fields one row per run. Never low when citations matter.
  7. Test on one company you already know the answer for, check it against section 4, then fix the skill or schema (not the effort) before running the rest.

One-shot create-and-run (MCP): nimble_agents_run(agent_name="hf-custom-<topic>", use_case=..., effort="high", skill=..., output_schema=..., input=...). An unseen name creates the agent; a known name reuses it.

Example: "Map every data center campus Vertiv's top customers announced in 2026" is dataset_building, with a skill that names utility interconnection queues, county permit portals and hyperscaler press rooms, and a schema of campus, owner, location, mw_capacity, announced_date, vertiv_mentioned, source_url.

6. Rules that apply to every run

  • Public information only. No paywalled, logged-in, leaked or expert-network content. If only a paywalled headline is public, it can be quoted as "Headline only:".
  • Facts, not forecasts. A value nobody published is null. Analyst estimates, ratings and targets are reported as views with their source, never as evidence.
  • Primary sources win. Filings, regulators, courts, government databases and the company's own statements beat press, and press beats aggregators.
  • Point in time. Every value carries the date it was published or happened, so the user can tell what the market knew and when. A window is not a date, and a cured problem is not a live one.
  • No paywalled-only values. A paywalled page is never the only source for a value.
  • Web Search Agents read public pages. For LinkedIn, Glassdoor or social feeds, use alt-data-at-scale (Extract Templates) or --focus social search.

Fast web search for company investment research

Nimble gives three fast tools. Pick the cheapest one that answers the question, and answer in seconds rather than minutes.

ToolWhat it doesUse it for
Search (nimble_search, POST /v2/search)Live web results across engines; optional cited answer (include_answer), full page text (full_content)Finding the page: the filing, the release, the deck, the article. One closed fact.
Extract (nimble_extract, POST /v2/extract)Clean markdown from one known URL, rendered and unblocked when neededReading the page you found: an 8-K, an IR page, a pricing page, a court docket
Extract Template (nimble_extract_templates_*, POST /v2/extract/templates/run)Structured JSON from a supported site (Amazon, Walmart, Google Maps, app and review sites, job boards...)A known product, store, listing or SERP on a named site

Escalate to company-deep-research when the answer needs more than about three searches or pages, several sources reconciled, a table, or verification across sites. To download a PDF or parse a long filing, use filings-media-pdfs. For hundreds of products, reviews or postings, use alt-data-at-scale.

The fast loop

  1. Pin the entity. Write down legal name, ticker, exchange and primary domain before searching (and SEC CIK when it is a US filer). Use two of them in every query. Watch for namesakes (Block vs H&R Block), share classes, parents and subsidiaries (the debt issuer is often a subsidiary with its own filings), brands that differ from the registrant, and former names after a rename or spin-off.
  2. Decide what kind of source answers it (see references/source-map.md) and aim the query there with include_domains or a site: operator.
  3. Search narrow. max_results 3 to 5, search_depth: "lite" when titles and URLs are enough to pick the page, the default (standard) when snippets may hold the answer.
  4. Read the primary page with Extract when the snippet is not enough or the number matters. Quote the figure from the page, not from the snippet.
  5. Answer with the citation and its date: the value, the URL it was read on, and the date the source published it. Say what you checked and did not find, naming the exact pages or registers and the period they cover.

Stop at the first primary source that answers the question. If after three searches you are reconciling conflicting pages, escalate to a Web Search Agent instead of searching more.

Writing queries

  • Quote exact phrases a document would contain: "Item 5.02", "going concern", "material weakness", "termination fee", "guidance", "amendment no.".
  • Name the document type: 10-K, 8-K, DEF 14A, S-4, 424B4, "investor presentation", "earnings call transcript", "press release".
  • Scope by domain: include_domains: ["sec.gov"] for filings, the company's IR domain for decks, ["fda.gov","clinicaltrials.gov"] for biotech, ["courtlistener.com"] for dockets, ["usaspending.gov","sam.gov"] for federal contracts. Up to 50 domains; exclude_domains drops mirrors, content farms and stock-promo sites.
  • Scope by time: time_range (day, week, month, year) for "latest" questions, or start_date / end_date (YYYY-MM-DD) for a window such as "since the last earnings call" or "as of the deal announcement". They cannot be combined.
  • Pick the focus: focus: "news" for what happened this week; focus: "general" with content_type: ["pdf"] (or presentations, spreadsheets) for decks, annual reports and statistical releases; focus: "shopping" for product pricing across merchants; focus: "location" for stores and sites.
  • One question per search. Run independent searches in parallel rather than one long query.

Patterns that travel across most tasks:

NeedQuery sketch
Latest material event"<Company>" 8-K + include_domains: ["sec.gov"], time_range: "month"
Officer or director change"<Company>" "Item 5.02" on sec.gov, or "<Company>" appoints OR resigns CFO with focus: "news"
Auditor change or restatement"<Company>" "Item 4.01" / "Item 4.02" / "non-reliance"
IR deck or investor day"<Company>" "investor presentation" 2026, content_type: ["pdf","presentations"], or include_domains: [<ir domain>]
Merger terms"<Target>" "merger agreement" "termination fee" on sec.gov (DEFM14A, S-4, 8-K Ex. 2.1)
Activist stake"<Company>" "SC 13D" or "<Company>" "open letter" nominate with focus: "news"
Debt and covenants"<Company>" "credit agreement" on sec.gov (8-K Ex. 10.x), "<Company>" indenture "senior notes due"
Distress"<Company>" forbearance OR "grace period" OR "restructuring support agreement", "<Company>" "claims agent"
Regulatory eventsite:fda.gov "<Company>" "warning letter", site:clinicaltrials.gov <drug>
Price or promotion todayExtract Template on the retailer (walmart_pdp, amazon_pdp, target_serp...), or Extract on the pricing page
Hiring signalExtract the company's careers page or ATS board (Greenhouse, Lever, Ashby, Workday); indeed_serp template for postings

For a single closed fact, set include_answer: true (Nimble Answer) and still check that the answer cites a primary page.

Reading pages with Extract

  • Pass the exact URL. Default output is markdown, which is what an agent should read.
  • If the page comes back empty or truncated, retry with a JS-rendering driver (vx8) or a full-browser driver (vx10) before giving up; add wait (ms) for pages that load data late.
  • Use country (and locale) for region-specific prices and availability.
  • For PDFs, spreadsheets and decks, use filings-media-pdfs (Extract with file_parsing_options).
  • On sites Nimble maintains a template for, use the template: it returns stable fields instead of page text. Find it with nimble_extract_templates_list(query="<site>"), inspect params with nimble_extract_templates_get, run with nimble_extract_templates_run. Prefer templates managed_by: "nimble"; community templates vary in quality.

Source priority

Use secondary pages to find facts and primary pages to cite them.

  1. Regulatory filings and records: SEC EDGAR, foreign regulators, courts, government databases (FDA, ClinicalTrials.gov, USAspending, FCC, FERC, state UCC and WARN portals).
  2. The company's own statements: earnings releases, IR decks, webcast pages, press releases, careers and pricing pages. Primary but promotional; note company-defined metrics.
  3. Original reporting from reputable outlets and trade press.
  4. Repeated press, aggregators and data sites. Useful for discovery; often stale or wrong on units, periods and restatements.
  5. Social posts, forums, blogs and short reports. Signals and allegations, never facts on their own. Verify each claim against a primary record.

When two sources disagree, the primary one wins; report the conflict if it matters.

Timing and point-in-time

  • Filing deadlines set how fresh a source can be: 8-K within 4 business days of most events, Form 4 within 2 business days, Schedule 13D within 5 business days of crossing 5%, 13F up to 45 days after quarter-end (so holdings can be months old).
  • Prefer the filing or acceptance date over an article's date, and the fiscal period over the publication date. Note "as reported" versus "restated".
  • For "as of" questions, use only pages dated on or before that date, and never fill gaps from model memory. Before concluding, check once for a newer filing, an amendment (/A) or a correction.
  • A window is not a date. "Expected to close in the third or fourth quarter of 2027" is reported as that window, never as a specific day.
  • Check whether a problem is still live. An exchange deficiency notice, covenant breach or going-concern doubt can be cured or withdrawn by a later filing; say "cured on " rather than reporting it as current.

Compliance guardrails (apply to every lookup)

  • Public information only. Do not use paywalled, logged-in, leaked or confidential material, or expert-network transcripts: they carry MNPI risk. If only a paywalled headline and opening lines are public, they may be quoted, labeled "Headline only". A paywalled page is never the only source for a value.
  • Do not try to get past logins, paywalls or CAPTCHAs, and do not create accounts to see data.
  • Avoid collecting personal data that the question does not need.
  • Report estimates, price targets and ratings as attributed views, not facts.

Answer format

Lead with the answer, then the evidence:

Answer: CoreWeave's next earnings date is 2026-11-12 (confirmed). Source: CoreWeave IR events page, https://..., published 2026-10-22. Checked, nothing found: EDGAR 8-K filings for CoreWeave from 2026-10-22 to today; none changes the date.

Keep numbers in their units and periods, include every URL, and say how fresh each source is.

See references/source-map.md for the full map of research questions to sources and their timing.

Competitor Intelligence

Real-time competitive intelligence powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

From the results:

  • CLI missing or API key unset → references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists → read ~/.nimble/memory/competitors/index.md to identify which competitor files exist and their last-updated dates. If the index doesn't exist (first run or upgrade), fall back to reading all ~/.nimble/memory/competitors/*.md directly — the index is an optimization, not a gate. Then load the relevant competitor files for known signals (used for dedup in Steps 3 + 5). Follow cross-references ([[path/entity]] links) to load related context. Determine mode using smart date windowing from references/nimble-playbook.md:
    • Full mode: first run OR last run > 14 days ago
    • Quick refresh: last run < 14 days ago
    • Same-day repeat: if last_runs.competitor-intel is today, check if a report already exists at ~/.nimble/memory/reports/competitor-intel-[today].md. If so, ask: "Already ran today. Run again for fresh data?" Don't silently re-run.
    • Skip to Step 2
  • No profile → Step 1

Note: Step 2 (WSA Discovery) runs after onboarding but before any research.

Step 1: First-Run Onboarding (2 prompts max)

Prompt 1 — ask in plain text (NOT AskUserQuestion with options):

"What's your company's website domain? (e.g., acme.com)"

Verify — make two Bash calls simultaneously:

  • nimble search --query "[domain]" --include-domain '["[domain]"]' --max-results 3 --search-depth lite
  • nimble search --query "[domain] company" --max-results 5 --search-depth lite

Prompt 2 — confirm company + choose competitor method (use AskUserQuestion):

I found that [Company] ([domain]) is [brief description]. Is this right? And how should I find your competitors?

  • Yes — find competitors for me
  • Yes — I'll list them myself
  • Wrong company — let me clarify

If "find competitors", make three Bash calls simultaneously:

  • nimble search --query "[Company] competitors" --max-results 10 --search-depth lite
  • nimble search --query "[Company] vs" --max-results 10 --search-depth lite
  • nimble search --query "[Company] alternatives" --max-results 5 --search-depth lite

Propose the list. Once the user confirms, create the profile and start Steps 2+3. When creating the profile, also ask for or infer each competitor's domain and the user's industry keywords. See references/profile-and-onboarding.md for the full profile schema (company, competitors with domains/categories, industry_keywords, integrations, preferences).

Step 2: WSA Discovery

For each competitor domain and the user's domain, discover available WSAs:

nimble extract:templates list --limit 100  # then filter items for "{domain}"

Run one search per domain simultaneously. From the results, filter for WSAs with entity_type matching SERP or PDP, prefer managed_by: "nimble", and validate each with nimble extract:templates get --extract-template-name {name}. Cache discovered WSA names + params for the run. Use discovered WSAs alongside nimble search in Steps 3-4 for richer data. If no WSAs found, continue with nimble search alone.

Step 3: Research the User's Company

Use --include-domain to avoid noise from generic company names. Make two Bash calls:

  • nimble search --query "product updates OR changelog OR releases" --include-domain '["[company-domain]"]' --start-date "[start-date]" --max-results 5 --search-depth lite
  • nimble search --query "[UserCompany] news" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite

Fallback if < 3 results: nimble search --query "blog" --include-domain '["[company-domain]"]' --max-results 5 --search-depth lite

Step 4: Parallel Research Per Competitor (sub-agents)

Read references/competitor-agent-prompt.md for the full agent prompt template. Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn nimble-researcher agents (agents/nimble-researcher.md) with mode: "bypassPermissions". Customize the prompt template with each competitor's name, domain, start-date, known signals from memory (loaded in Step 0), and any discovered WSA names from Step 2 so agents can use them for enrichment.

Call estimation & Scaled Execution: Before launching agents, estimate total API calls: ~6 searches per competitor × N competitors + ~2 industry searches + extractions. For 2+ competitors (12+ calls), tell agents to use extract-batch for page extractions instead of individual calls. See the Scaled Execution pattern in references/nimble-playbook.md for tier selection.

Also run industry searches directly (not in sub-agents), using industry_keywords from the business profile:

  • nimble search --query "[industry_keyword] AI agents OR automation" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite
  • nimble search --query "[industry_keyword] regulation OR compliance OR pricing" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite

Step 5: Deep Extraction

Extract signals that need date verification OR richer detail. See references/nimble-playbook.md → "Signal Date Validation" → "Verification Budget" for the full rules.

Must extract:

  • All P1 signals (funding, M&A, leadership) — need confirmed details AND date verification
  • Any signal with DATE_CONFIDENCE: LOW — event date needs verification from page content
  • Any signal where SOURCE_TYPE: DERIVATIVE — confirm the event date from the actual page content

Extract if useful:

  • P2 signals where the snippet lacks a date or key detail

Skip: P3 signals with DATE_CONFIDENCE: HIGH.

Make one Bash call per URL, all simultaneously:

nimble extract --url "https://..." --format markdown

For extraction failures, follow the fallback in references/nimble-playbook.md.

When reading extracted content, determine the actual event date from the article body (not just the page header date). Look for: explicit dates tied to the event, temporal language ("last September", "in Q3"), and datelines.

Step 5.5: Signal Validation

Before building the report, validate every signal's freshness. See references/nimble-playbook.md → "Signal Date Validation" for the full pattern.

For each signal from Step 3, classify it:

CheckResultAction
EVENT_DATE within freshness window + not in memoryNEWInclude
EVENT_DATE within window + updates a known signalUPDATEDInclude as update
EVENT_DATE outside freshness windowSTALEDrop — old event, new article
DATE_CONFIDENCE: LOW + couldn't verify in Step 4UNCERTAINDrop with note

P1 corroboration (mandatory) — any P1 signal with NEEDS_CORROBORATION: true MUST be corroborated before it can enter the report. This is a hard gate, not a suggestion.

For each flagged P1, run:

nimble search --query "[Company] [event summary]" --max-results 5 --search-depth lite

Look for the primary source (company blog, press release, official filing). If the primary source dates the event outside the freshness window, reclassify as STALE. If no primary source is found, reclassify as UNCERTAIN and drop.

Drop rules:

  • Event date is outside the freshness window → STALE
  • Only sourced from derivative/aggregator sites with no corroborating primary or major outlet → UNCERTAIN, drop unless verified via extraction
  • Content clearly describes a past event (temporal language like "last year", "back in Q3", "months ago") with event date outside the window → STALE

After validation, you should have a clean list of NEW and UPDATED signals only.

Step 6: Analysis & Output

Full mode (first run or > 14 days since last) — structured briefing:

  • TL;DR — 3-5 P1 signals, most recent first, every one dated with source
  • Per competitor — "Recent" and "Older Context" subsections, "Where They Win vs. Where You Win" table, "What This Means" (1-2 sentences)
  • Industry Trends — signals from industry searches
  • Your Company Update — releases/news from Step 2
  • Cross-Competitor Patterns — converging trends
  • What This Means for [Company] — strategic implications + suggested actions

Quick refresh mode (last run < 14 days) — short format:

  • New Signals — dated, with competitor name, priority, and clickable source URL
  • Nothing New — list competitors with no new signals
  • Action Items — only if something requires attention

Core rules:

  • Every signal MUST have a verified event date. Only events that happened within the freshness window qualify as new signals — older events are background context.
  • Only include signals classified as NEW or UPDATED in Step 5.5. STALE and UNCERTAIN signals have already been dropped.
  • Deduplicate against ~/.nimble/memory/competitors/*.md — only surface NEW findings.
  • Say "nothing notable this period" rather than padding with fluff.
  • P3 signals: mention briefly or omit if report is long.

Step 7: Save & Update Memory

Only persist signals that passed Step 5.5 validation (classified as NEW or UPDATED). Do not write STALE or UNCERTAIN signals to competitor memory files.

Make all Write calls simultaneously:

  • Report → ~/.nimble/memory/reports/competitor-intel-[date].md (save the full briefing, not a summary — this is the local source of truth)
  • Per competitor → append validated signals to ~/.nimble/memory/competitors/[name].md (use the format documented in references/memory-and-distribution.md). Add [[path/entity]] cross-references for relationships discovered during research (e.g., key people → [[people/name]], related competitors → [[competitors/name]]).
  • Profile → update last_runs.competitor-intel in ~/.nimble/business-profile.json
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.

Step 7.5: Synthesis Page Generation

If 3+ competitors were researched in this run, OR the existing ~/.nimble/memory/synthesis/competitive-landscape.md has stale source timestamps (source entity files were updated since generation), generate or refresh the synthesis page.

Use the nimble-analyst agent (agents/nimble-analyst.md) with mode: "bypassPermissions" to synthesize patterns across all competitor files. The agent should read all ~/.nimble/memory/competitors/*.md files and produce a competitive-landscape.md following the format in references/memory-and-distribution.md — market map, feature comparison, pricing comparison, key patterns, and strategic implications. Cite source entity files with [[competitors/name]] links.

Also append any unanswered questions to ~/.nimble/memory/backlog.md (e.g., competitors where key data like pricing or funding is missing).

After generating, update index.md with the synthesis page entry.

Step 8: Share & Distribute

Always offer distribution — do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Step 9: Follow-ups

  • Go deeper on a competitor → more focused searches
  • Skip a competitor → update preferences.skip_competitors
  • Add a competitor → update competitors, create memory stub
  • "Looks good" → done

Sibling skill suggestions:

Next steps:

  • Run competitor-positioning to analyze how competitors present themselves online
  • Run company-deep-dive for a full 360 profile on any competitor from this report
  • Run meeting-prep if you're meeting with someone at a competitor

Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn full teammates instead of sub-agents:

  • Lead (you): Assign competitors, synthesize the final briefing
  • One teammate per competitor: Uses references/competitor-agent-prompt.md with discovered WSAs — teammates can message each other when they find overlapping signals
  • Devil's Advocate (optional): Challenges findings, looks for blind spots
  • Lead synthesizes a cross-validated briefing with higher confidence

Solo mode (flag not set): Standard sub-agent flow from Step 3.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • Search 500: Retry once without --focus flag. If still failing, retry with a simplified query (shorter terms, no date filter). Log the failure but don't skip the competitor.
  • Search timeout: Retry once, then skip that call and continue — consistent with the playbook's timeout policy.

Competitor Positioning

Marketing-focused competitive positioning analysis powered by Nimble's web data APIs. Built for marketing teams who need to understand how competitors present themselves — messaging, value props, content themes, pricing — and how that evolves over time.

The output is a marketing briefing, not a signal feed. Every insight should answer: "what does this mean for our messaging and positioning?"

User request: $ARGUMENTS

Argument parsing — determine what to do before running anything:

  • No arguments → run full workflow (scope confirmation in Step 2)
  • Competitor names (e.g., "Exa, Tavily") → research only those, skip scope confirmation
  • "battlecard [competitor]" → skip to Battlecard Generation (see below) using existing snapshots from memory
  • "delta" / "what changed" → force delta mode regardless of timing

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

From the results:

  • CLI missing or API key unset → references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists → load prior data from two sources:
    • ~/.nimble/memory/positioning/*.md — prior positioning snapshots (used for delta detection in Steps 4 + 5)
    • ~/.nimble/memory/competitors/*.md — business signals from competitor-intel runs (provides context for why positioning may have shifted, e.g., a funding round or leadership change that preceded a messaging pivot) Determine mode:
    • Full snapshot: first run OR no prior positioning data OR last run > 14 days ago
    • Delta mode: last run < 14 days ago — only surface what changed
    • Same-day repeat: if last_runs.competitor-positioning is today, check for existing report at ~/.nimble/memory/reports/competitor-positioning-[today].md. If found, ask: "Already ran today. Run again for fresh data?" Don't silently re-run.
    • Skip to Step 2
  • No profile → Step 1

Step 1: First-Run Onboarding (2 prompts max)

This skill shares the competitor list from competitor-intel. If a profile already exists with competitors, skip onboarding entirely.

If no profile exists, follow references/profile-and-onboarding.md for the full onboarding flow. The profile and competitor list created here will be shared across all business skills.

Step 2: Confirm Scope

If $ARGUMENTS already specifies competitors, use those and skip this step.

Otherwise, check how many competitors are in the profile:

  • 4 or fewer → proceed with all, no confirmation needed

  • More than 4 → ask which to focus on (use AskUserQuestion):

    You have [N] competitors tracked. Which ones should I analyze?

    • All [N] (~[3-5 × N] Nimble API credits, ~[N × 2] min)
    • [Category A]: [names] (grouped by category from profile)
    • [Category B]: [names]
    • Let me pick — I'll list them

    Accept natural language: "just the AI search ones" → resolve from profile categories.

This prevents wasted API credits and wall time on competitors the user doesn't care about right now. Each competitor costs ~3-5 Nimble API credits (1 map + 3-4 extracts

  • 2-3 searches).

Step 3: WSA Discovery

For each competitor domain and the user's domain, discover available WSAs:

nimble extract:templates list --limit 100  # then filter items for "{domain}"

Run one search per domain simultaneously. Filter for SERP/PDP WSAs, prefer managed_by: "nimble", validate with nimble extract:templates get --extract-template-name {name}. Cache discovered names + params. Pass them to competitor agents in Step 5 for richer extraction. If no WSAs found, continue with nimble search/extract/map.

Step 4: Capture the User's Own Positioning (baseline)

Before analyzing competitors, capture the user's own positioning as a baseline for the messaging matrix.

First, discover the site structure to find the right pages to extract:

nimble --transform "links.#.url" map --url "https://[company-domain]" --sitemap only --limit 200

From the returned URLs, identify the features/product page and pricing page (look for paths containing /features, /product, /platform, /pricing, /plans).

Then extract the key pages simultaneously (homepage + whichever pages map found):

  • nimble extract --url "https://[company-domain]" --format markdown → Homepage messaging, tagline, hero copy, CTAs
  • nimble extract --url "[features-page-url]" --format markdown → Features page structure and emphasis (skip if map found no match)
  • nimble extract --url "[pricing-page-url]" --format markdown → Pricing structure and tier naming (skip if map found no match)

If a page extraction returns garbage, note "page not accessible" and continue — partial baseline is better than none.

Step 5: Parallel Research Per Competitor (sub-agents)

Read references/positioning-agent-prompt.md for the full agent prompt template. Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Call estimation & Scaled Execution: Before launching agents, estimate total API calls: ~1 map + 3 extractions + 3 searches per competitor = ~7 × N calls (plus baseline from Step 3). For 2+ competitors (14+ calls), tell agents to use extract-batch for page extractions instead of individual calls. See the Scaled Execution pattern in references/nimble-playbook.md for tier selection.

For each competitor in scope, spawn a general-purpose sub-agent with mode: "bypassPermissions" and inline the prompt from references/positioning-agent-prompt.md. Customize the prompt with each competitor's name, domain, start-date, previous positioning snapshot from memory (loaded in Step 0), and any discovered WSA names from Step 3 for richer data access.

Do NOT use agents/nimble-researcher.md — that agent is scoped for raw data gathering and explicitly forbids analysis, but this skill requires interpretive work (identifying audience signals, comparing positioning snapshots, assessing structure implications).

Each agent handles the complete research cycle for one competitor:

  1. nimble map to discover the site's actual page structure
  2. Extract homepage, features, and pricing pages (using discovered URLs)
  3. Search for and extract recent blog posts (2-3 deep dives)
  4. Analyze social proof (case studies, testimonials)
  5. Compare against previous snapshot for changes

The agent returns a structured positioning snapshot — see the prompt template for the full output format. No separate blog extraction step is needed; agents handle it.

If an agent's blog extraction was thin (< 2 posts extracted), optionally extract additional posts from the main context using URLs from the agent's search results.

Fallback: If an agent fails entirely, run extractions directly from the main context using the same prompt template steps.

Step 6: Analysis & Output

Frame everything for a marketing team. Use terms they work with: messaging hierarchy, share of voice, battlecard inputs, content calendar implications.

When analyzing blog content from agent results, look for:

  • Recurring narratives — what story is this company telling repeatedly?
  • Audience targeting — are posts aimed at developers, executives, practitioners?
  • Competitive mentions — do they name competitors or position against categories?
  • SEO patterns — what keywords do titles and headings target?
  • Content maturity — original research, thought leadership, or generic how-tos?

Full snapshot mode (first run or > 14 days since last):

  • TL;DR for Marketing — 3-5 key positioning insights the marketing team should act on, each with a specific implication (e.g., "Competitor X shifted tagline from developer-focused to enterprise — consider whether our messaging still differentiates")

  • Messaging Matrix — build a comparison table with rows for Tagline, Primary CTA, Value Props, Target Audience, and Pricing Model across all competitors including your company. Use verbatim quotes for taglines and CTAs.

  • Per Competitor — Positioning Profile:

    • Site structure signals (what pages exist/don't exist, subdomains)
    • Homepage messaging breakdown (tagline, hero, CTAs, value props)
    • Features page analysis (what they emphasize, differentiation claims)
    • Pricing positioning (model, tier strategy, enterprise signals)
    • Content strategy (blog themes, cadence, audience, content types)
    • Social proof strategy (who they showcase, what outcomes they highlight)
  • Content Gap Analysis — what competitors are publishing that you're not:

    • Topics they cover that you don't
    • Content formats they use (case studies, benchmarks, ROI calculators)
    • Audience segments they address in content
  • Positioning White Space — messaging angles no competitor has claimed strongly:

    • Unclaimed value props
    • Underserved audience segments
    • Narrative gaps
  • Recommended Actions — specific, actionable next steps for the marketing team (e.g., "Draft counter-messaging for Competitor X's new enterprise positioning", "Prioritize case studies targeting [segment] — 3 competitors already own this space")

Delta mode (last run < 14 days) — changes only:

  • What Changed — per competitor, before/after for each shift:

    • "Tagline: '[old]' → '[new]'"
    • "New feature category added: [name]"
    • "Pricing model shifted from [old] to [new]"
    • "New blog theme emerging: [topic] (3 posts in last 2 weeks)"
  • Nothing Changed — list competitors with no positioning shifts

  • Marketing Implications — what the changes mean for your team's priorities

Core rules:

  • Every claim must link to the source page.
  • Deduplicate against ~/.nimble/memory/positioning/*.md — in delta mode, only surface genuinely new changes.
  • Say "no positioning changes detected" rather than padding with fluff.
  • Use verbatim quotes for taglines, CTAs, and value props — don't paraphrase.

WSA enrichment: If WSAs were discovered in Step 3, agents should use them alongside nimble map/nimble extract for richer page data.

Step 7: Save & Update Memory

Make all Write calls simultaneously:

  • Report → ~/.nimble/memory/reports/competitor-positioning-[date].md (save the full briefing, not a summary — this is the local source of truth)

  • Per competitor → save positioning snapshot to ~/.nimble/memory/positioning/[name].md using the format in references/positioning-snapshot-format.md. Append a dated entry to the History section so future runs can detect what changed and when. Add [[competitors/name]] cross-references to link positioning snapshots to competitor intel files.

  • Profile → update last_runs.competitor-positioning in ~/.nimble/business-profile.json

  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.

Step 8: Share & Distribute

Always offer distribution — do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement. Marketing teams especially benefit from shared Notion pages they can reference in positioning workshops and content planning sessions.

Battlecard Generation

Triggered by "battlecard [competitor]" argument or as a follow-up request.

Inputs: Read the competitor's positioning snapshot from ~/.nimble/memory/positioning/[name].md and the user's own baseline from the most recent report. If no snapshot exists (or it's stale > 14 days), run Steps 4-5 for that competitor first, then return here.

Output format:

# Battlecard: [Your Company] vs [Competitor]
## As of [date]

### Competitor Overview
- Tagline: [verbatim]
- Primary CTA: [verbatim]
- Target audience: [who their messaging speaks to]
- Pricing model: [type and entry price if known]

### Their Key Claims
[List each value prop / differentiator they emphasize, verbatim with source URL]

### Our Counter-Positioning
[For each claim above: our response, proof points, and messaging angle]

### Feature Comparison
| Capability | Us | Them | Advantage |
|---|---|---|---|

### Where They Win (acknowledge honestly)
[Areas where their positioning is stronger or they have genuine advantages]

### Where We Win
[Our unique advantages, with evidence]

### Objection Handling
| Prospect Says | Respond With |
|---|---|

### Recommended Talking Points
[3-5 concise talking points for sales/marketing conversations]

Step 9: Follow-ups

  • Generate battlecard for a competitor → runs Battlecard Generation above
  • Draft counter-messaging for a specific competitor claim → suggest alternative angles and proof points
  • Content calendar comparison → map your publishing against competitors' cadence
  • Go deeper on a competitor → extract additional pages (about, careers, partners, case studies)
  • Track a new competitor → update competitors, create positioning snapshot
  • Skip a competitor → update preferences.skip_competitors
  • "Looks good" → done

Sibling skill suggestions:

Next steps:

  • Run competitor-intel for business signals (funding, hiring, product launches)
  • Run company-deep-dive for a full 360 profile on any competitor
  • Run meeting-prep if you're meeting with someone at a competitor

Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set):

  • Use the Agent tool with name: parameter so teammates are addressable
  • Teammates can use SendMessage to share cross-competitor patterns they discover (e.g., "two competitors both shifted to usage-based pricing this month")
  • After all competitor teammates return, spawn a Marketing Analyst teammate with all findings as input, focused solely on content gap analysis and positioning white space — this separates data collection from strategic analysis
  • Lead synthesizes the final cross-validated marketing briefing

Solo mode (flag not set):

  • Standard fire-and-forget sub-agents (no SendMessage, no name:)
  • All analysis happens in the main context after agents return

Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • Search 500: Retry once without --focus flag. If still failing, retry with a simplified query (shorter terms, no date filter). Log the failure but don't skip the competitor.
  • Search timeout: Retry once, then skip that call and continue — consistent with the playbook's timeout policy.
  • Page extraction fails (404/garbage): The map step should prevent most 404s by discovering actual URLs first. If extraction still fails, note "page not accessible" and continue — partial data is better than no data.
  • Map returns empty: Some sites block sitemap access. Fall back to extracting the homepage directly and guessing common paths (/features, /pricing, /blog).
  • Empty blog results: Some companies don't blog. Note "no active blog detected" and focus on page-based positioning instead.

Credit risk

Builds a dated, sourced credit picture of a company: financials, ratings, debt events, payment behaviour, distress signals and ownership, with a risk call and its reasons.

What the user gets

Financials with periods, ratings, debt events, payment behaviour, distress signals, ownership, and a risk call (low, moderate, elevated or high) with the reasons behind it.

Agent template

This skill runs the Nimble gallery template credit-risk. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesThe exact legal entity if it is a subsidiary, with a domain or ticker-
PurposenoLending, trade credit or a supplier check. It sets what the reasons stressgeneral credit view
Country of registrationnoFor a private company, where it is registered. Its filings come from that registrycountry not specified
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your credit research assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Assess the credit and counterparty risk of <Company> (<domain or ticker>). Purpose: <purpose>. Registered in <country>.

Example: Assess the credit and counterparty risk of Rite Aid Corporation

  • One company at a time. If the user names several, run the first and offer the rest next.
  • For a subsidiary, name the exact legal entity. The agent will not use the parent's numbers.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="credit-risk", agent_name="credit-risk"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="credit-risk", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="credit-risk", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Assess another company. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as credit-risk: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Many mid-size companies have no public rating. The run says so.
  • For private companies, figures come from filed accounts or press. Check who stated them.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.
  • Always show the risk call with its reasons and sources, never alone.

Deal sourcing

Builds a list of private companies that fit an investment thesis (sector, geography, size, ownership), with evidence for each criterion.

What the user gets

A list of companies that fit the thesis, with ownership and evidence for each criterion. A short list is an honest answer.

Agent template

This skill runs the Nimble gallery template deal-sourcing. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
SectoryesWhat the companies do, for example the industry or product-
GeographyyesCountry, region or state-
OwnershipyesFor example founder-owned, family-owned or PE-backed-
SizenoEmployee or revenue rangeany size
ExclusionsnoFor example "no PE-backed", or names or domains to leave outno exclusions
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your deal sourcing assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Find <ownership> <sector> companies in <geography> with <size>. Exclude <exclusions>.

Example: Find bootstrapped European vertical SaaS companies for logistics or freight forwarding with 20-200 employees

  • Turn each criterion into a clear test. Ownership is the hard one, so state it exactly.
  • Do not ask for a number of companies. Narrow theses return few rows on purpose.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="deal-sourcing", agent_name="deal-sourcing"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="deal-sourcing", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="deal-sourcing", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Try a different thesis. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as deal-sourcing: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • Ownership is the hardest field. Spot-check the top rows before outreach.
  • A narrow thesis can return one or two companies. Offer to widen one criterion.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Decision-maker identification

Finds the people who hold given roles at a company today, with current title, career history and the source that proves it.

What the user gets

For each role, the person who holds it now: name, exact title, start date, previous roles, public profiles and a dated source. Roles it cannot confirm are listed as missing.

Agent template

This skill runs the Nimble gallery template decision-maker-identification. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesName and domain-
RolesyesUp to about 5, for example "CFO, head of RevOps, VP engineering"-
Region or business unitnoFor a large company, for example "EMEA" or "the payments team"whole company
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your contact research assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

At <Company> (<domain>), find the current <role 1>, <role 2>, <role 3> in <region or business unit>

Example: At Gong, find the current CTO, CMO, head of revenue operations and CFO

  • One company at a time. If the user names several, run the first and offer the rest next.
  • Use the title the company would use. "Head of RevOps" finds more than "Revenue Operations Leader".
  • If they ask for emails or phone numbers, say up front that it does not return them.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="decision-maker-identification", agent_name="decision-maker-identification"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="decision-maker-identification", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="decision-maker-identification", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Look up other roles or companies. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as decision-maker-identification: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • A role in missing_roles means no current source confirmed it. That is the safe behaviour, not a failure.
  • LinkedIn profile pages need a login, so the agent relies on company pages, press and public posts.
  • If the company has no such role, it returns the closest one and explains why.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Due diligence

Writes a first-pass due diligence memo on a private company: business, traction, team, funding, financial signals, legal issues, reputation and red flags, every claim dated and cited.

What the user gets

A memo with sections for business, traction, team, funding, financial signals, legal and regulatory, reputation, red flags and a short verdict. Every claim has a date and source.

Agent template

This skill runs the Nimble gallery template due-diligence. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesName and domain-
FocusnoAnything to check first, for example "focus on the AI cost story"no specific focus
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your due diligence assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Write a due diligence memo on <Company> (<domain>). Focus on <focus>.

Example: Write a due diligence memo on Canva

  • One company at a time. If the user names several, run the first and offer the rest next.
  • A focus line shifts depth. It does not remove sections.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="due-diligence", agent_name="due-diligence"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="due-diligence", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="due-diligence", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Research another company. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as due-diligence: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • A red flag must point to a cited claim above it. If one does not, drop it.
  • Revenue for private companies is usually an estimate. Check who stated it before quoting.
  • Some legal items cite a secondary page. Open the primary source before relying on it.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

Filings, decks, PDFs and media for investment research

Two Nimble capabilities do this work:

CapabilityEndpointReturnsUse it to
Extract + file parsingPOST https://sdk.nimbleway.com/v2/extract with file_parsing_optionsThe document as markdown in data.markdownRead a PDF, DOCX, XLSX/XLS/ODS/CSV or PPTX/PPT/ODP: summarize it, quote it, pull tables, diff it against a prior version
Media DownloadPOST https://sdk.nimbleway.com/v2/media (realtime) or /v2/media/async (to your bucket)The raw file (binary), validated against the MIME types you expectKeep the original file: archive a point-in-time copy, download images, audio or video, or hand a file to another tool

Rule of thumb: if the next step is reading, parse with Extract. If the next step needs the file itself, download with Media.

Both run through the REST API, the SDKs (nimble_python, @nimble-way/nimble-js, nimble-go) or the nimble CLI with NIMBLE_API_KEY set. The Nimble MCP server does not expose Media or file-parsing options, so when you only have MCP, use nimble_extract for HTML pages and tell the user the CLI or API is needed for parsing documents and downloading media. Never print the API key; let the shell expand $NIMBLE_API_KEY.

1. Find the right document first

  • Prefer the HTML filing to a PDF. SEC EDGAR serves 10-Ks, 10-Qs, 8-Ks and proxies as HTML. Extract the HTML filing (plain nimble_extract or /v2/extract without parsing options) and save parsing for exhibits and documents that only exist as PDFs.
  • Locate PDFs and decks with Search: focus: "general" plus content_type: ["pdf"] (or "presentations", "spreadsheets", "documents"), include_domains: [<company IR domain>], and a date window. Example query: "<Company>" investor presentation 2026.
  • Use the dated copy. A deck furnished under 8-K Item 7.01 (Ex. 99.x) is the timestamped version of what is on the IR page; cite it when you can.
  • Confirm the entity and the version: right issuer, right period, latest amendment. File names like Q3-2026-Earnings-Deck-vF2.pdf get replaced silently; record the URL and the date you fetched it.
  • Common investment documents: annual and sustainability reports, earnings releases and financial supplements (often XLSX), investor day decks, prospectuses (424B), merger agreements and proxies (DEFM14A, S-4 exhibits), credit agreements and indentures (8-K Ex. 10.x and 4.x), rating agency press releases, regulator letters (FDA warning letters, SEC comment letters), court filings and first-day declarations, short-seller reports and company rebuttals, conference presentation slides.

2. Parse a document into markdown

curl -s -X POST https://sdk.nimbleway.com/v2/extract \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://investors.example.com/static-files/q3-2026-deck.pdf",
    "formats": ["markdown"],
    "file_parsing_options": {"mode": "light", "max_pages": 80}
  }' | jq -r '.data.markdown' > q3-2026-deck.md

Python (plain HTTP, works with any SDK version):

import os, requests
r = requests.post("https://sdk.nimbleway.com/v2/extract",
    headers={"Authorization": f"Bearer {os.environ['NIMBLE_API_KEY']}"},
    json={"url": url, "formats": ["markdown"],
          "file_parsing_options": {"mode": "pro", "max_pages": 150}},
    timeout=300)
r.raise_for_status()
doc = r.json()
markdown, warnings = doc["data"].get("markdown", ""), doc.get("warnings", [])

Choose the mode

ModeBest forNotes
light (default)Text-native PDFs with simple layouts: releases, letters, most agreements and prospectusesFast and cheapest. No OCR. Tables can come back flat
proFinancial tables (income statements, debt schedules, capitalization tables), scanned or image-only PDFs, court filings that are scansLLM-based parsing with OCR fallback. About $7.50 per 1,000 pages, on top of the base Extract price

Start with light for text. Switch to pro when tables come back flattened or pages come back empty. Test one document before a large batch.

Parameters that matter

  • formats: ["markdown"]: returns only the parsed text. Without it, the original file also comes back base64-encoded in data.html, which bloats the response.
  • max_pages: a guard against surprise 600-page filings. A PDF over the limit is rejected before parsing (400 file exceeds limit), with no parsing charge. It does not truncate: raise the limit, omit it, or find a shorter document (the exhibit instead of the whole filing). Only PDFs are page-checked.
  • Billing is per page parsed, not per document. A parse that fails still returns 200 with a warning and is not billed; check warnings and an empty data.markdown before trusting the result.
  • File type is detected from the content type, URL extension or contents. CSV needs a .csv extension or text/csv content type.
  • country routes the fetch through a region when an IR site is geo-restricted.

What parsing cannot do well: charts, diagrams and heavily designed slides. For a deck whose numbers live in charts, check the matching earnings release or financial supplement (often XLSX, which parses cleanly) instead of reading values off the chart.

3. Work with the parsed text

  • Long filings: split by headings (Item 1A. Risk Factors, Item 7, Note 9 — Debt) and read only the sections the question needs. Do not paste a whole 10-K into context.
  • Tables: keep them as markdown tables; carry the units ("in thousands", "in millions") and the period headers with every number you quote.
  • Diffs: to compare filings (this year's risk factors against last year's), parse both versions in the same mode, align by section heading, and report added, removed and changed sentences with both URLs. The hf-filing-changes agent in company-deep-research does this end to end.
  • Citations: cite the document URL, its date, and the section or page heading the value came from. Quote short passages; do not reproduce whole documents.
  • Allegations: a short report or complaint is a claim, not a fact. Pair each claim with the primary record it relies on.
  • Read the exact words. Going concern means the filing states substantial doubt exists now, not that auditors "may" express it in future. A merger's outside (end) date and extension terms come from the merger agreement's termination section (8-K Exhibit 2.1), updated by any amendment; cite the section. A debt fair value in the notes is not a market quote.
  • Windows stay windows. "Expected to close in the second half of 2027" is quoted as written, not converted to a day.

4. Download files with Media

Realtime (raw bytes back in the response):

curl -s -X POST https://sdk.nimbleway.com/v2/media \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://investors.example.com/q3-2026-deck.pdf",
       "expected_mime_types": ["application/pdf"]}' \
  -D headers.txt --output 2026-11-11_EXMP_q3-2026-deck.pdf

The body is the file itself, not JSON. Read the actual type from the Content-Type response header. In the SDKs, read the raw response (nimble.media.with_raw_response.run(...) in Python, .asResponse() in TypeScript). The CLI prints structured output only, so use curl or an SDK for downloads.

Async (file delivered to your bucket):

curl -s -X POST https://sdk.nimbleway.com/v2/media/async \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webcast-replay.mp4",
       "expected_mime_types": ["video/mp4"],
       "storage": {"url": "s3://research-archive/exmp/2026-q3/", "type": "s3",
                   "object_name": "exmp_2026q3_webcast_20261111"}}'

It returns a task.id at once; poll GET /v2/tasks/{task_id} until state is success (or failed). The file lands at storage.url + object_name + its original extension. Bucket permissions must be granted to Nimble first (see the Callbacks & Delivery guide in the Nimble docs). Use async for large files, video, and anything going straight into a data lake.

Parameters

  • expected_mime_types: always set it. The request fails if the server returns something else, which catches the common case of an HTML error or login page served in place of the file. Wildcards work: ["image/*"], ["application/pdf"], ["audio/*", "video/mp4"], ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"].
  • country / locale: fetch as if from a region, for geo-restricted IR sites or regional product images.
  • storage.object_name must be unique. A repeated name overwrites the earlier file. Build names from ticker, document type and date, for example EXMP_10-K_2026-02-14.
  • Pricing: billed per GB downloaded (about $2.00/GB); failed downloads are not billed.

Investment uses for Media

  • Point-in-time archive: save the exact deck, release or pricing PDF as published, with the fetch date in the name, so the evidence holds up after the company replaces it.
  • Earnings webcast replays and podcasts: download direct audio or video file links (mp3, mp4) for transcription. Streaming playlists (.m3u8) and players behind registration forms are not direct files; record the page URL instead and do not get past registration.
  • Images: product, packaging and shelf photos from retailer pages, store photos, satellite or site images published by the company, to pair with alt-data tables.
  • Spreadsheets and data supplements: download the XLSX when you want to load it into pandas yourself rather than read it as markdown.

5. Batch work

For tens to hundreds of documents (every 10-K exhibit for a coverage list, every deck from a conference):

  1. Build the URL list first (Search, or a Web Search Agent in dataset_building mode for "find every investor deck from these 40 companies since 2025").
  2. Parse with Extract in parallel at a modest concurrency, set max_pages, and write each result to disk named <ticker>_<doctype>_<date>.md. Keep a ledger (URL, status, pages, warnings) and retry failures once with pro.
  3. Archive originals with /v2/media/async into the bucket, one unique object_name per file.

6. Guardrails

  • Public documents only. Do not fetch material behind logins, paywalls or registration walls, leaked or "confidential" decks circulating online, or expert-network transcripts: they carry MNPI risk.
  • Respect each source's access policy. SEC EDGAR asks for modest request rates (around 10 requests a second at most); keep batch concurrency low there.
  • Copyrighted reports (broker research, paid newsletters) are not fair game for redistribution, even when a copy is online.
  • Never print or log NIMBLE_API_KEY.

GTM data at scale with Nimble Extract Templates

An Extract Template is a maintained scraper for one page type on one site (an Indeed job search, a Google Maps search, a Google Maps reviews page, a ChatGPT answer, a YouTube channel). You pass parameters (a keyword and location, a place ID, a prompt) and get the same JSON fields every time. That consistency is what turns web pages into a signal feed a RevOps or marketing team can score, route and trend.

ScaleModeEndpoint
1 to a few inputs, need it nowRealtime runPOST /v2/extract/templates/run (MCP nimble_extract_templates_run)
One input, deliver laterAsyncPOST /v2/extract/templates/async (MCP nimble_extract_templates_run_async)
Up to 1,000 inputs at onceBatchPOST /v2/extract/templates/batch
Thousands to millions of inputs, on a scheduleExtract JobPOST /v2/jobs or online.nimbleway.com/jobs
A site with no templateTemplate generationPOST /v2/extract/templates/generations

Base URL https://sdk.nimbleway.com, header Authorization: Bearer $NIMBLE_API_KEY (never print the key). For large pulls prefer the CLI, SDKs or REST over MCP, so results go to files, not the context window.

1. Frame the dataset like an operator

Before running anything, write down with the user:

  1. The decision it feeds. For example: "Which of our 500 target accounts are growing their sales team this month?" (route to SDRs), "Are we or our competitors named when buyers ask ChatGPT for the best tool in our category?" (content and AEO), "Which dental practices in Texas have 4.5+ stars and 200+ reviews?" (SMB list), "Which competitor's G2 reviews mention switching away?" (displacement campaign).
  2. The universe. The exact accounts (with domains and CRM IDs), keywords, place IDs, handles or prompts. A fixed universe is a trend; a moving one is noise.
  3. The metrics: open roles by function and location, new postings this week, rating and review-count velocity, share of AI answers that mention the brand and which pages they cite, search position and ad presence, follower and engagement change.
  4. Geography and cadence. Which locations or countries (job and local results differ by place; AI answers differ by country) and how often (weekly for hiring and AI answers, monthly for reviews and listings).
  5. History. Web data mostly starts the day you begin collecting. Start early; review timestamps and posting dates give partial backfill. A baseline is the same page, query, place and unit on the earlier date. Never invent or approximate one to fill a gap.

Pilot on 20 to 50 inputs, check the fields, then scale.

2. Find the template

  1. List: nimble_extract_templates_list(query="indeed") or GET /v2/extract/templates?limit=50&offset=0 (paginate through about 840). Each item has name, managed_by (nimble or community), and metadata (vertical, entity type, description).
  2. Inspect: nimble_extract_templates_get(template_name=...) or GET /v2/extract/templates/{name}. Read published_version.input_schema (required params and their exact names), output_schema (the fields you will get) and samples.
  3. Prefer managed_by: "nimble" templates: Nimble maintains them around the clock and they auto-heal when sites change. Community templates work but vary; check a sample run before building on one.
  4. Param names differ between templates: indeed_serp takes keyword and location; linkedin_job_search_* takes query and location; google_maps_search takes query (and optional coordinates); google_maps_reviews takes place_id, sort, num_results; chatgpt and perplexity take prompt (and country_code); google_ai takes keyword; youtube_channel takes account_id. Always copy names from the input_schema.

references/template-catalog.md lists the GTM-relevant templates in the catalog as of 2026-11-12, grouped by signal. Typical starting points:

SignalTemplates to start with
Hiring and sales-team growthindeed_serp, linkedin_job_search_*, dice_com_company_jobs_*; for one company's own ATS board, Extract its Greenhouse, Ashby or Lever URL
People for named rolesti_linkedin_serp_profiles (Google results limited to LinkedIn profiles); confirm current role on a first-party page
Software and employee reviewsg2_product_profile_*, glassdoor_company_reviews_*, shopify_app_store_search, bbb_org_customer_reviews_*
Local businesses (SMB prospecting)google_maps_search, google_maps_reviews, bing_maps_local_listings_*, bbb_org_business_search_*
AI answers and AI search visibilitychatgpt, perplexity, gemini, google_ai, reddit_answers
Search rankings and competitor adsgoogle_search (organic and is_sponsored results), bing_web_search_results_*
News monitoringbing_news_search_*, duckduckgo_news_search_*, yahoo_news_search_*
Social and creatorsyoutube_channel, tiktok_account, instagram_profile_by_account, facebook_page, reddit_subreddit_posts_*
Selling to ecommerce brandsamazon_serp, amazon_best_sellers, walmart_serp, target_serp, tiktok_shop_pdp, myshopify_com_*

Search can also run templates: nimble_search with focus set to up to 10 template names (for example ["chatgpt","perplexity","google_ai"]) fans one prompt across engines for a quick snapshot.

3. Run it

Realtime (pilot and spot checks)

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/run \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{"template": "indeed_serp", "params": {"keyword": "account executive Rippling", "location": "United States"}}' \
  | jq '.data.parsing'

Structured fields are in data.parsing. Add "formats": ["markdown"] or ["html"] only when you need the raw page too (for audit). Every template also accepts the shared params country, locale, tag and parse inside params.

Batch (up to 1,000 inputs per request)

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/batch \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "shared_inputs": {"template": "chatgpt", "params": {"country_code": "US", "tag": "aeo_panel_2026-11-12"}},
    "inputs": [
      {"params": {"prompt": "What are the best conversation intelligence tools for a 50-person sales team?"}},
      {"params": {"prompt": "Gong vs Clari vs Outreach for revenue forecasting"}}
    ]
  }'
  • shared_inputs.template is required and applies to every item; per-item params merge over shared_inputs.params (per-item wins). formats can be set shared or per item.
  • Delivery options go in shared_inputs.params: storage_type (s3 or gs), storage_url, storage_compress, callback_url.
  • Poll GET /v2/batches/{batch_id}/progress until completed: true, then GET /v2/batches/{batch_id} for each task's state and download_url, and fetch each success task's download_url (or GET /v2/tasks/{task_id}/results). The progress counter can trail the task states, so also read task states from GET /v2/batches/{batch_id} and collect finished tasks as they land; retry error tasks once in a new batch.
  • Put a tag in params (for example hiring_panel_2026-11-12) so rows can be traced to a collection run.

Async (single input, delivered): POST /v2/extract/templates/async with template, params, and optional storage_type, storage_url, storage_object_name, storage_compress or callback_url. Poll GET /v2/tasks/{task_id} until state is success, then GET /v2/tasks/{task_id}/results. Results land as {task_id}.json (or your object name) in the bucket. The callback carries task metadata only, not data.

Extract Jobs (recurring feeds): the right tool once the pilot works. A job binds one template to an input set, a schedule and a destination, then fans out one run per input row with retries and concurrency handled by Nimble.

curl -s -X POST https://sdk.nimbleway.com/v2/jobs \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-target-account-sales-hiring",
    "extract_template_name": "indeed_serp",
    "schedule": {"cron": "0 7 * * 1", "enabled": true},
    "inputs": {"type": "inline", "data": [{"keyword": "account executive Rippling", "location": "United States"}]},
    "destination": {"type": "s3", "path": "s3://gtm-signals/hiring/indeed/", "format": "parquet"}
  }'
  • Inputs: inline JSON, an uploaded CSV or Parquet whose column names match the template params, an S3 file or folder (latest file is used), or a Databricks table via Delta Sharing. Rows may include country, locale and tag. Add your CRM account ID as an extra column and turn on include input so each output row carries it for joins.
  • Destinations: download from Nimble, S3, or Databricks (Delta Sharing, 14-day retention: materialize into your own table). Formats JSON, CSV or Parquet. From there, load into the warehouse and sync scores to the CRM with the user's existing reverse-ETL or CRM import.
  • Schedule: cron in UTC, or Day / Week / Month presets; manual triggers (POST /v2/jobs/{job_id}/runs) add runs without changing the schedule.
  • Monitor: GET /v2/jobs/runs/{run_id} for status; artifacts hold the input set, valid rows and invalid rows, with success rate and error samples per run. Edits take effect on the next run. One job runs one template; use one job per site.
  • Jobs run Extract Templates, not Web Search Agents. For a scheduled agent job (a weekly trigger watch), run the agent from the user's own scheduler.

4. When no template exists: generate one

Use generation only when the catalog has nothing for the site and the data will be pulled repeatedly (a vertical directory, an association's member list, a marketplace's partner directory, a conference's exhibitor pages). For a one-off, use Extract or a Web Search Agent instead.

curl -s -X POST https://sdk.nimbleway.com/v2/extract/templates/generations \
  -H "Authorization: Bearer $NIMBLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example-conference.com/2026/exhibitors",
    "prompt": "Exhibitor directory page. Extract every exhibitor: company name, website, booth number, sponsorship tier, category, and the exhibitor profile URL.",
    "name": "example_conference_exhibitors",
    "output_schema": {"type": "array", "items": {"type": "object", "properties": {"company": {"type": "string"}, "website": {"type": "string"}, "tier": {"type": "string"}}}}
  }'
  • Required: url (a representative example page) and prompt. Optional: name (lowercase, digits and underscores), input_schema, output_schema, metadata.
  • Poll GET /v2/extract/templates/generations/{generation_id} until status is terminal. On success it reports generated_version with its input_schema, output_schema and samples. Check the samples on two or three other pages of the same type before trusting it.
  • Refine with POST /v2/extract/templates/generations and {"from_extract_template": "<name>", "prompt": "Also capture the booth number; it was missing for sponsors"}.
  • Manage: GET /v2/extract/templates/{name}/versions and /versions/{version_id} to compare versions, PATCH /v2/extract/templates/{name} (JSON Patch: [{"op": "replace", "path": "...", "value": ...}]), DELETE /v2/extract/templates/{name}.
  • MCP equivalents: nimble_extract_templates_generate, nimble_extract_templates_generation_status, nimble_extract_templates_update_from_template. Only generate when the user asked for a reusable template.

5. Make the data decision-grade

  • Keys and timestamps. Store every row with the CRM account ID or domain, template name and version, collection timestamp (UTC), location or country, and tag. Keep raw JSON next to the cleaned table so fields can be re-derived.
  • Entity mapping. Job and review sites name employers their own way ("Rippling People Center Inc.", a subsidiary, a staffing agency posting for a client). Map employer name → domain → CRM account and keep the map under version control. Exclude staffing agencies and reposts unless the user wants them.
  • Same panel every run. Changes to the account list, keywords, prompts or locations break trends. Version the input list and log every change.
  • Missing is not zero. A failed or empty fetch is a gap, not "no open roles" or "not mentioned". Track success rate per run and per site; alert when it drops.
  • Dedupe: job posts on job ID (the same role is often posted in many cities), reviews on review ID, listings on place ID.
  • Use the event's own date: posting date, review timestamp, answer collection date, not the collection run.
  • AI answers vary. Sample several phrasings of each buyer prompt, in each country that matters, on a fixed cadence; report mention share and cited sources over time, not one answer.
  • Sanity checks: week-over-week jumps, duplicate rows, template field drift after a site redesign (Nimble-managed templates heal, but check the fields you depend on).
  • Turn data into actions: a score per account (for example new sales roles in 30 days, new senior hire, rating drop) and a threshold that routes it to an owner, rather than a raw table.

6. Compliance

  • Collect public pages only: no logins, created accounts, paywalls or CAPTCHA bypassing.
  • Minimize personal data. Drop reviewer names, job-poster identities and profile links the analysis does not need; keep business contact details only for businesses (a dental practice's public phone), not for individuals unless the task needs it and the user's privacy rules allow it.
  • Outbound use of web data follows the user's own rules: suppression lists, opt-outs, GDPR, CASL and CAN-SPAM decide who is contacted, not the dataset.
  • Document lineage for legal or RevOps: the sites, the templates, the cadence, and what is and is not collected.
  • Keep request volume proportionate; Jobs and batches handle pacing, so do not hand-roll parallel floods on top of them.

Healthcare Providers Enrich

Fill gaps in existing practitioner lists with verified web data, powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight + WSA Discovery

Sibling handoff check: Before running full preflight, check if healthcare-providers-extract ran earlier in this session by following the Sibling Handoff pattern from references/nimble-playbook.md. If same-day extract output exists, skip CLI check and profile load, and reuse WSA Layer 1/3 inventory. Only re-run Layer 2 if the specialty changed.

Otherwise, run full preflight from references/nimble-playbook.md (5 simultaneous Bash calls: date calc, today, CLI check, profile load, index.md load).

Also simultaneously — run WSA discovery and setup:

  • mkdir -p ~/.nimble/memory/{reports,healthcare-providers-enrich/checkpoints}
  • ls ~/.nimble/memory/healthcare-providers-enrich/checkpoints/ 2>/dev/null
  • Run Layer 1 (vertical) and Layer 3 (general tools) WSA discovery from references/wsa-reference.md. Layer 2 (session-specific) runs after Step 1 when you know the user's specialty.

Classify discovered agents into phases and validate with nimble extract:templates get per references/wsa-reference.md.

From the preflight results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note it for context. Determine mode using smart date windowing from references/nimble-playbook.md:
    • Full mode: first run OR last run > 14 days ago
    • Quick refresh: last run < 14 days ago (re-enrich only records with gaps)
    • Same-day repeat: if last_runs.healthcare-providers-enrich is today, check for existing report at ~/.nimble/memory/reports/healthcare-providers-enrich-*[today].md. If found, ask: "Already ran today. Run again for fresh data?"
  • No profile -> that's fine. This skill doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Input + Starting Questions

Chained-from-extract shortcut: Check for a same-day extract report:

ls ~/.nimble/memory/reports/healthcare-providers-extract-*$(date +%Y-%m-%d).md 2>/dev/null

If a same-day report exists, parse the {slug} from the filename and load ~/.nimble/memory/healthcare-providers-extract/{slug}/providers.json. The practice domains and page URL patterns are already known — construct individual bio page URLs from the site's URL convention and skip Step 3 entirely. This avoids N unnecessary web searches. If no same-day report exists, do not reuse old providers.json files.

Parse $ARGUMENTS for input type using the Input Parsing Pattern from references/nimble-playbook.md. Key routing:

  • Extract output detected (providers.json) -> proceed to Step 2, mark Step 3 skip
  • CSV/Sheet/pasted data detected -> proceed to Step 2
  • Unclear -> ask (counts as 1 of max 2 prompts)

If input is clear, confirm and ask one shaping question (plain text, not AskUserQuestion):

"Found N providers in your list. Quick questions:

  1. Which fields need filling? (contact info, credentials, specialty, reviews, regulatory — or all gaps)
  2. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)"

If input is ambiguous, use AskUserQuestion (counts as 1 of max 2 prompts):

What provider list should I enrich?

  • Paste provider data directly (name + any known info, one per line)
  • Provide a CSV file path or Google Sheet URL
  • Or describe what you have (e.g., "a list of 50 ophthalmologists with just names and states")

Skip questions the user already answered in their initial message.

Step 2: Analyze Existing Data

Parse the input into structured records. For each provider, identify:

  • Known fields — what the user already has (name, state, specialty, etc.)
  • Missing fields — gaps against the 5 core fields from references/provider-extraction-patterns.md (name, credentials, specialty, contact, education)
  • Enrichment targets — additional fields the user requested (reviews, regulatory, accreditation)

Early exit — no gaps: If all providers are already High confidence (5/5 fields), skip to Step 5 (WSA enrichment) or report: "All providers already have complete profiles. Want me to add supplementary data (reviews, clinical trials, accreditation) instead?"

Build a gap analysis summary:

"Analyzing N providers:

  • Names: N/N present
  • Credentials: N/N present (N missing)
  • Specialty: N/N present (N missing)
  • Contact info: N/N present (N missing)
  • Education: N/N present (N missing)

Starting enrichment for N providers with gaps..."

Run Layer 2 WSA discovery now that you know the specialty:

nimble extract:templates list --limit 50  # filter items for "[specialty]"
nimble extract:templates list --limit 50  # filter items for "[directory-user-mentioned]"

See references/wsa-reference.md for session-specific discovery.

Step 3: Web Search for Provider Identity

For each provider with gaps, find their practice website and bio page:

nimble search --query "[provider name] [credentials] [location] [specialty]" --max-results 5 --search-depth lite

Search strategy:

  • Include all known fields in the query to disambiguate common names
  • Prioritize results from practice websites over directory listings
  • If the provider has a known practice name, add it to the query
  • For providers with only name + state, broaden: "[name] [state] doctor"

Result selection: Pick the most relevant result — practice bio page > healthcare directory profile > LinkedIn. Save the selected URL for extraction.

For 10+ providers, use sub-agents (see Sub-Agent Strategy below).

Checkpoint (mandatory): You MUST write the checkpoint file before proceeding. Interrupted runs with 20+ providers waste significant API credits without resume.

echo '{...}' > ~/.nimble/memory/healthcare-providers-enrich/checkpoints/{slug}/search.json

Step 4: Extract Missing Fields

Choose extraction strategy based on provider count. Follow the Scaled Execution pattern from references/nimble-playbook.md — it covers individual calls (1-10), extract-batch (11-100), and the confirmation gate for larger jobs. Use the Page Extraction with Retry pattern from the same reference for garbage detection and retry logic.

Parse extracted content for missing fields using the detection patterns from references/provider-extraction-patterns.md (credential regex, specialty keywords, contact patterns, education mentions).

Merge rules:

  • Only fill fields that are actually missing — never overwrite existing data
  • Track which fields were added and their source URL
  • If extracted data conflicts with existing data, keep the existing value and flag the conflict for user review

Checkpoint (mandatory): You MUST write the checkpoint file before proceeding.

echo '{...}' > ~/.nimble/memory/healthcare-providers-enrich/checkpoints/{slug}/extraction.json

Step 5: WSA Enrichment (Optional)

If the user requested reviews, regulatory data, or accreditation — or if the gap analysis shows most core fields are already filled and enrichment adds more value:

Run enrichment-phase WSAs discovered in Step 0. See references/wsa-reference.md for the enrichment phase mapping, agent evaluation, and fallback chains.

For each practice or provider, run relevant enrichment agents simultaneously. Follow the Scaled Execution pattern from references/nimble-playbook.md for batching.

Merge enrichment data into provider records:

  • Reviews/ratings -> add as supplementary fields (not part of core 5)
  • Clinical trial activity -> add as supplementary field
  • Accreditation status -> add as supplementary field

Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication and Entity Confidence Scoring patterns from references/nimble-playbook.md. Skill-specific dedup rules and the 5-field confidence criteria are in references/provider-extraction-patterns.md.

Enrichment-specific confidence: Score only the newly added fields:

  • High — field found and confirmed by 2+ sources
  • Medium — field found from 1 source
  • Low — field inferred or partially matched

Step 7: Output

Present results as an enrichment diff — showing what was added to each provider. Group by practice, sort by confidence within each group, and include a "What This Means" section at the end with actionable next steps.

# Provider Enrichment: [N] Providers Updated
*[Date] | [A] fields added across [P] providers | [H] High, [M] Medium, [L] Low confidence*

## TL;DR
Enriched [P] of [T] providers. Added [A] total fields: [breakdown by field type].
[Key finding: e.g., "Found contact info for 18 of 20 providers, 3 have clinical trials"].

## Enrichment Results

| # | Name | Added Fields | Confidence | Source |
|---|------|-------------|------------|--------|
| 1 | Dr. Jane Smith | +credentials (MD, FACS), +contact ((555) 123-4567) | High | [source](url) |
| 2 | Dr. John Doe | +specialty (General Ophthalmology), +education (Wills Eye) | Medium | [source](url) |
| 3 | Dr. Alex Chen | +contact ((555) 987-6543) | Low | [source](url) |

## Detailed Records

### Dr. Jane Smith
**Existing:** Name, State (TX)
**Added:**
- Credentials: MD, FACS — [source](url)
- Contact: (555) 123-4567 — [source](url)
- Education: Fellowship, Bascom Palmer Eye Institute — [source](url)
**Confidence:** High (3 fields added, 2 sources)

[Repeat per provider with additions]

## Providers Not Enriched
[List providers where no additional data was found, with attempted searches]

## Data Quality Summary
- **Fully enriched (5/5 fields):** [N] providers
- **Partially enriched:** [N] providers — common gaps: [list]
- **No new data found:** [N] providers

## Sources
[Clickable URL for every page used, grouped by provider]

## What This Means
[Actionable interpretation: which providers are ready to contact, which need more
data, what the enrichment coverage tells you about this list's quality]

Source links are mandatory. Every added field must trace back to a source URL.

Step 8: Save to Memory

Make all Write calls simultaneously:

  • Report -> ~/.nimble/memory/reports/healthcare-providers-enrich-{slug}-{date}.md
  • Enriched data -> ~/.nimble/memory/healthcare-providers-enrich/{slug}/enriched.json
  • Profile -> update last_runs.healthcare-providers-enrich in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Step 9: Share & Distribute

Always offer distribution — do not skip. Follow references/memory-and-distribution.md for connector detection and sharing flow.

Notion: full enrichment report as a dated subpage. Slack: TL;DR with enrichment summary and field counts only.

Step 10: Follow-ups

  • "Tell me more about Dr. X" -> show full enriched profile
  • "Export as CSV" -> generate CSV with original + enriched fields
  • "Enrich more fields" -> re-run with expanded field targets
  • "Which providers still have gaps?" -> filter to incomplete records

Sibling skill suggestions:

Next steps:

  • Run healthcare-providers-verify to validate the enriched credentials and license status
  • Run healthcare-providers-extract to discover more providers from practice websites
  • Run market-finder to find additional practices in this area

Sub-Agent Strategy

For batch enrichment (10+ providers), use nimble-researcher agents (agents/nimble-researcher.md) to parallelize search and extraction.

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn pattern: One agent per batch of 5 providers. Each agent runs Steps 3-4 for its assigned providers and returns enriched records. Tell each agent to use nimble extract-batch for its assigned URLs rather than individual nimble extract calls — one batch call per agent is faster and more reliable than sequential calls.

Small batch optimization: If fewer than 10 providers, run directly from the main context instead of spawning agents.

Fallback: If any agent fails, run those enrichments directly from the main context. Never leave gaps in the output.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • No search results for provider: "Couldn't find a web presence for [name] in [state]. The name may be too common or the provider may not have an online presence. Want me to try with additional context (practice name, specialty)?"
  • Ambiguous provider match: "Found multiple providers named [name] in [state]. Can you confirm which one? [list top 3 with practice names]"
  • All extractions returned garbage: "The provider websites appear to be heavily JavaScript-rendered. Retrying with browser rendering..." (auto-retry with --render per the shared pattern)
  • CSV/Sheet parse error: "Couldn't parse the input file. Expected columns with provider names and at least one identifier (state, specialty, or practice). Can you paste the data directly instead?"
  • No gaps detected: Handled in Step 2 (early exit to WSA enrichment or report).

Healthcare Providers Extract

Structured practitioner extraction from healthcare practice websites, powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight + WSA Discovery

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously — run WSA discovery and setup:

  • mkdir -p ~/.nimble/memory/{reports,healthcare-providers-extract/checkpoints}
  • ls ~/.nimble/memory/healthcare-providers-extract/checkpoints/ 2>/dev/null
  • Run Layer 1 (vertical) and Layer 3 (general tools) WSA discovery from references/wsa-reference.md. Layer 2 (session-specific) runs after Step 1 when you know the user's specialty.

Classify discovered agents into phases and validate with nimble extract:templates get per references/wsa-reference.md.

From the preflight results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note it for context. Determine mode using smart date windowing from references/nimble-playbook.md:
    • Full mode: first run OR last run > 14 days ago
    • Quick refresh: last run < 14 days ago (re-extract only new/changed pages)
    • Same-day repeat: if last_runs.healthcare-providers-extract is today, check for existing report at ~/.nimble/memory/reports/healthcare-providers-extract-*[today].md. If found, ask: "Already ran today. Run again for fresh data?"
  • No profile -> that's fine. This skill doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Input & Starting Questions

Parse $ARGUMENTS for input type using the Input Parsing Pattern from references/nimble-playbook.md. Key routing:

  • URLs detected -> proceed to Step 3
  • Specialty + location (no URLs) -> proceed to Step 2 (practice discovery)
  • Unclear -> ask (counts as 1 of max 2 prompts)

If input is clear, confirm and ask one shaping question (plain text, not AskUserQuestion):

"Extracting providers from N practice sites. Quick questions:

  1. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)
  2. Quick scan (names + credentials only) or full extraction (all 5 fields)?"

If input is ambiguous, use AskUserQuestion (counts as 1 of max 2 prompts):

What practice sites should I extract providers from?

  • Paste URLs directly (one per line)
  • Provide a CSV file path or Google Sheet URL with practice URLs
  • Or describe what you're looking for (e.g., "ophthalmologists in Austin, TX") and I'll find practices first

Skip questions the user already answered in their initial message.

Step 2: Practice Discovery (Optional)

Only if the user provided a specialty + location instead of URLs.

Two input paths into discovery:

Path A — Fresh discovery. User gave specialty + location. Run Layer 2 WSA discovery for session-specific agents:

nimble extract:templates list --limit 50  # filter items for "[specialty]"
nimble extract:templates list --limit 50  # filter items for "[directory-user-mentioned]"

See references/wsa-reference.md for the full discovery strategy, agent evaluation criteria, and healthcare discovery prioritization.

Run all discovery-phase agents simultaneously. Validate params with nimble extract:templates get first.

Path B — Market-finder handoff. User ran market-finder first and wants to extract providers from those results. Read the market-finder output:

cat ~/.nimble/memory/market-finder/{slug}/entities.json 2>/dev/null

Extract practice records. Note: Google Maps results contain place_url (a Maps link) but not the practice's actual website URL. Proceed to Step 2b to resolve real website URLs before site mapping.

After either path: Deduplicate by domain. Present discovered practices:

"Found N practices for [specialty] in [location] across [M] data sources. Proceeding to extract providers from these sites..."

Fallback — if no discovery WSAs were found, or results are sparse (< 3):

nimble search --query "[specialty] in [location]" --max-results 20 --search-depth lite

Step 2b: Resolve Practice Website URLs

Discovery sources (Google Maps, Yelp, BBB) return listing URLs, not practice website URLs. Before site mapping, resolve the actual website for each practice:

  1. Check structured data first — Google Maps results often include a website field in the structured output. Use it if present.
  2. Extract from listing page — if no website field, extract the Maps listing to find the practice website link:
    nimble extract --url "[maps-listing-url]" --format markdown
    
  3. Search fallback — if extraction fails:
    nimble search --query "[practice-name] [city] official website" --max-results 3 --search-depth lite
    

Skip practices where no website URL can be resolved — note them in the "Data Quality Summary" output section.

Step 3: Site Mapping

Follow the Site Mapping Pattern from references/nimble-playbook.md for each practice URL. Skill-specific settings:

  • Keyword weight table: references/provider-extraction-patterns.md
  • Page cap: 15 per site
  • Fallback query: site:[domain] doctors OR providers OR team

For 6+ practices, use sub-agents (see Sub-Agent Strategy below).

Save checkpoint: ~/.nimble/memory/healthcare-providers-extract/checkpoints/{slug}/mapping.json

Step 4: Page Extraction

WSA shortcuts first: If WSA discovery found agents that extract provider data from healthcare directories, use those for matching practices — structured WSA output is higher quality than parsed markdown.

For all other practices, follow the Page Extraction with Retry pattern from references/nimble-playbook.md. Scale using the Scaled Execution pattern from the same reference.

Save checkpoint: ~/.nimble/memory/healthcare-providers-extract/checkpoints/{slug}/extraction.json

Step 5: Structured Parsing

Parse extracted markdown to identify providers and their fields. Read references/provider-extraction-patterns.md for the 5 core fields, credential regex patterns, and specialty keywords.

For each extracted page:

  1. Scan for provider name patterns (Dr. prefix, heading patterns, bold text near credential suffixes)
  2. Match credentials using the regex patterns from references/provider-extraction-patterns.md
  3. Match specialty using keywords for the detected healthcare vertical
  4. Extract contact info (phone regex, appointment URLs, email)
  5. Extract education/training mentions

Build structured records:

{
  "name": "Dr. Jane Smith",
  "credentials": "MD, FACS",
  "specialty": "Retinal Surgery",
  "contact": {"phone": "(555) 123-4567", "scheduling_url": "..."},
  "education": "Fellowship: Bascom Palmer Eye Institute",
  "source_url": "https://practice.com/our-doctors",
  "practice_name": "Shore Center for Eye Care",
  "practice_url": "https://practice.com",
  "confidence": "High"
}

Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication and Entity Confidence Scoring patterns from references/nimble-playbook.md. Skill-specific dedup rules and the 5-field confidence criteria are in references/provider-extraction-patterns.md.

Step 7: Output

Present results grouped by practice, sorted by confidence within each practice.

# Provider Extraction: [N] Providers from [M] Practices
*[Date] | [H] High, [M] Medium, [L] Low confidence*

## TL;DR
Extracted [N] providers from [M] practice websites. [H] with complete profiles,
[L] with partial data. [Key finding: e.g., "12 of 15 providers are board-certified"].

## [Practice Name] ([domain])

| # | Name | Credentials | Specialty | Contact | Education | Confidence |
|---|------|------------|-----------|---------|-----------|------------|
| 1 | Dr. Jane Smith | MD, FACS | Retinal Surgery | (555) 123-4567 | Fellowship: Bascom Palmer | High |
| 2 | Dr. John Doe | OD | General Ophthalmology | [Book](url) | Residency: Wills Eye | Medium |

[Repeat per practice]

## Data Quality Summary
- **Complete profiles (High):** [N] providers
- **Partial profiles (Medium):** [N] providers — missing: [list common gaps]
- **Minimal profiles (Low):** [N] providers — missing: [list common gaps]

## Sources
[Clickable URL for every page extracted, grouped by practice]

Source links are mandatory. Every provider record must trace back to a source URL.

Step 8: Save to Memory

Make all Write calls simultaneously:

  • Report -> ~/.nimble/memory/reports/healthcare-providers-extract-{slug}-{date}.md
  • Provider data -> ~/.nimble/memory/healthcare-providers-extract/{slug}/providers.json
  • Profile -> update last_runs.healthcare-providers-extract in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Step 9: Share & Distribute

Always offer distribution -- do not skip. Follow references/memory-and-distribution.md for connector detection and sharing flow.

Notion: full provider table as a dated subpage. Slack: TL;DR with provider count and confidence breakdown only.

Step 10: Follow-ups

  • "Tell me more about Dr. X" -> show full extracted profile
  • "Export as CSV" -> generate CSV from providers.json
  • "Run on more sites" -> append new practice URLs, extract and merge
  • "What's missing?" -> detail the data gaps per provider

Enrichment from discovered WSAs: If Step 0 found enrichment-phase agents (reviews, regulatory, practice details), offer them as immediate follow-ups:

"I also found [N] WSAs that could enrich this data: [brief list]. Want me to run reputation checks or regulatory lookups on these providers/practices?"

See references/wsa-reference.md for enrichment phase mapping and fallback chains.

Sibling skill suggestions:

Next steps:

  • Run healthcare-providers-enrich to fill data gaps (NPI lookup, board certification verification, additional contact info)
  • Run healthcare-providers-verify to validate credentials and license status
  • Run market-finder to discover more practice URLs in this area

Sub-Agent Strategy

For batch extraction (6+ practices), use nimble-researcher agents (agents/nimble-researcher.md) to parallelize site mapping and extraction.

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn pattern: One agent per practice (or per batch of 3 practices for large jobs). Each agent runs Steps 3-5 for its assigned practices and returns structured provider records.

Single-practice optimization: If only 1-2 practices, run directly from the main context instead of spawning agents.

Fallback: If any agent fails, run those extractions directly from the main context. Never leave gaps in the output.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • No provider pages found: "Couldn't find provider/team pages on [domain]. The site may list staff differently. Want me to try extracting from the homepage or search for this practice on healthcare directories?"
  • All extractions returned garbage: "The practice sites appear to be heavily JavaScript-rendered. Retrying with browser rendering..." (auto-retry with --render per the shared pattern)
  • Ambiguous practice name: If a URL fails and the user provided a name instead, search for the practice: nimble search --query "[practice name] [location] doctors" --max-results 5 --search-depth lite
  • CSV/Sheet parse error: "Couldn't parse the input file. Expected a column with practice URLs. Can you paste the URLs directly instead?"

Healthcare Providers Verify

Validate practitioner credentials against the NPI registry and authoritative sources, powered by Nimble's web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight + WSA Discovery

Sibling handoff check: Before running full preflight, check if healthcare-providers-extract or healthcare-providers-enrich ran earlier in this session by following the Sibling Handoff pattern from references/nimble-playbook.md. If same-day output exists, skip CLI check and profile load, and reuse WSA Layer 1/3 inventory. Only re-run Layer 2 if the verification focus changed.

Otherwise, run full preflight from references/nimble-playbook.md (5 simultaneous Bash calls: date calc, today, CLI check, profile load, index.md load).

Also simultaneously — run WSA discovery and setup:

  • mkdir -p ~/.nimble/memory/{reports,healthcare-providers-verify/checkpoints}
  • ls ~/.nimble/memory/healthcare-providers-verify/checkpoints/ 2>/dev/null
  • Run Layer 1 (vertical) and Layer 3 (general tools) WSA discovery from references/wsa-reference.md. Layer 2 (session-specific) runs after Step 1 when you know the user's specialty and verification focus.

Classify discovered agents into verification categories and validate with nimble extract:templates get per references/wsa-reference.md.

From the preflight results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note it for context. Determine mode using smart date windowing from references/nimble-playbook.md:
    • Full mode: first run OR last run > 14 days ago
    • Quick refresh: last run < 14 days ago (re-verify only previously Unverified/Flagged practitioners)
    • Same-day repeat: if last_runs.healthcare-providers-verify is today, check for existing report at ~/.nimble/memory/reports/healthcare-providers-verify-*[today].md. If found, ask: "Already ran today. Run again for fresh data?"
  • No profile -> that's fine. This skill doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Input + Starting Questions

Chained-from-sibling shortcut: Check for same-day extract or enrich output:

ls ~/.nimble/memory/reports/healthcare-providers-extract-*$(date +%Y-%m-%d).md 2>/dev/null
ls ~/.nimble/memory/reports/healthcare-providers-enrich-*$(date +%Y-%m-%d).md 2>/dev/null

If a same-day report exists, parse the {slug} and load the provider data (providers.json or enriched.json). This gives you names, credentials, specialties, and locations — skip parsing and go directly to Step 2.

Parse $ARGUMENTS for input type using the Input Parsing Pattern from references/nimble-playbook.md. Key routing:

  • Sibling output detected (providers.json/enriched.json) -> proceed to Step 2
  • CSV/Sheet/pasted data detected -> proceed to Step 2
  • Unclear -> ask (counts as 1 of max 2 prompts)

If input is clear, confirm and ask one shaping question (plain text, not AskUserQuestion):

"Found N practitioners to verify. Quick questions:

  1. What should I verify? (credentials, specialty, active status, practice address — or all)
  2. Healthcare vertical? (ophthalmology, dental, dermatology, general, or other)"

If input is ambiguous, use AskUserQuestion (counts as 1 of max 2 prompts):

What practitioner data should I verify?

  • Paste provider data directly (name + credentials + location, one per line)
  • Provide a CSV file path or Google Sheet URL
  • Or describe what you have (e.g., "a list of 50 ophthalmologists I need to verify against the NPI registry")

Skip questions the user already answered in their initial message.

Step 2: Analyze Input Data

Parse the input into structured records. For each practitioner, identify:

  • Claimed fields — name, credentials, specialty, state/city, practice name
  • Verification targets — which claims to check based on user's focus

Minimum required fields: Name + at least one of (credentials, state, specialty). If a practitioner has only a name with no other identifiers, flag it: "Cannot verify [name] — need at least a state, credential, or specialty to search."

Build a verification plan summary:

"Analyzing N practitioners for verification:

  • Names: N/N present
  • Credentials claimed: N/N
  • Specialty claimed: N/N
  • State/location: N/N

Starting NPI verification..."

Run Layer 2 WSA discovery now that you know the specialty:

nimble extract:templates list --limit 50  # filter items for "[specialty]"
nimble extract:templates list --limit 50  # filter items for "[registry-user-mentioned]"

See references/wsa-reference.md for session-specific discovery.

Step 3: NPI Registry Lookup

Prefer the NPPES API — it returns structured JSON in one call instead of search + extract (two calls). Build the query URL from the practitioner's fields:

nimble extract --url "https://npiregistry.cms.hhs.gov/api/?version=2.1&first_name=[First]&last_name=[Last]&state=[ST]&limit=5" --format markdown

Add &taxonomy_description=[Specialty] if the specialty is known and specific enough. The API returns NPI number, status, credentials, taxonomy codes, addresses, and enumeration dates — everything needed for verification in a single call.

Fallback to web search if the NPPES API returns zero results or errors:

nimble search --query "[Name] [Credential] [State] NPI registry" --max-results 5 --search-depth lite

Then extract the top result from an NPI source (see source priority below).

Source priority (enforce in sub-agent prompts):

  1. NPPES API (npiregistry.cms.hhs.gov/api/) — preferred, structured JSON
  2. npidb.org/doctors/ — clean structured data, good fallback
  3. nppes.cms.hhs.gov (provider-view pages) — official CMS source
  4. Skip all others (healthline, hmedata, vitals, etc.) — inconsistent formatting

Tell sub-agents: "Only extract from NPPES API, npidb.org, or nppes.cms.hhs.gov. Ignore other NPI aggregator sites."

Search budget per provider: Max 3 search queries + 1 extraction per practitioner. If no NPI match after 3 attempts, mark as Unverified and move on. Tell sub-agents: "Do not run more than 4 nimble commands per provider. Mark as Unverified if no match by then."

For 10+ practitioners, use sub-agents (see Sub-Agent Strategy below).

Key fields from NPI records — see references/npi-verification-patterns.md for the full list: NPI number, status, credentials, taxonomy/specialty, enumeration date, last updated, practice address.

Checkpoint enforcement: After each sub-agent returns its batch results, the main context MUST write the checkpoint before spawning the next step or presenting results:

  1. Receive sub-agent results
  2. Write checkpoint: echo '[results]' > ~/.nimble/memory/healthcare-providers-verify/checkpoints/{slug}/batch-{n}.json
  3. Continue to next step

Do NOT skip this — if the run fails between steps, the user loses all progress.

Step 4: Cross-Reference and Verify

For each practitioner, compare claimed data against extracted NPI data. Follow the verification logic in references/npi-verification-patterns.md:

  1. Name matching — normalize both names and determine match level (Strong, Likely, Weak, No Match) per the name matching rules in the reference
  2. Credential matching — compare claimed credentials against NPI record
  3. Specialty matching — compare claimed specialty against NPI taxonomy using the taxonomy matching strategy in the reference
  4. Address matching — compare claimed state/city against NPI practice address
  5. Status check — verify NPI status is Active

Assign verification status per practitioner based on the totality of evidence:

  • Verified — all claims match NPI record
  • Partially Verified — NPI found, minor discrepancies
  • Unverified — no NPI match found or unable to disambiguate
  • Flagged — active mismatches requiring human review

See references/npi-verification-patterns.md for the detailed criteria for each status and the mismatch severity levels (Critical vs Warning).

Step 5: WSA Supplementary Verification (Optional)

If the user requested regulatory verification beyond NPI lookup, or if Step 5 left practitioners as Unverified that might benefit from additional sources:

Run verification-phase WSAs discovered in Step 0. See references/wsa-reference.md for the verification phase mapping, agent evaluation, and fallback chains.

Practice confirmation: For Unverified practitioners, try confirming their practice exists via practice-level WSAs or web search:

nimble search --query "[practice-name] [city] [state]" --max-results 5 --search-depth lite

Regulatory verification: For practitioners the user wants regulatory checks on:

nimble search --query "[name] [credentials] clinical trials OR FDA OR board certification" --max-results 5 --search-depth lite

Step 6: Deduplication & Confidence Scoring

Follow the Entity Deduplication pattern from references/nimble-playbook.md. Skill-specific dedup rules are in references/provider-extraction-patterns.md.

NPI dedup check: After all sub-agents return, scan for duplicate NPI numbers across batches. If two different providers mapped to the same NPI, flag both as "Flagged — possible NPI collision, requires human review." This catches data entry errors and name confusion in the source provider list.

Verification-specific scoring: The verification status (Verified / Partially Verified / Unverified / Flagged) replaces confidence scoring for this skill. Each status includes a confidence qualifier:

  • High confidence — 2+ NPI sources corroborate, strong name match
  • Medium confidence — single NPI source, likely name match
  • Low confidence — weak name match, partial field matches

Step 7: Output

Present results as a verification report — showing status per practitioner with specific mismatch details. Group by verification status, include a "What This Means" section at the end.

# Provider Verification: [N] Practitioners Checked
*[Date] | [V] Verified, [PV] Partially Verified, [U] Unverified, [F] Flagged*

## TL;DR
Verified [V] of [T] practitioners against the NPI registry. [F] flagged for
review: [brief description of critical issues]. [U] could not be verified —
[common reason].

## Verification Results

| # | Name | Claimed | NPI Status | Verification | Issues | Source |
|---|------|---------|------------|-------------|--------|--------|
| 1 | Dr. Jane Smith | MD, Retinal Surgery, TX | Active (NPI 1234567890) | Verified | — | [NPI](url) |
| 2 | Dr. John Doe | OD, Ophthalmology, CA | Active (NPI 0987654321) | Partially Verified | Subspecialty differs | [NPI](url) |
| 3 | Dr. Alex Chen | MD, Dentistry, NY | Not Found | Unverified | No NPI match | [NPPES query](api-url) |
| 4 | Dr. Pat Lee | DO, Cardiology, FL | Deactivated | Flagged | NPI deactivated 2024-01 | [NPI](url) |

## Flagged Practitioners (Requires Human Review)

### Dr. Pat Lee
**Claimed:** DO, Cardiology, FL
**NPI Record:** NPI 1122334455 — **Deactivated** (01/15/2024)
**Issues:**
- CRITICAL: NPI status is Deactivated since January 2024
- Credential matches (DO confirmed)
- Specialty matches (Cardiovascular Disease taxonomy)
**Source:** [NPI Record](url)
**Action needed:** Confirm if provider has re-registered or if this is a
different individual.

[Repeat per flagged practitioner]

## Unverified Practitioners

[List practitioners where no NPI match was found, with search queries attempted]

## Verification Summary
- **Verified:** [V] practitioners — all claims confirmed
- **Partially Verified:** [PV] — minor discrepancies noted
- **Unverified:** [U] — no NPI match (common names, missing identifiers)
- **Flagged:** [F] — critical issues requiring review

## Sources
[Clickable URL for every NPI lookup page used, grouped by practitioner]

## What This Means
[Actionable interpretation: which practitioners are safe to include in your
directory, which need follow-up, what the verification rate tells you about
your data quality. Suggest next steps for unverified/flagged records.]

Source links are mandatory. Every verification finding must trace back to a source URL.

Step 8: Save to Memory

Make all Write calls simultaneously:

  • Report -> ~/.nimble/memory/reports/healthcare-providers-verify-{slug}-{date}.md
  • Verification data -> ~/.nimble/memory/healthcare-providers-verify/{slug}/verified.json
  • Profile -> update last_runs.healthcare-providers-verify in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Update sibling artifacts: If providers.json or enriched.json exists for this slug under ~/.nimble/memory/, merge NPI numbers and verification status into those files. Generate a verified CSV export at ~/.nimble/memory/healthcare-providers-verify/{slug}/verified-{date}.csv with all verification columns (NPI, NPI Status, NPI Taxonomy, Verification Status). Offer this export path in Step 9 so the user can copy it where needed.

Step 9: Share, Distribute & Follow-ups

Always offer distribution — do not skip. Follow references/memory-and-distribution.md for connector detection and sharing flow.

Notion: full verification report as a dated subpage. Slack: TL;DR with verification counts and flagged items only.

Follow-ups:

  • "Tell me more about Dr. X" -> show full verification detail
  • "Export as CSV" -> generate CSV with verification statuses
  • "Re-verify flagged only" -> re-run NPI search for Flagged/Unverified only
  • "What should I do about the flagged ones?" -> actionable next steps per issue

Sibling skill suggestions:

Next steps:

  • Run healthcare-providers-extract on unverified providers' practice URLs to get fresh data
  • Run healthcare-providers-enrich to fill gaps in verified providers' records
  • Run market-finder to find additional practices in this area

Sub-Agent Strategy

For batch verification (10+ practitioners), use nimble-researcher agents (agents/nimble-researcher.md) to parallelize NPI lookups and extraction.

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn pattern: One agent per batch of 5 practitioners. Each agent runs Steps 3-4 for its assigned practitioners and returns verification records. Tell each agent to use nimble extract-batch for its NPI result URLs where possible — one batch call per agent is faster than sequential calls.

Small batch optimization: If fewer than 10 practitioners, run directly from the main context instead of spawning agents.

Fallback: If any agent fails, run those verifications directly from the main context. Never leave gaps in the output.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • No NPI results for practitioner: "Couldn't find an NPI record for [name] in [state]. The name may be too common, or the provider may practice under a different name. Want me to try with additional context (practice name, NPI number)?"
  • Multiple NPI matches: "Found multiple NPI records for [name] in [state]. Can you confirm which one? [list top 3 with NPI numbers and specialties]"
  • NPI page extraction returned garbage: "The NPI lookup page appears to be JavaScript-rendered. Retrying with browser rendering..." (auto-retry with --render per the shared pattern)
  • CSV/Sheet parse error: "Couldn't parse the input file. Expected columns with practitioner names and at least one identifier (state, specialty, or credentials). Can you paste the data directly instead?"
  • Insufficient data for verification: "Cannot verify [N] practitioners — they have only a name with no state, credential, or specialty. Add identifiers or remove them from the list."

KYC screening

Runs a sourced KYC / AML research screen on a company: registration, officers, beneficial owners, sanctions, PEPs and adverse media, with namesakes excluded and a risk rating.

What the user gets

Registry details, officers and owners, sanctions and PEP checks, adverse media, related entities, how many namesakes were excluded, and a risk rating with reasons.

Agent template

This skill runs the Nimble gallery template kyc-screening. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
CompanyyesLegal or trading name-
CountryyesWhere it is registered-
Registry number or LEInoRemoves namesake riskmatched by name and country
WebsitenoThe company's domain. It confirms the right entityno website given
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your KYC research assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Run a KYC screen on <Company> in <Country>. Registry number: <number>. Website: <domain>.

Example: Run a KYC screen on Greensill Capital in the United Kingdom

  • One entity at a time. If the user names several, run the first and offer the rest next. Country is required.
  • A registry number or LEI makes the match exact.
  • Leave out any part of the pattern the user skipped: leaving it out is the default.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="kyc-screening", agent_name="kyc-screening"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="kyc-screening", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="kyc-screening", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Screen another entity. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as kyc-screening: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • One trading name can map to several legal entities. Check the registration block is the one they meant.
  • Coverage is strongest where public registries exist: the UK, the EU and US states.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.
  • Say once that this is a research screen, not a certified compliance check.

Launch Monitor

Monitors press, social, and community forums from launch day — tracking sentiment, flagging mischaracterizations, surfacing competitor responses, and recommending actions so you can respond fast.


Onboarding message

When this skill is triggered for the first time in a session, send this message. Send it exactly once per session, before asking any setup questions. Do not skip it even when the user's opening message already names a product — the onboarding sets expectations for what the skill collects and how it works.

👋 Launch Monitor is ready.

This skill monitors press, social media, developer communities, and competitor channels around a product launch — tracking sentiment, flagging mischaracterizations, surfacing competitor responses, and telling you exactly what to respond to and how.

To start, just say: "Monitor the launch of [product name]"

Or try:

  • "Track coverage since we announced [product] yesterday"
  • "What's the reaction to our [product] launch?"
  • "Flag any mischaracterizations in our [product] press coverage"
  • "How are competitors responding to our [product] launch?"

Would you like me to save your preferences so I skip the questions next time?


Preflight

Follow the transport selection and standard preflight from references/nimble-playbook.md: pick CLI vs MCP at session start, then run the parallel preflight calls (date, profile, memory index) simultaneously. Tag every Nimble CLI call: nimble --client-source nimble-agent-skills <subcommand>.

From the profile (~/.nimble/business-profile.json): load product/brand context and last_runs.launch-monitor for date windowing. Pre-populate setup questions so the user confirms rather than re-enters. If no profile exists, follow the first-run onboarding flow in references/profile-and-onboarding.md and create a stub after the first run.


How to start

Before asking anything, do two quick research steps:

Step A — Resolve alternate names automatically: Search for the product the user named to discover all alternate names, codenames, version names, and related search terms. Do not ask the user for this. Use what you find to build a comprehensive search term list for Step 1.

  • Search: "[product name]" official name OR "also known as" OR codename OR version
  • For Apple products, always check for internal codename, model number, and marketing name variants
  • For software: check GitHub repo names, API names, and SDK names
  • Add all confirmed variants to your search queries silently — the user never needs to see this step

Step B — Confirm launch date automatically: Search for when the product launched before asking the user. Surface what you find and ask the user to confirm or correct it.

  • Search: "[product name]" launch date OR announced OR "available now" OR "shipping today"
  • If you find a clear date, present it to the user for confirmation
  • If you find multiple conflicting dates (announcement vs GA), surface both and ask which window to use

Then ask in a single message:

"Before I run — just confirming a couple of things:

  1. Launch date: I found that [product] launched on [DATE YOU FOUND] — is that the right date to monitor from, or a different one?
  2. Window: How far back should I look beyond that? (default: from launch date to now)
  3. Depth: Quick scan (faster) or deep sweep (more thorough, more sources)? (default: deep)
  4. Competitors: I'll monitor competitor responses by default — any specific competitors to prioritize or exclude?"

Output is always the Response War Room rendered directly in Claude. Do not ask about format or output options.

Exceptions — skip asking entirely if:

  • The user provided all the above in their initial message
  • The user has run this skill before in the session (use prior config)

Defaults if user says "just run it":

  • Window: launch date to now
  • Depth: deep
  • Competitors: on (identify automatically from context profiling)

Disambiguation: If the product name is ambiguous after research, confirm before proceeding:

"Just to confirm — by [product], do you mean [Option A] or [Option B]?"


Step 0 — Context profiling (run before any searches)

Before searching, profile the product to adapt all queries:

  1. What category is this? (developer tool, consumer app, enterprise SaaS, hardware, API, etc.)
  2. What ecosystem does it live in? (e.g. Claude/Anthropic, AWS, Salesforce, open source)
  3. Who is the target audience? (developers, PMs, enterprise buyers, consumers)
  4. What are the key claims made at launch? (extract from the user's description or a quick search of the announcement)
  5. What would a mischaracterization look like? (wrong category, wrong pricing, wrong capability, wrong comparison)

Use this profile to:

  • Target the right communities and press outlets
  • Build precise search queries that find real coverage vs noise
  • Know what "correct" positioning looks like so mischaracterizations can be flagged accurately
  • Understand what competitor responses would look like

Step 1 — Signal sweep

Run all of the following in parallel. Use --search-depth lite for the discovery pass. Switch to --search-depth deep only when extracting full article or thread content. Tag every call: nimble --client-source nimble-agent-skills search ...

Press & editorial

  • "[product name]" site:techcrunch.com
  • "[product name]" site:theverge.com
  • "[product name]" site:wired.com
  • "[product name]" site:arstechnica.com
  • "[product name]" site:venturebeat.com
  • "[product name]" site:siliconangle.com
  • "[product name]" site:theregister.com
  • "[product name]" site:zdnet.com
  • "[product name]" "[company name]" announcement OR launch OR release
  • Category-specific press (e.g. for dev tools: InfoQ, SDTimes; for AI: The Information, Import AI)

Social & community

Run ALL of the following — social moves faster than press. Use focus:"social" on Nimble for broader platform reach. See references/sources.md Tier 2b for full query patterns per platform.

Reddit (run multiple subreddit-specific queries, not just the broad one):

  • "[product name]" site:reddit.com — broad
  • "[product name]" site:reddit.com/r/[category] — category subreddit
  • "[product name]" site:reddit.com/r/[company] — brand subreddit
  • "[product name]" site:reddit.com/r/technology and other relevant subs
  • Nimble social focus: focus:"social" query "[product name]" reddit

X / Twitter:

  • "[product name]" site:x.com
  • "[product name]" wrong OR broken OR disappointed site:x.com — complaint hunt
  • "[product name]" "actually" OR correcting site:x.com — correction chains
  • Check quote-tweets of the official launch tweet

LinkedIn:

  • "[product name]" site:linkedin.com
  • "[product name]" launched OR "my take" site:linkedin.com

Instagram:

  • Nimble social focus: focus:"social" query "[product name]" instagram
  • Signal: influencer posts, brand account engagement, consumer reactions

TikTok:

  • Nimble social focus: focus:"social" query "[product name]" tiktok review OR reaction
  • Signal: viral reaction videos within 48h; comment sentiment

YouTube:

  • "[product name]" review OR reaction OR "first impressions" site:youtube.com
  • "[product name]" problems OR issues site:youtube.com

Facebook / Threads:

  • Nimble social focus: focus:"social" query "[product name]" facebook OR threads

Hacker News:

  • "[product name]" site:news.ycombinator.com
  • Also search: hn.algolia.com/?q=[product+name]&dateRange=last24h

Dev communities:

  • "[product name]" site:dev.to
  • "[product name]" site:medium.com

Developer communities (if applicable)

  • "[product name]" site:stackoverflow.com
  • "[product name]" site:github.com — issues, discussions, reactions
  • "[product name]" site:discord.com OR discord community
  • "[product name]" site:hashnode.com

Competitor monitoring (if enabled)

  • [competitor A] "[product name]" OR "[category]" — how are they reacting?
  • [competitor A] announcement OR response OR "compared to" — any counter-announcements?
  • Check competitor social accounts and blogs for positioning moves
  • Search for "[competitor] vs [product name]" content published since launch date

Mischaracterization hunting

Run targeted queries designed to surface wrong information:

  • "[product name]" "[wrong claim to watch for]"
  • "[product name]" pricing OR price — check if pricing is being reported accurately
  • "[product name]" vs "[wrong comparison]" — is it being compared to the wrong thing?
  • "[product name]" "[capability it doesn't have]" — check for capability inflation or deflation

Step 2 — Signal triage

For every signal found, assign:

Urgency level:

  • 🔴 Act now — mischaracterization going viral, high-reach negative coverage, competitor counter-announcement, crisis signal
  • 🟡 Monitor — emerging negative theme, mid-reach inaccurate coverage, competitor positioning content
  • 🟢 Good signal — accurate positive coverage, organic enthusiasm, developer adoption signals
  • ⬜ Noise — irrelevant mentions, unrelated products with similar names, spam

Action badge:

  • RESPOND — requires a direct public response (tweet, comment, press outreach)
  • CORRECT — requires a correction or clarification (DM, comment, press note)
  • AMPLIFY — worth sharing, retweeting, or building on
  • ESCALATE — needs to go to comms, legal, or leadership
  • WATCH — no action yet but track for escalation
  • IGNORE — filtered noise

Signal type:

  • Press coverage · Community discussion · Social mention · Competitor move · Mischaracterization · Churn signal · Influencer take · Developer reaction · Analyst comment

Source URL — required for every signal: Every signal must include the exact URL returned by Nimble for that article, thread, or post. This URL powers the clickable ↗ source link on each card. A homepage URL is useless to the user.

CORRECT — exact article/thread/post URLs:

  • https://techcrunch.com/2026/06/11/nimble-mcp-connector-launch
  • https://news.ycombinator.com/item?id=12345678
  • https://reddit.com/r/MachineLearning/comments/abc123/is_nimble_just_another_scraper
  • https://x.com/[username]/status/[POST_ID]

WRONG — never use these:

  • https://techcrunch.com
  • https://news.ycombinator.com
  • https://reddit.com
  • https://x.com

Use the URL exactly as Nimble returns it in the search result. Do not fabricate a URL.


Step 3 — Mischaracterization analysis

For every piece of coverage that gets something wrong, extract:

  1. The claim — exactly what was said
  2. The source — outlet, author, reach estimate, date
  3. What's wrong — specific inaccuracy
  4. The correct version — what the accurate statement is
  5. Spread risk — is this being picked up by others? (search for secondary coverage citing the wrong claim)
  6. Suggested response — one-sentence correction Claude recommends

Step 4 — Sentiment velocity

Track how sentiment is trending over time since launch:

  • Break the window into intervals (e.g. hourly for first 24h, daily after that)
  • For each interval: count positive, negative, neutral signals
  • Identify the inflection point — when did sentiment peak? When did it shift?
  • Flag any velocity spike — sudden surge in mentions (positive or negative)

Memory dedup (filter already-known signals)

Before generating output, run the dedup lifecycle from references/memory-and-distribution.md against prior launch-monitor reports in ~/.nimble/memory/reports/.

Skill-specific rules:

  • Fingerprint: {url, signal_type, published_date} — normalize URLs (strip query params, trailing slashes).
  • Returning signal, urgency changed: keep in feed, mark with ↩ returning · urgency changed badge.
  • Already known, no change: suppress from Act Now / Monitor sections; include in appendix only if user requested full history.
  • Summary line: show at top of war room: X net-new · Y returning (urgency changed) · Z suppressed.
  • Persist: after the run, save signal fingerprints to ~/.nimble/memory/reports/launch-monitor-{YYYY-MM-DD}.md and append a log.md entry per references/memory-and-distribution.md.

Output template (REQUIRED)

Claude MUST follow references/template.html exactly when generating the HTML output. Load the template, substitute real researched data into placeholders, keep all CSS, JS, and interaction patterns identical.

Required response structure

Every launch-monitor response must follow this structure, in order:

  1. ## TL;DR — first section, always. Two to three sentences: overall sentiment read (positive / mixed / negative / trending), count of act-now items, and the single most urgent signal or mischaracterization. Example: "Sentiment is mixed-to-negative in the first 48 hours, with 5 act-now items. The dominant risk is the 'Gemini reskin' framing spreading across HN and press. Three mischaracterizations are active, two spreading."
  2. The inline Response War Room widget — rendered immediately after TL;DR per the sequence below.
  3. ## What This Means — final section, always. Two to three sentences synthesizing what the signal pattern implies for launch trajectory and the single most important action for the team to take right now.

Rendering — INLINE FIRST, ALWAYS (read this before producing output)

The Response War Room is an interactive widget that must be rendered inline in the chat. A downloadable file is a secondary artifact, never the primary deliverable. Follow this sequence exactly, every run:

  1. Render the war room inline FIRST. Write the fully-populated launch-monitor-{YYYY-MM-DD}.html to ~/.nimble/ using the Write tool, then emit the HTML content inline in the conversation so the user sees the interactive widget immediately. This inline output is the main deliverable and must happen before anything else is offered.
  2. Then, and only then, offer downloads. After the inline widget is on screen, confirm that ~/.nimble/launch-monitor-{YYYY-MM-DD}.html and ~/.nimble/launch-monitor-{YYYY-MM-DD}.md have been saved and offer them to the user for download or sharing.

Hard rules:

  • Never respond with only a download link or only a file. If the user sees a file but no inline war room, the run has failed its primary job.
  • Do not ask the user whether they want it inline or as a file, and do not ask about format — inline is always the default and the file always accompanies it.
  • The inline widget and the downloadable HTML are the same artifact — render the identical template, do not produce a stripped-down inline version.

If the inline output genuinely cannot be produced:

  1. Say so explicitly in one short line — e.g. "I couldn't render the war room inline this time, so here's the file instead."
  2. Confirm the file has been saved to ~/.nimble/launch-monitor-{YYYY-MM-DD}.html as the fallback.

Never silently fall back to a download — if inline fails, name the failure so the user knows it was the environment, not the intended behavior.

Output template spec (launch-monitor-{YYYY-MM-DD}.html)

The Response War Room has a distinct visual identity from all other skills:

  • Light background using CSS variables — inherits host theme, works in both light and dark mode
  • Monospace accents for signal metadata — feels operational, not reporty
  • Color system: Red #A32D2D / Amber #854F0B / Green #3B6D11 for urgency — matches the CSS variable palette
  • Tight, dense layout — war room feel, not a dashboard feel
  • Source links: <a href="[EXACT_NIMBLE_URL]" class="src-link">↗ source</a> — color #185FA5, no border/background, click listener on sc-top (not sc) so links pass through

Required sections in order:

0. Launch header bar Full-width bar showing: product name · launch date · time since launch · total signals found · last updated timestamp

1. Sentiment velocity chart A small line chart (not bars) showing signal volume over time since launch, split into positive (green line) and negative (red line). X-axis = time intervals. Y-axis = signal count. Hoverable data points showing count + top signal at that moment. Click a point to filter the signal feed to that time window.

2. Signal feed — the war room The main panel. Signal cards displayed in a responsive grid that packs 2–3 cards across by available width (it auto-fills columns rather than forcing a fixed count, so the feed stays compact and never collapses to a single long column). Cards are sorted by urgency (🔴 first, then 🟡, then 🟢). Each card shows:

  • Top row: urgency dot + action badge + type tag + chevron (all on one line in .sc-header)
  • Headline (font-size 12px, font-weight 500)
  • One-line context (font-size 11px, muted)
  • Bottom row: metadata + ↗ source link — pinned to card bottom with margin-top:auto and a top border so all cards in a row align visually
  • Suggested action shown on expand — click card to expand (click listener on .sc-top, not .sc, so source link clicks pass through)

Grid layout CSS: .feed { display:grid; grid-template-columns:repeat(auto-fill,minmax(215px,1fr)); gap:8px } — auto-fill packs as many ~215px columns as fit (2–3 across at typical render widths), keeping the feed short. Do not change this back to a fixed repeat(2,...), which can collapse to one column at narrow widths. .no-sigs spans both columns: grid-column:1/-1

Filter bar above the feed:

  • Primary: View tabs — All / 🔴 Act now / 🟡 Monitor / 🟢 Good / Mischar. — synced with clickable stat cards
  • Secondary: Collapsed "Refine" button → expands panel with action type + signal type pills
  • Active filters shown as dismissable chips with "Clear all"

All filters stack. Signal count updates live. "No signals match" empty state spans full width.

3. Mischaracterization tracker A dedicated panel — only shown if mischaracterizations were found. Two-column layout:

Left column: The claim (what was said, source, reach) Right column: The correction (accurate version + suggested response text)

Each row has a COPIED button that copies the suggested correction to clipboard. Status badge: SPREADING (if being picked up) / CONTAINED (single source) / CORRECTED (if already addressed).

4. Competitor response panel Only shown if competitor monitoring is enabled. One card per competitor showing:

  • Competitor name
  • What they did (published content, tweet, counter-announcement, silence)
  • Urgency assessment
  • Suggested counter-move

5. Coverage summary Compact stats row: Total signals · Press mentions · Community threads · Social mentions · Mischaracterizations · Competitor moves · Avg sentiment score

Interaction requirements (JS click handlers — never CSS hover):

  • Signal cards: click to expand/collapse suggested action text
  • Velocity chart: click data point to filter feed to that time window
  • Filter buttons: all three filter rows stack independently
  • Mischaracterization copy button: copies correction text to clipboard
  • All filters show live count of matching signals

Styling:

  • Background: var(--color-background-primary) — transparent outer, inherits host
  • Card background: var(--color-background-primary) with 0.5px solid var(--color-border-tertiary) border
  • Section backgrounds: var(--color-background-secondary)
  • Text: var(--color-text-primary) / var(--color-text-secondary) — never hardcoded
  • Monospace: 'SF Mono', 'Fira Code', monospace for metadata fields
  • Urgency red: #A32D2D · amber: #854F0B · green: #3B6D11
  • Action badge colors: RESPOND/ESCALATE use red tint · CORRECT amber tint · AMPLIFY green tint · WATCH gray tint
  • Source links: color: #185FA5 — inline <a href> tag, no border or background
  • Do NOT use hardcoded dark backgrounds anywhere

Markdown output spec (launch-monitor-{YYYY-MM-DD}.md)

# Launch Monitor — [Product Name]
**Launch date:** [DATE]
**Monitored window:** [DATE RANGE]
**Generated:** [TIMESTAMP]
**Total signals:** [N]

## TL;DR
[2-3 sentences: overall sentiment read, count of act-now items, single most urgent signal or mischaracterization]

## Summary
- Act now: [N] | Monitor: [N] | Good signals: [N] | Noise: [N]
- Mischaracterizations found: [N]
- Competitor moves: [N]
- Overall sentiment: [Positive / Mixed / Negative / Trending negative]

## Signal Feed

### 🔴 Act Now
- **[RESPOND/CORRECT/ESCALATE]** | [Signal type] | [Headline]
  Context: [One sentence]
  Source: [outlet] · Reach: [estimate] · [Time since launch]
  Action: [Suggested action]

### 🟡 Monitor
...

### 🟢 Good Signals
...

## Mischaracterizations
| Claim | Source | Reach | Correct version | Status |
|---|---|---|---|---|
| [What was said] | [Source] | [Reach] | [Accurate version] | SPREADING/CONTAINED |

## Competitor Moves
- **[Competitor]:** [What they did] — [Suggested counter-move]

## Source Index
- [URL] | [Source] | [Date] | [Urgency] | [Action]

## What This Means
[2-3 sentences: what the signal pattern implies for launch trajectory; the single most important action for the team to take right now]

Saved preferences

After onboarding, ask once:

"Would you like me to save your preferences so I skip the questions next time? You can always say 'change settings' to update anything."

Store: product name(s), key competitors, launch window preference, depth setting.


Distribution

After output is rendered inline and files are saved, offer sharing following references/memory-and-distribution.md (connector detection, AskUserQuestion flow, Notion/Slack options).

Skill-specific routing: push launch-monitor-{YYYY-MM-DD}.md to Notion (full report); post Act Now signals only to Slack. Use destination from integrations in ~/.nimble/business-profile.json if set; otherwise ask and save for next time.


Re-run behavior

For date window calculation, follow the Smart Date Windowing pattern in references/nimble-playbook.md — use last_runs.launch-monitor from the profile.

If the user asks to re-run or refresh monitoring:

"I'll sweep for new signals since [last run timestamp] and update the war room. Anything new to add to the watch list?"

Only surface net-new signals since last run. Carry forward unresolved mischaracterizations and open action items.


Related skills — next steps

After delivering the war room, suggest relevant next steps in the ## What This Means section:

  • Ongoing brand monitoring: Once the active launch window closes (typically 2–4 weeks post-launch), suggest handing off to brand-mention-monitor for continuous brand health tracking — it is optimized for steady-state monitoring rather than launch spikes.
  • Competitor follow-up: If competitors made significant moves during the launch window, suggest competitor-intel for deeper, ongoing competitive intelligence — it tracks messaging, positioning shifts, and counter-narrative development over time.
  • Consumer sentiment: If the product is consumer-facing and early usage data is accumulating, suggest consumer-sentiment-monitor to track how real users are experiencing the product beyond the launch press cycle.

Materiality threshold

Skip signals that are:

  • Clearly about a different product with the same name (filter via context profiling)
  • Automated bots or spam accounts
  • Duplicate coverage with no new information (syndicated wire copy)
  • Single-digit reach with no amplification potential

Flag but don't prioritize:

  • Neutral coverage that accurately describes the product
  • Positive signals that need no action

Local Places

Location intelligence powered by Nimble Web Search Agents and web data APIs.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously:

  • mkdir -p ~/.nimble/memory/{reports,local-places/checkpoints}
  • Check for existing checkpoints: ls ~/.nimble/memory/local-places/checkpoints/ 2>/dev/null

From the results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note the user's location preferences if any. Determine mode using smart date windowing from references/nimble-playbook.md:
    • Full mode: first run OR last run > 14 days ago
    • Quick refresh: last run < 14 days ago (skip social enrichment, reviews only for new places)
    • Same-day repeat: if last_runs.local-places is today, check if a report already exists at ~/.nimble/memory/reports/local-places-*[today].md. If so, ask: "Already ran today for this area. Run again for fresh data?" Don't silently re-run.
    • Skip to Step 1
  • No profile -> that's fine. Local places doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Request & Starting Questions

Parse $ARGUMENTS for place type and location. Extract:

FieldRequiredSource
Place typeYesUser input ("coffee shops", "gyms", "restaurants")
LocationYesUser input ("Williamsburg", "downtown Austin", "Park Slope")
FiltersOptionalUser input ("with good reviews", "open late", "cheap")
Output preferenceOptionalUser input ("map", "list", "guide")

If both place type and location are clear from $ARGUMENTS, confirm briefly and proceed: "Searching for coffee shops in Williamsburg, Brooklyn..."

If partial or ambiguous, ask one combined question in plain text:

"What type of places are you looking for, and where? (e.g., 'coffee shops in Williamsburg' or 'gyms near downtown Austin')"

If the user provided both but you want to scope further, use AskUserQuestion (counts as 1 of max 2 prompts):

How thorough should this search be?

  • Quick scan -- top results from Google Maps + Yelp (~20 places)
  • Comprehensive -- full discovery + social enrichment + reviews (~50+ places)
  • Deep dive with map -- everything above + interactive neighborhood map

Step 2: Location Disambiguation

Before any API calls, resolve the location to avoid wasted searches.

Disambiguation triggers:

  • Location name exists in multiple cities/states (e.g., "Williamsburg" = Brooklyn NY vs. Williamsburg VA)
  • Location is a broad area (e.g., "downtown Austin" = multiple neighborhoods)
  • Location is informal (e.g., "Soho" = NYC vs. London)

If ambiguous, ask the user (counts toward 2-prompt max):

"There are a few places called Williamsburg. Which one?"

  • Williamsburg, Brooklyn, NY
  • Williamsburg, VA
  • Other -- I'll specify

If unambiguous, infer the full location (city + state/country) and confirm inline: "Searching Williamsburg, Brooklyn, NY..."

After disambiguation, derive the slug for checkpointing and file paths: lowercase, hyphenated, includes city + state/country (e.g., williamsburg-brooklyn-ny).

Step 3: Check for Existing Checkpoint

Follow the Checkpointing & Resume pattern from references/memory-and-distribution.md.

Check: cat ~/.nimble/memory/local-places/checkpoints/{slug}/discovery.json 2>/dev/null

  • Checkpoint found -> offer: "Found previous run ({N} places from {date}). Resume and fill gaps, or start fresh?"
  • No checkpoint -> proceed to Step 4

Step 4: WSA Discovery

Discover available WSAs for all phases before execution. Run these searches simultaneously:

nimble extract:templates list --limit 100  # then filter items for "maps"
nimble extract:templates list --limit 100  # then filter items for "reviews"
nimble extract:templates list --limit 100  # then filter items for "social"
nimble extract:templates list --limit 100  # then filter items for "{place-type}"

From the combined results:

  1. Filter by entity_type: SERP for discovery, PDP/Profile for enrichment/detail
  2. Prefer managed_by: "nimble" over managed_by: "community"
  3. Classify into phases -- see references/wsa-pipeline.md for classification strategy
  4. Validate each with nimble extract:templates get --extract-template-name {name} to confirm params
  5. Cache all discovered WSA names + validated params for the rest of the run

If no WSAs found for a phase, that phase falls back to nimble search. Log which phases had WSA coverage and which are using fallback.

Step 5: Primary Search (Phase 1)

Read references/wsa-pipeline.md for category detection logic.

Run discovered maps/location WSAs simultaneously, using the validated params from Step 4:

nimble extract:templates run --template {discovered_maps_wsa} --params '{...validated params...}'
nimble extract:templates run --template {discovered_review_site_wsa} --params '{...validated params...}'

Tertiary (conditional): Run discovered credibility WSAs only if primary + secondary return < 10 combined unique results, or if the user asked for credibility/trust data.

If any WSA fails or returns empty, fall back to: nimble search --query "[place-type] in [location]" --max-results 20 --search-depth lite

After discovery:

  1. Parse all results into a unified entity list
  2. Deduplicate following the Entity Deduplication pattern from references/nimble-playbook.md: place_id exact match -> domain normalization -> fuzzy name + city
  3. Save checkpoint: ~/.nimble/memory/local-places/checkpoints/{slug}/discovery.json

Step 6: Social Enrichment (Phase 2)

For each discovered place that has a Facebook page or Instagram handle, run the social WSAs discovered in Step 4. Batch max 4 concurrent Bash calls.

nimble extract:templates run --template {discovered_social_wsa} --params '{...validated params...}'

Run each discovered social WSA for places with matching handles. Skip social platforms for which no WSA was discovered. If no social WSAs were found in Step 4, skip this phase entirely.

Save checkpoint: ~/.nimble/memory/local-places/checkpoints/{slug}/social.json

Step 7: Reviews (Phase 3)

For the top places (by source count and data completeness), run the review WSAs discovered in Step 4:

nimble extract:templates run --template {discovered_reviews_wsa} --params '{...validated params...}'

Batch max 4 concurrent calls. Focus on places that have a place_id or equivalent identifier from Phase 1 discovery. If no review WSAs were found in Step 4, fall back to: nimble search --query "[place-name] reviews" --max-results 5 --search-depth lite

Save checkpoint: ~/.nimble/memory/local-places/checkpoints/{slug}/reviews.json

Step 8: Food/Drink Bonus (Phase 4)

Auto-trigger when the place type category matches food/drink keywords. See references/wsa-pipeline.md for the category detection logic.

If triggered, run the delivery/food WSAs discovered in Step 4. Discovery first, then detail:

nimble extract:templates run --template {discovered_delivery_serp_wsa} --params '{...validated params...}'

For places found on delivery platforms, fetch full details using discovered detail WSAs:

nimble extract:templates run --template {discovered_delivery_detail_wsa} --params '{...validated params...}'

If no delivery WSAs were found in Step 4, fall back to: nimble search --query "[place-name] [location] delivery" --max-results 3 --search-depth lite

Only run for food/drink categories. Skip if category doesn't match.

Step 9: Deduplication & Confidence Scoring

Deduplication: Run a final dedup pass across all phases following the Entity Deduplication pattern from references/nimble-playbook.md. Merge fields from multiple sources into a single enriched record per place.

Confidence scoring: Follow the Entity Confidence Scoring pattern from references/nimble-playbook.md. Skill-specific target fields (N=8):

FieldDescription
nameBusiness name
addressFull street address
phonePhone number
websiteWebsite URL
ratingAverage rating
review_countNumber of reviews
socialAt least one social profile
hoursOperating hours

Scoring criteria:

  • High (8/8 fields + 2+ sources + 10+ reviews) -> display as *** High
  • Medium (5-7/8 fields OR 2+ sources with partial data) -> ** Medium
  • Low (<=4/8 fields, single source, few/no reviews) -> * Low

Step 10: Output

Present results as a numbered table sorted by confidence (High first), then by rating within each tier.

# Local Places: [Place Type] in [Location]
*Found [N] places | [Date] | Confidence: [H] High, [M] Medium, [L] Low*

## Results

| # | Name | Rating | Reviews | Confidence | Address | Sources |
|---|------|--------|---------|------------|---------|---------|
| 1 | Place A | 4.8 (312) | *** High | 123 Main St | [Maps][Yelp] |
| 2 | Place B | 4.6 (89)  | ** Medium | 456 Oak Ave | [Maps] |
...

## Top Picks (High Confidence)

### 1. Place A
- **Address:** 123 Main St, Williamsburg, Brooklyn, NY
- **Phone:** (555) 123-4567 | **Website:** [placea.com](https://placea.com)
- **Rating:** 4.8/5 (312 reviews on Google Maps, 289 on Yelp)
- **Social:** Instagram @placea (2.1K followers) | Facebook (1.8K likes)
- **Hours:** Mon-Fri 7am-7pm, Sat-Sun 8am-6pm
- **Delivery:** Available on DoorDash, Uber Eats
- **Why it stands out:** [1-2 sentences from review highlights]
- **Sources:** [Google Maps](link) | [Yelp](link) | [Facebook](link)

[Repeat for each High confidence place]

## Other Results (Medium + Low Confidence)
[Briefer format -- name, rating, address, missing data noted]

## What's Missing
[Note any data gaps: "3 places had no website or social presence",
 "Reviews unavailable for BBB-only listings"]

Source links are mandatory. Every place must have at least one clickable source URL (Google Maps link, Yelp listing, website, or social profile). Places without any source link should be noted in "What's Missing" but still included if they have sufficient data from WSA results.

Drill-down: After presenting, tell the user:

"Want details on any place? Say 'tell me more about #3' or ask for the interactive map."

Step 11: Interactive Map (on request or "Deep dive" mode)

Generate an HTML file with Leaflet.js + OpenStreetMap tiles. See references/wsa-pipeline.md for the full map generation pattern and color scheme.

Save to: ~/.nimble/memory/local-places/{slug}-map-{date}.html

Open in browser: open ~/.nimble/memory/local-places/{slug}-map-{date}.html

Only generate automatically if the user chose "Deep dive with map" in Step 1. For map generation details, see references/wsa-pipeline.md. Otherwise, offer it as a follow-up action.

Step 12: Save to Memory

Make all Write calls simultaneously:

  • Report -> ~/.nimble/memory/reports/local-places-{slug}-{date}.md
  • Per-place data -> ~/.nimble/memory/local-places/{slug}/places.json (structured JSON with all enriched records)
  • Profile -> update last_runs.local-places in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Step 13: Share & Distribute

Always offer distribution -- do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Notion: full results table as a dated subpage. Slack: TL;DR with top 5 places only.

Step 14: Follow-ups

  • "Tell me more about #N" -> show full detail for that place
  • "Show the map" -> generate interactive map (Step 11)
  • "Add filters" -> re-search with additional constraints
  • "Search nearby area" -> expand to adjacent neighborhoods
  • "Export as CSV" -> generate CSV from places.json
  • "Looks good" -> done

Sibling skill suggestions:

Next steps:

  • Run company-deep-dive for a full 360 profile on any business from this list
  • Run meeting-prep if you're meeting with someone at one of these businesses
  • Run competitor-positioning to compare businesses in this area

Sub-Agent Strategy

For comprehensive searches (50+ places), use nimble-researcher agents (agents/nimble-researcher.md) to parallelize enrichment.

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure). For WSA calls at scale (11+ entities), tell agents to use agent run-batch instead of individual calls. See the Scaled Execution pattern in references/nimble-playbook.md for tier selection. Pass the discovered WSA names from Step 4 to each agent so they use the same cached names.

Spawn pattern: One agent per batch of 10 places for social enrichment. Each agent runs the Phase 2 WSAs for its batch and returns structured results.

Single-batch optimization: If <= 10 places, run enrichment directly from the main context instead of spawning agents -- saves overhead.

Fallback: If any agent fails, run those WSA calls directly from the main context.


Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn teammates for parallel phases:

  • Discovery teammate: Runs all Phase 1 WSAs, deduplicates, returns unified list
  • Enrichment teammate: Runs Phases 2-4 for each place batch
  • Lead (you): Coordinates, scores, generates output and map

Solo mode (flag not set): Standard sequential flow from Steps 4-7.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • WSA/Search 500: Retry once with the same params. If still failing, fall back to nimble search for that place/query. Log the failure but don't skip the place.
  • WSA/Search timeout: Retry once, then skip that call and continue — consistent with the playbook's timeout policy.
  • WSA not found: If no WSAs are discovered for a phase, skip that phase's WSA calls and fall back to nimble search. Log which phases had no WSA coverage.
  • Location not found: "Couldn't find results for [location]. Could you be more specific? Try including city and state (e.g., 'Williamsburg, Brooklyn, NY')."
  • No results for place type: "No [place type] found in [location]. Want to try a broader category or nearby area?"
  • Ambiguous place type: "Did you mean [option A] or [option B]?" (e.g., "bar" could be cocktail bar, sports bar, wine bar)

Market Finder

Market intelligence powered by Nimble Web Search Agents.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously:

  • mkdir -p ~/.nimble/memory/{reports,market-finder/checkpoints}
  • Check for existing checkpoints: ls ~/.nimble/memory/market-finder/checkpoints/ 2>/dev/null

From the results:

  • CLI missing or API key unset -> references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists -> note industry keywords if any. Apply smart date windowing from references/nimble-playbook.md. Market-finder tweak: in quick refresh mode, skip enrichment and only discover new metros.
  • No profile -> fine. Market-finder doesn't require onboarding. Proceed to Step 1.

Step 1: Parse Request & Detect Mode

Parse $ARGUMENTS for business type, geography, qualifiers, and mode detection.

Mode detection

Check $ARGUMENTS for a reference list. Read references/audit-mode.md for the full detection signals and parsing rules.

SignalMode
Google Sheet URL, CSV path, or inline list of 3+ businessesAudit
Explicit audit language ("audit my list", "compare against", "gap analysis")Audit
No reference list providedDiscovery (default)

If a reference list is present but intent is ambiguous, ask: "Want me to audit your list against fresh discovery, or use it as a starting point?"

If audit language is detected but no reference list is provided, ask: "You mentioned auditing — please provide your list (Google Sheet URL, CSV file path, or paste inline)." Do not proceed with Audit mode until a reference list is received.

Extract fields
FieldRequiredSource
Business type / verticalYesUser input ("dentists", "SaaS CRM tools")
GeographyYes (except SaaS)User input ("Florida", "Austin TX", "nationwide")
Reference listAudit mode onlyGoogle Sheet URL, CSV path, or inline
Qualification criteriaOptionalUser input ("must have website", "10+ reviews")
Output preferenceOptionalUser input ("quick summary", "full dataset")

If both type and geography are clear from $ARGUMENTS, confirm briefly and proceed: "Finding dentists in Florida..." (or "Auditing your list against dentists in Florida..." in Audit mode)

If partial or ambiguous, ask one combined question (counts as 1 of max 2 AskUserQuestion prompts):

Use AskUserQuestion with up to 3 questions:

  1. Vertical -- "What type of business?" with options: Healthcare, SaaS/Software, Restaurants/Food, Legal/Financial, Auto/Home Services, Other
  2. Geography -- "What geography?" (free text or: City, State, Region, Nationwide)
  3. Depth -- "Quick scan or comprehensive discovery?"

Skip questions already answered by $ARGUMENTS.

Depth modes (determines how much work each step does):

DepthDiscoveryEnrichmentVerificationDistribution
Quick scanAll sources, 1 passSkip (or top 5 only)Top 5 entitiesOffer
ComprehensiveAll sources + fallback retriesFullAll entitiesOffer

Step 2: Vertical Detection & Preset Loading

Read references/vertical-presets.md and match the user's business type against preset trigger keywords.

MatchAction
Clear matchLoad that preset's WSA routing and query pattern
Partial matchConfirm: "This looks like Healthcare. Use healthcare presets?"
No matchUse Custom preset with user's keywords
SaaS matchSwitch to non-geographic pipeline (no geo-tiling)

Note which discovery WSAs and enrichment WSAs the preset specifies.

Step 3: Geographic Scoping

Skip this step for SaaS vertical (no geography needed).

Geography levelTiling strategy
CitySingle query, no tiling
Metro areaSingle query per WSA
StateTile by top 5-10 metros in the state
RegionTile by states, then top metros per state
NationwideTile by all states, then top metros per state

Estimate API calls: metros * discovery_wsas * (1 + enrichment_ratio) where enrichment_ratio is ~0.3. Follow the Scaled Execution pattern from references/nimble-playbook.md to choose execution tier (individual / batch / multi-batch / confirmation gate):

Estimated API calls: ~1,560 (50 states x 8 metros x 3 WSAs + enrichment)
This is a nationwide search. Proceed? [Y/n]

Derive a slug for checkpointing: lowercase, hyphenated, includes vertical + geo (e.g., dentists-florida, saas-crm-tools, hvac-nationwide).

Step 4: Check for Existing Checkpoint

Follow the Checkpointing & Resume pattern from references/memory-and-distribution.md.

Check: cat ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json 2>/dev/null

  • Checkpoint found -> offer: "Found previous run ({N} entities from {date}). Resume and fill gaps, or start fresh?"
  • No checkpoint -> proceed to Step 5

Step 5: WSA Discovery & Execution

5a: Discover available WSAs

For each target domain in the selected vertical preset, discover current WSAs:

nimble extract:templates list --limit 100  # then filter items for "{domain}"

Run these searches simultaneously (one per target domain). From the results:

  1. Filter by entity_type (SERP for discovery, PDP/Profile for enrichment)
  2. Prefer managed_by: "nimble" over managed_by: "community"
  3. If no WSA found for a domain, mark it for nimble search fallback
  4. If no WSAs found for ANY domain, fall back entirely to nimble search for all metros

Then validate each discovered WSA's input params:

nimble extract:templates get --extract-template-name {discovered_name}

Cache the discovered WSA names + params for the rest of the run.

5b: Geographic discovery (all except SaaS)

For each metro in the tiling plan, run the discovered WSAs simultaneously:

nimble extract:templates run --template {maps_wsa} --params '{...validated params...}'
nimble extract:templates run --template {yelp_wsa} --params '{...validated params...}'

Run tertiary domain WSAs only if the preset includes them AND primary + secondary return < 10 combined unique results for that metro.

Choose execution tier per the Scaled Execution pattern in references/nimble-playbook.md (based on total estimated calls from Step 3).

5c: SaaS discovery (non-geographic)

SaaS skips WSA discovery. Run the two-pass search queries defined in the SaaS preset from references/vertical-presets.md:

  • Pass 1 -- Product discovery: G2, Capterra, general, ProductHunt, GitHub
  • Pass 2 -- Financial discovery: Crunchbase, funding news, market landscape

Both passes run simultaneously. Pass 2 is critical -- without it, funding and traction data will be missing or wrong.

5d: Fallback

If no WSA was found for a target domain, or if a WSA fails for any metro:

nimble search --query "[type] in [metro]" --max-results 20 --search-depth lite

After discovery:

  1. Parse all results into a unified entity list
  2. Deduplicate following the Entity Deduplication pattern from references/nimble-playbook.md: place_id -> domain -> fuzzy name + city
  3. Track source_count per entity (how many WSAs/sources found it)
  4. Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json

Step 6: Enrichment

Run enrichment using the WSAs discovered in Step 5a for the preset's enrichment target domains. Prioritize entities with the highest source count first. Choose execution tier per Scaled Execution in references/nimble-playbook.md.

nimble extract:templates run --template {enrichment_wsa} --params '{...validated params...}'

Only run enrichment WSAs that apply to the current vertical's enrichment targets (see references/vertical-presets.md). Skip entities without the required ID/URL for the enrichment WSA.

Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/enrichment.json

Step 6b: Financial Verification (SaaS vertical)

For SaaS entities, verify funding claims before reporting. Never label a company's funding stage without a source.

For each entity in the top results (top 5 in quick scan, all in comprehensive):

nimble search --query "{company name} funding raised series" --max-results 5 --search-depth lite
  • Source found: Use the sourced amount and date
  • No source found: Display "Undisclosed" -- never guess "Early stage" or "Bootstrapped"

This step prevents publishing unverified financial claims. It's fast (one search per entity, lite depth) and catches recent funding rounds that directory sites miss.

Step 7: Deduplication & Scoring

Final deduplication: Run a final dedup pass across all phases following the Entity Deduplication pattern from references/nimble-playbook.md. Merge fields from multiple sources into a single record per entity.

Discovery strength scoring (skill-specific, varies by vertical):

Geographic verticals (Healthcare, Restaurants, Legal, Auto/Home, Custom):

LevelCriteria
High3+ sources OR 2+ sources with reviews > 50
Medium2 sources OR 1 source with reviews > 10
Low1 source only, few/no reviews

SaaS vertical (funding + directory presence matter more than review count):

LevelCriteria
HighVerified funding > $10M OR 3+ directory sources OR 1000+ G2 reviews
MediumVerified funding < $10M OR 2 sources OR 100+ G2 reviews
Low1 source only, no verified funding, few reviews

Display as: *** High, ** Medium, * Low

Step 7b: Audit Comparison (Audit mode only)

Skip this step in Discovery mode.

Read references/audit-mode.md for the full matching algorithm, normalization rules, and output template.

  1. Parse reference list — detect format (Google Sheet / CSV / inline), extract records, normalize to {name, domain, city, state, phone} per the parsing rules in references/audit-mode.md
  2. Run three matching layers in order (domain → name+city → phone). Once an entity matches at any layer, stop. Track which layer produced the match.
  3. Categorize every entity:
    • matched — in both reference list and discovery results
    • discovered_only — found by discovery, not in reference list
    • reference_only — in reference list, not found by discovery
  4. Calculate coverage score — matched / reference_count × 100

Proceed to Step 8 with the categorized results.

Step 8: Output

# Market Finder: [Business Type] in [Geography]
*Found [N] businesses | [Date] | Strength: [H] High, [M] Medium, [L] Low*

## Summary
- **Total discovered:** [N] unique businesses across [M] metros
- **Geographic breakdown:** [top 5 metros by count]
- **Source coverage:** [list each source used with entity counts]

## Top Results (High Strength)

| # | Name | Location | Rating | Reviews | Strength | Sources |
|---|------|----------|--------|---------|----------|---------|
| 1 | Acme Dental | Miami, FL | 4.8 | 312 | *** High | Maps, Yelp, BBB |
| 2 | WidgetCo Health | Orlando, FL | 4.6 | 89 | *** High | Maps, Yelp |
...

## All Results by Geography

### Miami, FL ([n] businesses)
[Table of businesses in this metro]

### Orlando, FL ([n] businesses)
[Table of businesses in this metro]
...

## What's Missing
[Data gaps: metros with low coverage, entities without websites, etc.]

SaaS output variant (when vertical is SaaS, replace "All Results by Geography" with tier-based grouping):

## Players by Tier

### Pure-Play (dedicated to this vertical)
| # | Name | Domain | Funding | Key Metric | Strength | Sources |
...

### Adjacent (feature overlap from larger platforms)
| # | Name | Domain | Funding | Key Metric | Strength | Sources |
...

### Open Source
| # | Name | Repo | Stars | Key Metric | Strength | Sources |
...

Source links are mandatory. Every entity must have at least one clickable source URL (Google Maps link, Yelp listing, website, BBB profile, G2 page, or GitHub repo).

Audit output variant (when in Audit mode, replace the Discovery output above): Use the audit output template from references/audit-mode.md. Key sections: Summary with coverage score, Matched table, Discovered Only table (expansion candidates), Reference Only table (coverage gaps), and "What This Means" interpretation.

Step 9: Save to Memory

Make all Write calls simultaneously:

Discovery mode:

  • Report -> ~/.nimble/memory/reports/market-finder-{slug}-{date}.md
  • Entity data -> ~/.nimble/memory/market-finder/{slug}/entities.json

Audit mode:

  • Report -> ~/.nimble/memory/reports/market-finder-audit-{slug}-{date}.md
  • Structured data -> ~/.nimble/memory/market-finder/{slug}/audit-{date}.json (all three categories with match metadata)

Both modes:

  • Profile -> update last_runs.market-finder in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.
  • Clean up checkpoint (complete run) or keep (partial run)

Step 10: Share & Distribute

Always offer distribution -- do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Notion: full results table as a dated subpage. Slack: TL;DR with total count + top 10 entities only.

Step 11: Follow-ups

Discovery mode follow-ups:

  • "Tell me more about #N" -> show full detail for that entity
  • "Filter by [criteria]" -> re-filter existing results
  • "Expand to [new geography]" -> add metros and re-run discovery
  • "Export as CSV" -> generate CSV from entities.json
  • "Run enrichment on all" -> extend enrichment beyond top entities
  • "Audit against my existing list" -> switch to Audit mode with this run's results
  • "Looks good" -> done

Audit mode follow-ups:

  • "Export discovered-only as CSV for outreach?" -> CSV of expansion candidates
  • "Investigate reference-only gaps?" -> targeted searches for reference_only entries
  • "Run company-deep-dive on new discoveries?" -> deep research on discovered_only
  • "Re-run with a different geography?" -> audit the same list against a new area
  • "Looks good" -> done

Sibling skill suggestions:

Next steps:

  • Run company-deep-dive for a full 360 profile on any business from this list
  • Run competitor-positioning to compare top players in this market
  • Run local-places for neighborhood-level discovery with social enrichment and maps

Sub-Agent Strategy

For large jobs, nimble extract:templates batch handles WSA parallelism server-side (see Scaled Execution in references/nimble-playbook.md). Sub-agents are useful for preparing batch inputs and processing results, not for running individual WSA calls.

Use nimble-researcher agents (agents/nimble-researcher.md) when:

  • Building metro query lists for large geographies (one agent per state)
  • Processing and deduplicating batch results in parallel

Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, fallback on failure).


Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn teammates for parallel phases:

  • Discovery teammate(s): Run all discovery WSAs across metro batches
  • Enrichment teammate: Run enrichment WSAs for top entities
  • Lead (you): Coordinate, scope, deduplicate, score, generate output

Solo mode (flag not set): Standard sequential flow from Steps 5-8.


Error Handling

See references/nimble-playbook.md for the standard error table (missing API key, 429, 401, empty results, extraction garbage). Skill-specific errors:

  • WSA not found: Skip silently and rely on other discovery sources. Log which WSAs were unavailable.
  • Search 500/timeout: Retry once without --focus flag. If still failing, retry with a simplified query. Log the failure but don't skip the entire search category -- partial data is better than none.
  • No results for metro: "No [type] found in [metro]. Skipping to next metro." Don't abort the entire job for one empty metro.
  • Ambiguous business type: "Did you mean [option A] or [option B]?" (e.g., "practice" could be medical, dental, legal)
  • SaaS with geography: If the selected preset has no geo-tiling but the user specified a geography, offer it as a search qualifier instead.
  • Reference list parse failure: If Google Sheet extraction returns garbage or CSV is malformed, ask the user to paste the data inline instead.
  • Empty reference list: If parsed list has 0 valid records, warn and offer to switch to Discovery mode.
  • No matches found: If all three matching layers produce zero matches, report it — a 0% coverage score is valid and informative.

Meeting Prep

Research-powered meeting preparation with attendee intelligence and company context.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

From the results:

  • CLI missing or API key unset → references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists → read ~/.nimble/memory/people/index.md to identify existing person profiles. Load relevant ~/.nimble/memory/people/ files for attendees before — skip redundant searches, surface prior meeting notes. Follow [[path/entity]] cross-references in person files: if an attendee's file links to [[competitors/widgetco]], load that competitor file for richer context (e.g., recent intel from competitor-intel runs). Also check ~/.nimble/memory/companies/ for cached company research. No same-day report check — meeting-prep is per-meeting, not per-day. Users may prep for multiple meetings in one day. Instead, check entity freshness: if a person/company profile was updated within the last 24 hours, offer to reuse it: "I have a recent profile for [Name] from earlier today. Use it, or refresh?"
  • No profile → that's fine. Meeting prep doesn't require onboarding. Proceed to Step 1.

Step 1: Gather Meeting Context

Parse the meeting details from $ARGUMENTS or ask the user.

Calendar shortcut: If the user didn't specify attendees and a calendar connector is available — either a calendar MCP tool (look for list_events in the tool list) or the gws CLI (gws calendar +agenda --today) — offer to pull today's meetings so they can pick one. If neither is available, skip this silently.

If clear (e.g., "prep me for my meeting with Alex Kim at WidgetCo tomorrow"):

  • Extract: attendee name(s), company, meeting date/time (if given)
  • Confirm briefly: "Preparing briefing for your meeting with Alex Kim at WidgetCo..."

If partial (e.g., "prep me for my meeting tomorrow"):

  • Ask one clarifying question in plain text:

    "Who are you meeting with? (names, titles, and company if you have them)"

If just a person (e.g., "research John Smith"):

  • Proceed with the person. Try to infer their company from search results.

Extract these fields:

FieldRequiredSource
Attendee name(s)YesUser input or calendar event
CompanyPreferredUser input or inferred from search
Attendee title(s)OptionalUser input or discovered in Step 2
Meeting typeRequiredUser input, inferred, or asked (discovery, demo, check-in, interview, partnership, internal)
Meeting date/timeOptionalUser input
Additional contextOptionalUser notes ("they're evaluating our product", "board member intro")

Meeting type detection — if the user doesn't specify, infer from context clues:

SignalInferred type
"prospect", "demo", "sales call"Sales / discovery
"interview", "candidate"Interview
"board", "investor"Board / investor
"partner", "integration"Partnership
"check-in", "sync", "1:1" with colleagueInternal
No signalAsk (see below)

If no signal — don't guess "general external." The meeting type gates whether the Value Positioning section is generated, so it's worth one question. Use AskUserQuestion:

What's the goal of this meeting?

  • Sales / discovery — pitching, demo, exploring fit
  • Partnership — integration, co-selling, joint venture
  • Board / investor — board meeting, investor update, fundraising
  • Interview — evaluating a candidate
  • General / other — networking, catch-up, or not sure

Map the answer to the meeting type. If the user picks "General / other", treat as general external (no value positioning section).

The meeting type shapes the briefing focus — specifically, it determines whether the Value Positioning section (Step 4.5 + Step 6) is generated. Value positioning activates for: sales/discovery, partnership, board/investor. It is skipped for: interview, internal, general external.

Step 2: WSA Discovery

Discover available WSAs for each attendee's company domain:

nimble extract:templates list --limit 100  # then filter items for "{company-domain}"

Run one search per unique company simultaneously. Filter for SERP/PDP WSAs, prefer managed_by: "nimble", validate with nimble extract:templates get --extract-template-name {name}. Cache discovered names + params. Pass them to attendee agents in Step 3 for richer data. If no WSAs found, continue with nimble search alone.

Step 3: Per-Attendee Research (sub-agents)

Read references/attendee-agent-prompt.md for the full agent prompt template. Follow the sub-agent spawning rules from references/nimble-playbook.md (bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Check memory first. For each attendee, check ~/.nimble/memory/people/[name-slug].md. If a profile exists and is < 30 days old, load it as known context and pass it to the agent so it focuses on what's new. If > 30 days old, run a full refresh.

Spawn nimble-researcher agents (agents/nimble-researcher.md) with mode: "bypassPermissions". One agent per attendee. Pass discovered WSA names from Step 2 to each agent for enrichment.

Important: The Nimble API has a 10 req/sec rate limit per API key. With each agent running 4-5 searches, limit concurrent agents to 2 per batch. For 3+ attendees, batch in groups of 2.

Call estimation & Scaled Execution: Before launching agents, estimate total API calls: ~5 searches per attendee + ~4 company searches + 3-5 extractions = ~(5 × N) + 9 calls. For 3+ attendees (15+ calls), tell agents to use extract-batch for page extractions instead of individual calls. See the Scaled Execution pattern in references/nimble-playbook.md for tier selection.

Batch 1 (2 agents simultaneously):

  • Attendee 1 research
  • Attendee 2 research

Batch 2 (if needed):

  • Attendee 3 research
  • Attendee 4 research

Single attendee optimization: If only one person, run the searches directly from the main context instead of spawning an agent — saves overhead.

Fallback: If any agent fails or returns empty, run those searches directly from the main context. Don't leave gaps in the briefing.

Step 3.5: Gap Check

Before proceeding, verify every attendee has at least a title and company confirmed.

For any attendee with < 3 meaningful results or "Role Unknown":

  1. Run a --focus social fallback search directly (this searches social platform people indices and is the most reliable way to find someone): nimble search --query "[Name] [Company]" --focus social --max-results 5 --search-depth lite
  2. If --focus social is unavailable, fall back to: nimble search --query "[Name]" --include-domain '["linkedin.com"]' --max-results 5 --search-depth lite
  3. Try name variations: "[First] [Last]", "[Full Name] [Company] [Title if known]"

Do NOT present a briefing with "Role Unknown" — exhaust social search first. If still nothing after fallbacks, note it honestly: "Limited public presence — could not confirm role. Consider asking for their LinkedIn URL."

Also collect LinkedIn profile URLs for each attendee during this step if not already found. These are high-value for the final briefing output and Notion distribution.

Step 4: Company Research

Research the attendees' company for meeting-relevant context. This is a lighter version of company-deep-dive — focused on what's useful for the conversation, not a full 360°.

Company name quoting: If the company name contains common words that cause noisy results (e.g., "Acme Supply", "Nova Dynamics", "Global Industries"), wrap it in escaped quotes: "\"Acme Supply\" news". Use --include-domain '["[domain]"]' as an alternative anchor.

Make these Bash calls simultaneously:

  • nimble search --query "\"[Company]\" news" --focus news --start-date "[14-days-ago]" --max-results 8 --search-depth lite
  • nimble search --query "\"[Company]\" product launch OR announcement" --focus news --start-date "[14-days-ago]" --max-results 5 --search-depth lite
  • nimble search --query "about" --include-domain '["[domain]"]' --max-results 3 --search-depth lite
  • nimble search --query "\"[Company]\" funding OR raised OR investors" --max-results 5 --search-depth lite

If your user's company profile exists, also run:

  • nimble search --query "[Company] [UserCompany] OR [user-domain]" --max-results 5 --search-depth lite

This catches any existing relationship between the two companies — prior partnerships, mentions, shared investors, or competitive overlap.

If < 3 results from the news searches, retry without --start-date.

Date validation: When including company news in the briefing, verify that the event date (when something actually happened) is recent, not just the article date. See references/nimble-playbook.md → "Signal Date Validation" for details. If a snippet uses past-tense language like "last year" or "back in Q3", treat it as background context rather than recent news.

If the company was already researched (exists in ~/.nimble/memory/companies/), load the existing profile and only run the news search for fresh updates.

Step 4.5: Value Positioning Research

Skip this step if the meeting type is interview, internal, or general external.

This step cross-references what you learned about the attendee's company (Step 4) with the user's own business profile to find concrete positioning angles. It works best when business-profile.json exists with at least company.name and company.domain.

If no profile exists, skip searches that reference the user's company or competitors (searches 2, 4, 5) and rely on generic research (searches 1, 3) for positioning insights. Use any WSAs discovered in Step 2 for richer attendee company data. The Value Positioning section will be thinner but still useful — pain-to-solution mapping and tech stack discovery work without a profile.

Load the user's sales context from ~/.nimble/business-profile.json:

  • sales_context.key_differentiators — what makes the user's product unique
  • sales_context.integration_partners — tools the user's product connects with
  • sales_context.case_studies — similar customers and outcomes
  • sales_context.common_objections — pre-built objection responses
  • competitors — tracked competitors (check if the attendee's company uses any)

If sales_context doesn't exist in the profile, the skill still works — the value positioning section will rely on web research alone rather than profile-enriched data. Mention at the end: "Tip: Add sales context to your profile for richer positioning next time."

Make these Bash calls simultaneously (3-5 searches depending on available data):

  1. nimble search --query "\"[AttendeeCompany]\" tech stack OR tools OR platform OR uses" --max-results 5 --search-depth lite → Discover what tools/platforms they use — match against integration_partners

  2. nimble search --query "\"[AttendeeCompany]\" [UserCompany] OR [user-domain]" --max-results 5 --search-depth lite → Any existing relationship, mentions, or competitive overlap (skip if already run in Step 3)

  3. nimble search --query "\"[AttendeeCompany]\" challenges OR pain points OR struggling OR migrating" --max-results 5 --search-depth lite → Pain signals to map against user's value props

  4. (If competitors list exists) nimble search --query "\"[AttendeeCompany]\" [CompetitorName1] OR [CompetitorName2]" --max-results 5 --search-depth lite → Check if they use a competitor — critical for displacement positioning

  5. (If case_studies exist with matching industry) nimble search --query "[UserCompany] [attendee-industry] case study OR customer story" --max-results 5 --search-depth lite → Find published case studies in the attendee's industry to reference

From the results, extract:

  • Tools/platforms they use (for integration hooks)
  • Pain signals or challenges (for value mapping)
  • Competitor usage (for displacement angles)
  • Industry match to existing case studies (for social proof)

This data feeds directly into the Value Positioning section in Step 5.

Step 5: Deep Extraction

From Steps 3-4.5, identify the top 3-5 most informative URLs across all results. Prioritize:

  • Attendee's own LinkedIn posts, articles, or talks
  • Recent company announcements directly relevant to the meeting
  • Interviews or profiles of the attendee
  • The company's about/team page (if attendee title wasn't found)
  • (If value positioning active) Pages revealing their tech stack or tool usage
  • (If value positioning active) Articles about their challenges or migration plans

Make one Bash call per URL, all simultaneously:

nimble extract --url "https://..." --format markdown

For extraction failures, follow the fallback in references/nimble-playbook.md.

Single attendee + known company: Skip company extraction, focus on person URLs. Multiple attendees: Prioritize person-specific URLs over company-level ones.

Step 6: Synthesize Briefing

Structure the output as a meeting prep briefing. Adapt focus based on meeting type.

# Meeting Prep: [Company Name]
*[Meeting date/time if known] | Prepared [today's date]*

## Quick Take
[2-3 sentences: who you're meeting, why it matters, and the one thing to know
going in. This is the "read nothing else" paragraph.]

## Attendees

### [Name] — [Title]
**Background:** [Current role, time in position, career trajectory highlights]
**Recent Activity:** [What they've been posting, speaking about, or working on.
  Direct quotes from posts/talks when available.]
**Conversation hooks:** [2-3 specific things to reference — shared connections,
  their recent project, a post they wrote, a talk they gave]
**Notes from prior meetings:** [If exists in memory — what was discussed, their
  preferences, open items. "No prior meetings on file" if none.]

[Repeat for each attendee]

## Relationship Map
[Cross-attendee connections — shared employers, mutual connections, overlapping
  interests, organizational dynamics between attendees. Skip if single attendee.]

## Company Context
- **What they do:** [One line]
- **Size / Stage:** [Employees, funding stage, HQ]
- **Recent news:** [Top 2-3 items, dated with source]
- **Relevant to your meeting:** [How their company context connects to your
  discussion — e.g., recent product launch you might discuss, funding that
  signals growth, leadership change affecting priorities]

## Value Positioning
*[Only for sales/discovery, partnership, and board/investor meetings. Omit entirely
  for interview, internal, and general external meetings.]*

### Value Mapping
[Match their specific needs/pain points to your capabilities. Every mapping must
  be grounded in research from Step 4.5, not generic claims.
  Format: "They [specific finding with source] → Your product [specific capability]"]

### Integration Hooks
[Tools/platforms they use that your product integrates with. Only include
  integrations confirmed from research (their tech stack) AND your profile
  (integration_partners). If no overlap found, say so honestly.]

### Recommended Positioning
[2-3 sentences on how to frame your pitch for THIS specific company and person.
  Consider: their company stage, recent news, the attendee's role and priorities,
  and any competitive displacement opportunity. This is the "elevator pitch
  calibrated to this meeting" paragraph.]

### Reference Customers
[Similar companies from your case_studies that match their industry, size, or
  use case. Include the outcome/metric if available. If no matching case studies,
  omit this subsection rather than forcing a weak match.]

## Talking Points
[3-5 specific, actionable conversation starters grounded in the research.
  Not generic "ask about their priorities" — specific: "Ask about their
  migration from [old tool] to [new tool] that they announced last month."
  When value positioning is active, weave 1-2 positioning angles into the
  talking points naturally — don't make every talking point a sales pitch.]

## Watch Out For
[1-3 things to be aware of — sensitive topics (recent layoffs, bad press),
  potential awkward overlaps, information gaps you couldn't fill.]

## Sources
[Numbered list of key URLs cited in the briefing]

Meeting type adaptations:

TypeEmphasisAdd to briefingValue Positioning
Sales / discoveryBuyer authority, pain signals, competitive stack"Qualification signals" sectionYes — full section
PartnershipMutual benefit signals, integration opportunities"Alignment opportunities" sectionYes — focus on integration hooks
Board / investorFinancial context, market position, portfolio overlap"Key metrics to reference" sectionYes — focus on recommended positioning
InterviewCandidate's work history depth, cultural signals"Assessment angles" sectionNo
InternalSkip company research, focus on person's recent workLighter format, no company sectionNo
General externalBalanced across all dimensionsStandard format aboveNo

Core rules:

  • Every factual claim about an external company or person must have a source URL. Data drawn from the user's own business profile (differentiators, integrations, case studies) should be attributed to the profile rather than requiring an external source.
  • Lead with the Quick Take — most readers stop there.
  • Talking points must be specific to THIS meeting, grounded in research findings. Never generate generic conversation starters.
  • Say "no public information found" for a person rather than speculating about their role or background.
  • If memory has prior meeting notes, surface open items and continuity points prominently — this is the highest-value content.
  • Value Positioning claims must be grounded in research from Step 4.5. Never generate generic positioning advice like "highlight your product's strengths." Every value mapping must reference a specific finding about the attendee's company paired with a specific capability from the user's profile or research.
  • If sales_context is missing from the profile, note it once at the end of the Value Positioning section: "Tip: Edit your profile at ~/.nimble/business-profile.json to add sales context (differentiators, integrations, case studies) for richer positioning next time."

Step 7: Save to Memory

Make all Write calls simultaneously:

  • Report → ~/.nimble/memory/reports/meeting-prep-[company-slug]-[date].md
  • Per attendee → ~/.nimble/memory/people/[name-slug].md (use the format in references/memory-and-distribution.md). Add [[path/entity]] cross-references for the attendee's employer (e.g., [[competitors/widgetco]] or [[companies/widgetco]]) and any other discovered relationships.
  • Company profile → update ~/.nimble/memory/companies/[company-slug].md if new company data was found. Add reverse cross-references to the people researched (e.g., [[people/alex-kim]]).
  • Profile → update last_runs.meeting-prep in ~/.nimble/business-profile.json (only if profile exists)
  • Follow the wiki update pattern from references/memory-and-distribution.md: update index.md rows for all affected entity files, append a log.md entry for this run.

The person profile in people/ should contain structured key facts (role, background, interests, communication style) that can be loaded by future meeting prep runs.

Step 8: Share & Distribute

Always offer distribution — do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Step 9: Follow-ups

  • Go deeper on an attendee → more focused person research
  • Add attendees → research additional people joining the meeting
  • "What about [topic]?" → targeted search on specific dimension
  • "Looks good" → done
  • Sibling skills: company-deep-dive for a full 360 on the company, competitor-intel to track them as a competitor, competitor-positioning to compare messaging before a sales meeting

Agent Teams Mode (Dual-Mode)

Check at startup: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Team mode (flag set): Spawn teammates instead of sub-agents. Each teammate researches one attendee and can message the others when finding cross-connections.

TeammateFocusCross-checks with
Attendee 1 researcherFull person + company research for attendee 1All other teammates (shared employers, connections)
Attendee 2 researcherFull person + company research for attendee 2All other teammates
[Additional per attendee]......

How cross-attendee discovery works:

  1. Each teammate researches their assigned attendee independently
  2. When a teammate discovers a workplace, school, or connection that overlaps with another attendee, they send a message to that teammate: "My attendee [Name] worked at [Company] from 2019-2022 — did yours overlap?"
  3. The receiving teammate checks and responds
  4. Lead (you) collects all cross-references and builds the Relationship Map section

This produces higher-quality relationship maps than solo mode because teammates actively search for connections rather than just comparing results post-hoc.

Solo mode (flag not set): Standard sub-agent flow from Step 3.


What This Skill Is NOT

  • Not competitor monitoring — use competitor-intel for tracking competitors
  • Not a company deep dive — use company-deep-dive for research without attendees
  • Not a CRM — gathers web intelligence, doesn't manage contacts or pipelines
  • Not a calendar app — reads events for context but doesn't manage them

Error Handling

See references/nimble-playbook.md for the standard error table. Skill-specific errors:

  • Person not found: Try name variations (full, first+last, with company). If still nothing: "Couldn't find public info on [Name]. Can you share their title or LinkedIn?"
  • Ambiguous name: Present top candidates with company/title context and ask.
  • Empty company results: Note it and focus on attendee-level findings.

Nimble on Databricks — data products builder

Turn a natural-language brief like pricing analysis on dog products from walmart and amazon into working Databricks data products: discover agents → ingest live web search data into Delta → build dashboard and/or app → deliver links. Equally at home for a quick demo or a real, reusable data product.

You are the orchestrator. Databricks mechanics are delegated to the official databricks-* skills (see references/databricks-skills.md); this skill owns the Nimble glue and the gaps (agent discovery, ingestion-from-agents, the AI/BI dashboard JSON, branding).

Golden rules

  • Discover, don't assume. Read agent names via nimble_agent_list(), input params via nimble_agent_describe('<agent>'), and output fields by probing one call (to_json(parsing[0])) — never hardcode from memory (Amazon search takes keyword, not query).
  • Probe before fanning out. Run one call per source first to learn its localization flag, field names, and value formats — sources differ (some return numeric prices, others currency strings).
  • One statement per Statements API call. Multiple ;-separated statements in one call are a parse error.
  • Each Bash call is a fresh shell. Env vars and cd don't persist — set them inline. See references/preflight.md.
  • Fail fast, then confirm. Run Phase 0 preflight first; recommend a warehouse + writable schema, then confirm before writing.
  • Always ask the deliverable. Table / +dashboard / +app is a per-run choice.
  • Branding is always on, neutral. "Powered by Nimble" + light theme + yellow accent. See references/branding.md.
  • Leave artifacts in place. No teardown.
  • Show your work and the headline. End with URLs and the one-sentence insight (e.g. the price gap).

Workflow

Track these as todos so nothing is skipped.

Phase 0 — Preflight (read-only, fail fast)

Lean on the databricks-core skill for the generic checks.

  1. databricks current-user me → confirm auth; capture the username (for the default schema).
  2. Find a RUNNING SQL warehouse: databricks warehouses list. Prefer one already RUNNING; if none, offer to start one.
  3. Integration gate — confirm these exist: nimble_integration.tools.{nimble_search, nimble_extract, nimble_agent_run, nimble_agent_list, nimble_agent_describe}. Quick check: databricks functions list nimble_integration tools. If missing → STOP and walk the user through references/install-nimble-integration.md (Nimble cookbook). Do not try to auto-install.
  4. Recommend + confirm the target: a warehouse and a writable catalog.schema (default users.<username>). Verify writability — some shared catalogs deny CREATE TABLE. Present the recommendation and let the user confirm or override before writing.

Details + exact commands: references/preflight.md.

Phase 1 — Interpret the brief + clarify (AskUserQuestion)

Parse the brief into: domain/entity · search terms · sources · analysis goal. Then ask (batch into one AskUserQuestion call):

  • Deliverable — always ask: table / table + dashboard / table + dashboard + app.
  • Sources — confirm the agents you matched (e.g. Amazon + Walmart SERP).
  • Volume — default ~8–10 search terms, ~100+ rows/source.

Keep the brief's intent (the "analysis goal") — it picks the Phase 4 template and the headline.

Phase 2 — Discover agents + map a unified schema

See references/nimble-agents.md.

  1. nimble_agent_list() via SQL, filter by the source/domain keywords.
  2. For each chosen agent: nimble_agent_describe('<name>') → read its input params (required ones, exact names, localization/pagination flags). Output fields come from the §2.5 probe, not here.
  3. Design one unified table with a source column + a normalized core (product_name, price, currency, rating, review_count, brand, url, …), keeping only fields the chosen agents actually emit. Multi-source comparison hinges on the shared columns.

Phase 3 — Ingest (control table + one set-based call)

See references/nimble-agents.md for the full SQL. Drive ingestion from a control table, not per-keyword files — it's reproducible and expandable (add a row, re-run). 0. Probe ONE call per source first (fail fast). Before fanning out, run a single nimble_agent_run per source and check: status, the real field names, the localization flag, and whether a price casts cleanly. This catches the Walmart-class surprises (localization, currency- string prices, product_price vs price) in ~40s instead of after a wasted full round. Highest- leverage step — see nimble-agents.md §2.5.

  1. Create a control (queries) table <schema>.<table>_queries (source, agent, keyword, params_json, localization, enabled) and seed one row per (source × term). params_json uses each agent's real param name (from input_properties); set localization per agent (e.g. amazon_serp true, walmart_serp false).
  2. Create the unified results table (source column + normalized core + raw VARIANT).
  3. Run one INSERT that calls nimble_agent_run(q.agent, q.params_json, q.localization) via a correlated LATERAL join over the control table, with a /*+ REPARTITION(N) */ hint (N ≈ enabled rows, kept modest — high parallelism can trip API rate limits) so the agent calls run in parallel. It's one long statement → run it async with bash scripts/ingest.sh <WH> ingest.sql.
  4. Reconcile against the control table (LEFT JOIN): a term that lands no items returns an empty result, and a correlated LATERAL drops empty rows — so reconcile to confirm every source is covered. If a source shows 0, re-check its localization flag (per-agent) and casts before building; see nimble-agents.md §6 for the diagnostic order.

Phase 4 — Build the deliverable(s)

Choose a template from the matched agents' vertical/entity_type:

VerticalDashboard/app shape
Ecommerce (SERP/PDP/CLP)KPIs; listings & avg price by source/keyword; sponsored share; price-vs-rating scatter; product table with Open links; multi-source → comparison bars + best-effort item-level price gap
Socialvolume/engagement by account/post; top-content table; like/follower distributions
Real Estateprice & price/sqft; listings by location; beds/baths breakdowns
Maps / Localavg rating; review counts; places table
LLM / AEOsource/answer presence; share-of-voice; citation table
fallbackKPIs + 2 categorical bars + the raw table (works off any output_schema)

Comparison depth (hybrid): always build the aggregate/category comparison; additionally try best-effort item-level matching across sources (normalize brand + key tokens). If confident matches exist, add a "same-product price gap" view; otherwise keep the aggregate comparison and note that item-level matching wasn't confident.

  • Dashboard → use scripts/build_dashboard.py (compact spec → valid serialized_dashboard, create + publish). It bakes in every Lakeview gotcha. Read references/dashboard-cookbook.md for the spec format and recipes.
  • App → follow references/app-cookbook.md (delegates scaffold/deploy to databricks-apps; adds the Nimble-specific SQL, branding, and the numeric-string / light-mode gotchas).
  • Branding → references/branding.md (always applied).

Phase 5 — Verify, deliver & share

  • Publish the dashboard / confirm the app is RUNNING; collect URLs.
  • Summarize what was built and the headline insight (the comparison takeaway).
  • Offer to share the dashboard/app link — if a Slack or Notion connector is available, offer to post it there (Slack = the link + headline; Notion = a short dated page). Mention once; don't nag.
  • Suggest next steps with sibling skills, e.g. competitor-intel / company-deep-dive for business signals on the brands surfaced, or nimble-web-expert for a one-off deeper pull.
  • Offer iterations (more charts, item-level matching, theming, a scheduled refresh job).

Reference map

  • references/databricks-skills.md — which official databricks-* skill to use per phase.
  • references/install-nimble-integration.md — setup when the integration gate fails.
  • references/preflight.md — auth, warehouse, writable-schema discovery (exact commands).
  • references/nimble-agents.md — discovery, schema mapping, ingestion SQL + gotchas.
  • references/dashboard-cookbook.md — Lakeview JSON recipes + every gotcha (authoritative).
  • references/app-cookbook.md — AppKit demo app glue + gotchas.
  • references/branding.md — "Powered by Nimble", logo, colors.
  • scripts/ingest.sh — async statement fan-out + poll.
  • scripts/build_dashboard.py — compact spec → create + publish a dashboard.
  • assets/nimble-logo.png — the Nimble mark for app branding.

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.

CapabilityWhat it isCommand family
SearchReal-time web search — raw results (pages, snippets), 8 focus modesnimble search
ExtractFetch + parse a single known URL (the one-off primitive)nimble extract
Extraction TemplateReusable, site-specific structured scraper for a known item (by URL or identifier)nimble extract:templates
Web Search AgentOpen-ended research / enrichment / dataset building — discovers sources, synthesizes, citesnimble agents / agents:runs
MapDiscover the URLs that exist on a sitenimble map
CrawlBulk-fetch many pages across a site (one-time, at scale)nimble crawl

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?

User signalRoute
Direct single URL to fetchnimble extract
Named site + a direct item to look up (URL/ID)Step 0 — check for an Extraction Template first
"Find URLs / sitemap / all pages"nimble map
"Crawl / archive a whole section"nimble crawl
No location signal at allFall through to Gate B
Named site with no templateFall through to Gate B, carrying the site as a source constraint

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.

→ Web Search Agent→ nimble search
report, brief, analysis, landscape, teardown, deep divefind, search for, look up
compare, "best X", "which should I", "state of", recommend"pages/articles about", "links to"
enrich, build a list, dataset, "…with their pricing/headcount"latest news, recent posts, what's trending

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.

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.

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.


Workflow

SituationCommandReference
Site + item → template firstextract:templates list → extract:templates runreferences/nimble-extract-templates/reference.md
Research / enrichment / datasetpick a run mode → get → resultreferences/nimble-agents/reference.md
Direct URLnimble extractreferences/nimble-extract/reference.md
Search the live webnimble searchreferences/nimble-search/reference.md
Discover URLs on a sitenimble mapreferences/nimble-map/reference.md
Bulk crawl a sectionnimble crawl runreferences/nimble-crawl/reference.md
Batch templates (up to 1,000)nimble extract:templates batchreferences/nimble-extract-templates/reference.md
Batch extract (up to 1,000)nimble extract-batchreferences/nimble-extract/reference.md
Poll tasks / batches / resultsnimble tasks / nimble batchesreferences/nimble-tasks/reference.md
Unknown selectors or XHR pathbrowser-use or Playwright investigationreferences/nimble-extract/browser-investigation.md
Proven site patternscopy a recipereferences/recipes.md
2+ inputsparallel bash &+wait or generated scriptreferences/batch-patterns.md

For the full extract waterfall (tiers, flags, browser actions, network capture), see references/nimble-extract/reference.md.


Response shapes

CommandOutput
nimble extract:templatesRecords per the template's output_schema — array (list/SERP) or object (detail/PDP)
nimble agents:runs resultoutput (type:"text" prose or type:"json" structured) + trust per-claim citations
nimble extractHTML, Markdown, or parsed JSON — depends on --format and --parse
nimble searchStructured results array (title, URL, description)
nimble mapURL list + metadata
nimble crawlAsync job — poll with nimble crawl status <job_id>

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.

Output & Organization

mkdir -p .nimble   # save all outputs here

Naming: .nimble/<site>-<task>.md (e.g. .nimble/amazon-airpods.md, .nimble/yelp-sf-italian.json)

Working with saved files:

wc -l .nimble/page.md && head -100 .nimble/page.md
grep -n "price\|rating" .nimble/page.md | head -30

End every response with: Source: [URL] — fetched live via Nimble CLI


Self-Improvement

The skill maintains ~/.claude/skills/nimble-web-expert/learned/examples.json.

  • At task start: read the file, scan good[] for url_pattern matches → use documented command/tier as starting point. Scan bad[] → avoid documented pitfalls.
  • 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.
  • Keep entries concise — 5–10 per site. Only write on real feedback, never speculatively.

Guardrails

  • NEVER answer from training data for live prices, current news, or real-time data. If Nimble is unavailable, say so.
  • 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.
  • 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.
  • 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.
  • 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.
  • NEVER retry the same render tier. If a tier returns empty or truncated content, escalate — do not re-run.
  • 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.
  • 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.
  • NEVER load reference files speculatively. Only read a reference when the current task explicitly needs it.
  • Task agents MUST use run_in_background=False.
  • Hard retry limit. On error (not empty content): retry at most 2 times with different flags. After 2 errors, report and stop.
  • Hard 429 rule. On rate-limit error: stop immediately. Do not retry or switch tiers.

Reference files

Load only when needed:

FileLoad when
references/recipes.mdNeed a proven command for a common site (Amazon, Yelp, LinkedIn…)
references/nimble-extract-templates/reference.mdStep 0 — discover/inspect/run Extraction Templates for a known site
references/nimble-agents/reference.mdWeb Search Agents — discovery, run lifecycle, authoring, trust/citations
references/nimble-extract/reference.mdExtract flags, render tiers, browser actions, network capture, parser schemas
references/nimble-search/reference.mdSearch flags, all 8 focus modes
references/nimble-map/reference.mdMap flags, response structure
references/nimble-crawl/reference.mdFull async crawl workflow
references/nimble-tasks/reference.mdPoll tasks/batches, fetch results — for async, batch, and crawl operations
references/nimble-extract/browser-investigation.mdTier 6 — CSS selector/XHR discovery with browser-use or Playwright
references/nimble-extract/parsing-schema.mdParser types, selectors, extractors, post-processors
references/nimble-extract/browser-actions.mdFull browser action types and parameters
references/nimble-extract/network-capture.mdFilter syntax, XHR mode, capture+parse patterns
references/nimble-search/search-focus-modes.mdDecision tree, mode details, combination strategies
references/batch-patterns.mdParallel bash patterns for 2–5, 6–20, and 20+ inputs
references/error-handling.mdError codes, known site issues, troubleshooting

Onboard your agent: Nimble for company investment research

You are setting up Nimble for an investment professional (analyst, PM, credit or event-driven desk, data scientist). Nimble gives you the live web as cited, structured data. Follow the steps in order.

Step 1: Show the benchmark chart, the five tiles and ask one question

As soon as this skill loads, show the benchmark chart, then the five tiles below it, then ask exactly one question. Do this before any setup talk.

1a. Show the prebuilt onboarding screen (never redraw it)

The benchmark chart and the five tiles are prebuilt in assets/, next to this file (paths below are relative to this skill's base directory). Show them as they are. Never write chart or tile code yourself: generating it is what makes onboarding slow.

Show them inline, in the conversation itself. The user must see the chart and all five tiles in the chat, above your question. Never put them only in a side panel, a file card, a separate artifact or a browser tab, and never tell the user to look in a panel. Pick the first row your host supports:

Your host can…Show
Render HTML inline in the chat (for example the Claude apps' inline visual or widget tool, an inline HTML block)Read assets/onboarding-inline.html and pass it verbatim: chart and all five tiles in one static fragment (no doctype, no scripts, no libraries, about 6 KB)
Render visuals inline only from SVGRead assets/benchmark-chart.svg and pass it verbatim (3 KB of static SVG), then the markdown tiles below in your reply
Show an image in the chat![Deep research task comparison for finance](https://raw.githubusercontent.com/Nimbleway/agent-skills/main/skills/onboard-your-agent/assets/onboarding.png) (chart and tiles in one image), then the integrations link below as text so it is clickable
None of these (plain terminal)The benchmark table below under its title, with Nimble's row in bold, then the markdown tiles below

assets/onboarding.html is the same screen as a full standalone page, for hosts that can only preview files; if that is all you can do, also put the markdown tiles in your reply so the user sees them in the chat.

For the fallbacks, the chart data: Nimble's public Finance Use-Case Benchmark v2 (all eight finance jobs, 40 tasks, November 2026; source: references/benchmark.md). Title: "Deep research task comparison for finance". Caption: "Finance Use-Case Benchmark v2, 40 tasks, November 2026. Higher and further left is better."

ProviderF1 accuracy + coverageCost per run (USD)
Nimble0.5940.45
Claude Opus 5.50.5830.79
GPT-6.1 Sol0.5130.64
Exa0.4550.48
Parallel0.4180.54
Firecrawl0.3880.36

Use exactly these numbers; never round them up or add providers. The same numbers and the tile copy live in assets/build.py; when either changes, edit it there and run python3 skills/onboard-your-agent/assets/build.py to rebuild the SVGs, the HTML page and fragment, and the PNG.

1b. The five tiles

The tiles say what they are: the user is testing Nimble's APIs on real investment research use cases, right here in their own AI. Each tile names the Nimble API behind it. The fifth tile is for taking those APIs into the user's own stack.

The inline fragment and the PNG already contain the tiles. When you showed only the SVG or the table, put this line above the tiles: "Test Nimble's APIs on these use cases, right here in your AI." Then use this markdown:

🔎 Deep research · Web Search Agents API⚡ Fast search · Search + Extract APIs
13 hedge fund research agents (deep dive, catalysts, filing changes, red flags, credit, merger arb, channel checks) plus custom agents. Cited answers in about 5 to 15 minutes.Answers in seconds from filings, IR pages, regulators and news, with dated primary-source citations.
"Underwrite Duolingo long on paid subscriber growth.""What did NVDA's latest 8-K disclose?"
📄 Filings, PDFs & media · Extract file parsing + Media API📊 Alt data at scale · Extract Templates + Jobs API
Turn 10-K exhibits, decks, credit and merger agreements into markdown; download files and webcasts to disk or S3.Prices, reviews, jobs and store data from 800+ Extract Templates, run as batches or scheduled jobs into S3 or Databricks.
"Pull the debt table from this credit agreement.""Track Celsius prices at Walmart and Target daily."

🔌 Try asking Nimble your most complex web research questions

Once you're done testing, call the same APIs from your own apps and agents (MCP, SDK, CLI, & more): https://docs.nimbleway.com/integrations/overview

Then ask:

What kind of company investment research do you want to test? For example, a name you're underwriting, a catalyst or deal you're tracking, a borrower you're watching, or a dataset you want to build. Or try: "Underwrite Duolingo long on paid subscriber growth."

Keep the chart, the tiles and the question to one screen. No preamble. Then stop and wait for the user's answer: never run the example prompt yourself or answer it on the user's behalf.

Step 2: Check whether Nimble is already connected

While the user answers, check silently. This probe is the only Nimble call before the user replies: no Search, Extract or Web Search Agent call on the example prompt or anything else, and no "test" or "verification" call. Either surface working means setup is done; once the user answers, skip to Step 5 and route their request.

  • MCP: if any Nimble tool is listed, call the read-only nimble_agents_list.
  • CLI: if you can run shell commands: command -v nimble && nimble --version && nimble agents list. The CLI reads NIMBLE_API_KEY from the environment.
ResultNext
Either probe returns dataStep 5
A Nimble tool returns an auth error or an authorization URLStep 4
Nothing is installed and the user has no Nimble accountStep 3
Nothing is installed but the user has an accountStep 4

Step 3: Start the free trial

If the user has no Nimble account, this comes first. Say it in two or three lines:

Nimble has a free trial, and signing up takes about two minutes.

  1. Open https://online.nimbleway.com/signup and create an account with your work email.
  2. Confirm your email, then log in to the dashboard. Tell me when you're in and I'll connect it.

Open the link for them if your host can. Do not fill in the form, create the account or confirm the email for them. Wait for them to confirm, then go to Step 4.

On hosts that use OAuth (most MCP clients), the user can also create the account during the first authorization in Step 4; mention it so they do not sign up twice.

Step 4: Connect Nimble to this agent

Default to the MCP server: it uses OAuth, so no API key is created, pasted or stored. Pick the row for your host:

HostHow
Claude CodeIf the nimble plugin (nimble@nimble-plugin-marketplace) is installed, the Nimble MCP server is bundled: run /mcp, pick nimble and authorize. If the skills were installed with npx skills add, run claude mcp add --transport http --scope user nimble https://mcp.nimbleway.com/mcp in a terminal (or run it for the user if you can run shell commands), then /mcp to authorize
Claude.ai / Claude Desktop / CoworkInstall Nimble from the plugin directory, or add a custom connector at https://mcp.nimbleway.com/mcp under Customize → Connectors, then Connect
ChatGPTSettings → Apps & Connectors → add a custom connector with URL https://mcp.nimbleway.com/mcp (requires developer mode on some plans), then sign in
Cursor, VS Code, other MCP clientsAdd {"mcpServers": {"nimble": {"type": "http", "url": "https://mcp.nimbleway.com/mcp"}}}; the first tool call starts OAuth
Codex DesktopPlugins → search Nimble → install and approve OAuth
Codex CLIIn ~/.codex/config.toml: [mcp_servers.nimble-mcp-server], url = "https://mcp.nimbleway.com/mcp", bearer_token_env_var = "NIMBLE_API_KEY"

When the CLI or API is also needed. The MCP server covers Search, Extract, Extract Templates, Map, Crawl and Web Search Agents. Parsing PDFs, downloading media, template batches and Extract Jobs need the CLI or REST API (filings-media-pdfs, alt-data-at-scale). If the user's task needs those and the host has a terminal, ask once whether to add the CLI and say why in one sentence:

npm i -g @nimble-way/nimble-cli

Then the user creates a key at https://online.nimbleway.com/settings/api-keys (one key per agent, named for it) and sets NIMBLE_API_KEY in their shell profile or secret manager.

Credential safety. Never ask the user to paste the key into the chat. Never print it (echo $NIMBLE_API_KEY, printenv) or write it to a file that could be committed or shared. Check it exists with [ -n "$NIMBLE_API_KEY" ] && echo set || echo missing and let the shell expand it in an Authorization: Bearer $NIMBLE_API_KEY header.

If a tool returns an authorization URL, show it exactly as given and wait. Do not fall back to a generic web search or fetch tool while waiting; that hides the setup problem and returns different data.

Install these skills so the agent can route requests (if the user is reading this, they are installed on this host; share this when they want them on another tool or for a teammate):

HostHow
Claude Code, Codex, Cursor and other agentsnpx skills add Nimbleway/agent-skills (one command; then connect the MCP server as above)
Claude Code, with the MCP server bundledclaude plugin marketplace add Nimbleway/agent-skills && claude plugin install nimble@nimble-plugin-marketplace
ChatGPT Business, Enterprise and EduZip each folder under skills/ and upload it under Skills → Create → Upload from your computer (one zip per skill; a workspace admin may need to allow uploads)
ChatGPT on other plans, or any other agentAdd the SKILL.md files to the project or custom GPT instructions
Claude.aiZip each folder under skills/ and upload it under Customize → Skills

Step 5: Route the request to a skill

Once Nimble is connected, say so in one line and route the user's answer from Step 1. Do not run a separate test call first; the user's own request is the first call.

What the user saidSkillFirst move
A single fact, date, person, filing or page ("who", "when", "what did the 8-K say")company-fast-searchOne scoped Search, then Extract the primary page
A name to underwrite, a thesis to test, a short idea, management credibilitycompany-deep-researchhf-fundamental-deep-dive, hf-forensic-red-flags or hf-management-track-record
What's coming up, what changedcompany-deep-researchhf-catalyst-calendar, hf-filing-changes
A pending merger (merger arb)company-deep-researchhf-deal-terms, then hf-deal-tracker
A borrower's credit file (capital structure, loans, bonds), stress signals since the last reviewcompany-deep-researchhf-credit-profile, then hf-credit-early-warning
A quick credit view or counterparty check on one company ("can they pay")credit-riskThe credit-risk agent
Customers, suppliers, competitors, government revenuecompany-deep-researchhf-customer-supplier-map, hf-competitor-momentum, hf-government-contracts
"What does the web show today versus last quarter" for one questioncompany-deep-researchhf-channel-check
Anything else that needs many sourcescompany-deep-researchBuild a custom Web Search Agent (section 5 of that skill)
Using Nimble's APIs from their own code, agents, pipelines or warehouseNoneLink https://docs.nimbleway.com/integrations/overview and help them pick a path (MCP server, plugin and skills, SDK and CLI, Databricks or Snowflake)
A PDF, deck, agreement, spreadsheet, webcast or imagefilings-media-pdfsExtract with file_parsing_options, or Media download
A panel of prices, reviews, postings or locations over timealt-data-at-scaleFind the Extract Template, pilot 20 to 50 inputs, then batch or schedule a Job

If the answer spans more than one (common), start with the fastest piece that unblocks the rest and say what comes next. For example: fast search to pin the entity and latest filing, then a deep research run, then an alt-data panel to keep watching.

By strategy, the usual starting points:

  • Fundamental long/short: fundamental deep dive → catalyst calendar → channel check or an alt-data panel on the key KPI.
  • Event-driven / merger arb: deal terms → deal tracker on a schedule → fast search for each new filing.
  • Credit / distressed: credit file → early-warning log since the last review → parse the credit agreement.
  • Quant / data science: alt-data panels via Extract Jobs into S3 or Databricks, with entity maps to tickers.
  • Activist: forensic screen, management track record, proxy (DEF 14A) parsing.

Ground rules to state once

Say these once during onboarding, briefly, then apply them silently:

  • Only public information. No paywalled, logged-in, leaked or expert-network content, which could be MNPI. A paywalled page is never the only source for a value.
  • Every value comes with its source URL and date; anything unpublished is reported as not found, not estimated. Date windows stay windows, and problems that were cured are labeled cured, not live.
  • Analyst estimates and price targets are labeled as opinions.
  • Deep research runs take minutes. You'll be told when one starts and roughly when it will finish.

Reference

Onboard your agent: Nimble for GTM research

You are setting up Nimble for a go-to-market professional (AE, SDR/BDR, sales leader, RevOps, growth or product marketing, founder doing sales). Nimble gives you the live web as cited, structured data. Follow the steps in order.

Step 1: Show the benchmark chart, the six tiles and ask one question

As soon as this skill loads, show the benchmark chart, then the six tiles below it, then ask exactly one question. Do this before any setup talk.

1a. Show the prebuilt onboarding screen (never redraw it)

The benchmark chart and the six tiles are prebuilt in assets/, next to this file (paths below are relative to this skill's base directory). Show them as they are. Never write chart or tile code yourself: generating it is what makes onboarding slow.

Show them inline, in the conversation itself. The user must see the chart and all six tiles in the chat, above your question. Never put them only in a side panel, a file card, a separate artifact or a browser tab, and never tell the user to look in a panel. Pick the first row your host supports:

Your host can…Show
Render HTML inline in the chat (for example the Claude apps' inline visual or widget tool, an inline HTML block)Read assets/onboarding-inline.html and pass it verbatim: chart and all six tiles in one static fragment (no doctype, no scripts, no libraries, about 6 KB)
Render visuals inline only from SVGRead assets/benchmark-chart.svg and pass it verbatim (3 KB of static SVG), then the markdown tiles below in your reply
Show an image in the chat![Deep research task comparison for GTM](https://raw.githubusercontent.com/Nimbleway/agent-skills/main/skills/onboard-your-gtm-agent/assets/onboarding.png) (chart and tiles in one image), then the integrations link below as text so it is clickable
None of these (plain terminal)The benchmark table below under its title, with Nimble's row in bold, then the markdown tiles below

assets/onboarding.html is the same screen as a full standalone page, for hosts that can only preview files; if that is all you can do, also put the markdown tiles in your reply so the user sees them in the chat.

For the fallbacks, the chart data: Nimble's public GTM Use-Case Benchmark v2 (meeting prep and signal tracking, 10 tasks, November 2026; source: references/benchmark.md). Title: "Deep research task comparison for GTM". Caption: "GTM Use-Case Benchmark v2, 10 tasks, November 2026. Higher and further left is better."

ProviderAccuracy + coverage scoreCost per run (USD)
Claude Opus 5.50.5200.28
Nimble0.4970.10
GPT-6.1 Sol0.4480.21
Exa0.4050.10
Parallel0.3570.10
Firecrawl0.3160.10

Use exactly these numbers; never round them up, reorder them or add providers. If the user asks, the honest read is: Nimble scored highest of the four research APIs at the same price, and close to Claude Opus 5.5 at about a third of its cost; it found the most verified facts of any provider and scored highest on signal tracking. The same numbers and the tile copy live in assets/build.py; when either changes, edit it there and run python3 skills/onboard-your-gtm-agent/assets/build.py to rebuild the SVGs, the HTML page and fragment, and the PNG.

1b. The six tiles

The tiles say what they are: the user is testing Nimble's APIs on real GTM use cases, right here in their own AI. Each tile names the Nimble API behind it. The last tile is for taking those APIs into the user's own stack.

The inline fragment and the PNG already contain the tiles. When you showed only the SVG or the table, put this line above the tiles: "Test Nimble's APIs on these use cases, right here in your AI." Then use this markdown:

🔎 Account research · Web Search Agents API⚡ Fast search · Search + Extract APIs
12 GTM agents (meeting prep, buying triggers, decision makers, competitive and brand intel, social) plus custom agents. Cited answers in about 2 to 10 minutes.Answers in seconds from company sites, newsrooms, careers pages and the press, with dated citations.
"Prepare me for a meeting with Gong (gong.io).""Did Clay raise a round this year?"
📋 Lists & CRM enrichment · Web Search Agents + Search APIs📊 GTM data at scale · Extract Templates + Jobs API
Build ICP account lists with near-misses, and fill CRM fields (firmographics, funding, leaders, hiring) with sources and conflicts kept.Job postings, reviews, local business lists, social and AI-answer visibility from 800+ Extract Templates, as batches or scheduled jobs.
"Find US legal AI companies, Series A to C, hiring AEs.""Track sales hiring at my top 200 accounts weekly."
👤 People research · Search + Web Search Agents APIs
Who holds a role, verified as current, in seconds; people who match an ICP, person briefs, buying committees and job-change checks with agents.
"Who is Gong's CRO today, and since when?"

🔌 Try asking Nimble your most complex web research questions

Once you're done testing, call the same APIs from your own apps and agents (MCP, SDK, CLI, & more): https://docs.nimbleway.com/integrations/overview

Then ask:

What GTM research do you want to test? For example, an account or a person you're meeting this week, a watchlist you want buying triggers for, an ICP list you want built, or CRM records you want enriched. Or try: "Prepare me for a meeting with Gong (gong.io)."

Keep the chart, the tiles and the question to one screen. No preamble. Then stop and wait for the user's answer: never run the example prompt yourself or answer it on the user's behalf.

Step 2: Check whether Nimble is already connected

While the user answers, check silently. This probe is the only Nimble call before the user replies: no Search, Extract or Web Search Agent call on the example prompt or anything else, and no "test" or "verification" call. Either surface working means setup is done; once the user answers, skip to Step 5 and route their request.

  • MCP: if any Nimble tool is listed, call the read-only nimble_agents_list.
  • CLI: if you can run shell commands: command -v nimble && nimble --version && nimble agents list. The CLI reads NIMBLE_API_KEY from the environment.
ResultNext
Either probe returns dataStep 5
A Nimble tool returns an auth error or an authorization URLStep 4
Nothing is installed and the user has no Nimble accountStep 3
Nothing is installed but the user has an accountStep 4

Step 3: Start the free trial

If the user has no Nimble account, this comes first. Say it in two or three lines:

Nimble has a free trial, and signing up takes about two minutes.

  1. Open https://online.nimbleway.com/signup and create an account with your work email.
  2. Confirm your email, then log in to the dashboard. Tell me when you're in and I'll connect it.

Open the link for them if your host can. Do not fill in the form, create the account or confirm the email for them. Wait for them to confirm, then go to Step 4.

On hosts that use OAuth (most MCP clients), the user can also create the account during the first authorization in Step 4; mention it so they do not sign up twice.

Step 4: Connect Nimble to this agent

Default to the MCP server: it uses OAuth, so no API key is created, pasted or stored. Pick the row for your host:

HostHow
Claude CodeIf the nimble plugin (nimble@nimble-plugin-marketplace) is installed, the Nimble MCP server is bundled: run /mcp, pick nimble and authorize. If the skills were installed with npx skills add, run claude mcp add --transport http --scope user nimble https://mcp.nimbleway.com/mcp in a terminal (or run it for the user if you can run shell commands), then /mcp to authorize
Claude.ai / Claude Desktop / CoworkInstall Nimble from the plugin directory, or add a custom connector at https://mcp.nimbleway.com/mcp under Customize → Connectors, then Connect
ChatGPTSettings → Apps & Connectors → add a custom connector with URL https://mcp.nimbleway.com/mcp (requires developer mode on some plans), then sign in
Cursor, VS Code, other MCP clientsAdd {"mcpServers": {"nimble": {"type": "http", "url": "https://mcp.nimbleway.com/mcp"}}}; the first tool call starts OAuth
Codex DesktopPlugins → search Nimble → install and approve OAuth
Codex CLIIn ~/.codex/config.toml: [mcp_servers.nimble-mcp-server], url = "https://mcp.nimbleway.com/mcp", bearer_token_env_var = "NIMBLE_API_KEY"

When the CLI or API is also needed. The MCP server covers Search, Extract, Extract Templates, Map, Crawl and Web Search Agents. Enriching a whole CSV or CRM export, template batches and scheduled Extract Jobs are better through the CLI or REST API, so results land in files instead of the chat (account-lists-and-enrichment, gtm-data-at-scale). If the user's task needs those and the host has a terminal, ask once whether to add the CLI and say why in one sentence:

npm i -g @nimble-way/nimble-cli

Then the user creates a key at https://online.nimbleway.com/settings/api-keys (one key per agent, named for it) and sets NIMBLE_API_KEY in their shell profile or secret manager.

Credential safety. Never ask the user to paste the key into the chat. Never print it (echo $NIMBLE_API_KEY, printenv) or write it to a file that could be committed or shared. Check it exists with [ -n "$NIMBLE_API_KEY" ] && echo set || echo missing and let the shell expand it in an Authorization: Bearer $NIMBLE_API_KEY header.

If a tool returns an authorization URL, show it exactly as given and wait. Do not fall back to a generic web search or fetch tool while waiting; that hides the setup problem and returns different data.

Install these skills so the agent can route requests (if the user is reading this, they are installed on this host; share this when they want them on another tool or for a teammate):

HostHow
Claude Code, Codex, Cursor and other agentsnpx skills add Nimbleway/agent-skills (one command; then connect the MCP server as above)
Claude Code, with the MCP server bundledclaude plugin marketplace add Nimbleway/agent-skills && claude plugin install nimble@nimble-plugin-marketplace
ChatGPT Business, Enterprise and EduZip each folder under skills/ and upload it under Skills → Create → Upload from your computer (one zip per skill; a workspace admin may need to allow uploads)
ChatGPT on other plans, or any other agentAdd the SKILL.md files to the project or custom GPT instructions
Claude.aiZip each folder under skills/ and upload it under Customize → Skills

Step 5: Route the request to a skill

Once Nimble is connected, say so in one line and route the user's answer from Step 1. Do not run a separate test call first; the user's own request is the first call.

What the user saidSkillFirst move
A single fact about an account ("did they raise", "are they hiring AEs", "what's on their pricing page")account-fast-searchOne scoped Search, then Extract the primary page
A meeting or call with one account, "brief me on", "prep me for"account-briefThe account-brief agent
What changed at an account, buying triggers, a watchlistaccount-deep-researchaccount-signals (one account) or gtm-buying-trigger-monitor (a watchlist)
Who holds a role at one company ("who is their CRO", "who runs RevOps at")decision-maker-identificationThe decision-maker-identification agent, with the current title proved by a dated source
Who to talk to: a person brief, a buying committee, decision makers across many accounts, job changes on a contact listpeople-researchperson-brief, buying-committee-map, decision-maker-identification per account, contact-job-change-monitor
A list of people who match an ICP (roles, seniority, company criteria)people-researchpeople-discovery
Competitors, battlecards, pricing comparisonsaccount-deep-researchcompetitive-intelligence
What people say about a brand or product; what an influencer or exec postedaccount-deep-researchbrand-intelligence, social-media-monitor
Anything else about one account that needs many sourcesaccount-deep-researchBuild a custom Web Search Agent (section 5 of that skill)
An ICP or target account list, a TAM list, local businesses in an areaaccount-lists-and-enrichmentgtm-icp-discovery / account-discovery, or business-discovery for local SMBs
A CSV, CRM export or list of domains to fill inaccount-lists-and-enrichmentgtm-account-enrichment / account-enrichment in batches, then CRM write-back rules
Hiring, reviews, local listings, social or AI-answer data tracked over time for many accountsgtm-data-at-scaleFind the Extract Template, pilot 20 to 50 inputs, then batch or schedule a Job
Using Nimble's APIs from their own code, agents, CRM or warehouseNoneLink https://docs.nimbleway.com/integrations/overview and help them pick a path (MCP server, plugin and skills, SDK and CLI, Databricks or Snowflake)

If the answer spans more than one (common), start with the fastest piece that unblocks the rest and say what comes next. For example: fast search to pin the account's domain and latest news, then an account brief, then a trigger watch on the same account.

By motion, the usual starting points:

  • AE preparing for a meeting: account brief (account-brief) → person brief on each attendee and a buying committee map (people-research) → competitive intelligence if a rival is in the deal (account-deep-research).
  • SDR/BDR prospecting: ICP discovery → enrichment of the list → buying triggers on the list weekly → decision makers for the accounts that trigger → job-change checks on past champions monthly.
  • RevOps / data: enrichment of the CRM in batches with precedence rules → Extract Jobs for hiring and review signals into the warehouse.
  • Product and competitive marketing: competitive intelligence → brand intelligence → AI-answer visibility panels (chatgpt, perplexity, google_ai, gemini templates).
  • Local and SMB sales: business discovery by category and city → Google Maps reviews and ratings → enrichment of the shortlist.

Ground rules to state once

Say these once during onboarding, briefly, then apply them silently:

  • Only public information. No logged-in, paywalled or purchased data, and no emails or phone numbers guessed from patterns. Personal data is limited to what the task needs.
  • Every value comes with its source URL and date; anything unpublished is reported as not found, not estimated. Lists are never padded to reach a count.
  • Events are dated by when they happened, not when an article was published. Re-reported old news is not a new signal.
  • Deep research runs take minutes. You'll be told when one starts and roughly when it will finish.

Reference

People research with Nimble

People questions come in two speeds. Start fast, and go deep only when the question needs it.

SpeedNimble APIUse it forTime
FastSearch (nimble_search, POST /v2/search), plus Extract for one pageOne person or one role: who holds it, since when, where they came from, one recent quote or talkSeconds
DeepWeb Search Agents (nimble_agents_*)A list of people who match an ICP, a full brief on a person, a buying committee at an account, job-change checks on a contact list, decision makers across accountsAbout 1.5 to 10 minutes (a person brief took about 2 minutes, a one-contact job-change check about 1.5)

Rule of thumb: if three searches answer it, stay fast. If the user wants a brief, a map, a table or many people, run one agent.

1. Pin the person first

Write down full name + company + company domain (and title or city if known) before searching, and use at least two of them in every query. People research fails on identity more than on search:

  • Common names: there are many people called Shane Evans; there is one Shane Evans at Gong.
  • Company names that are common words (Gong, Ramp, Clay, Mercury): add the domain or a product word, or the search returns everything else.
  • Former employees: bios, speaker pages and profiles from previous jobs stay indexed for years.
  • Same title in several units or regions at large companies: say which one the person covers.

2. The fast path: Search API

The loop:

  1. Find the candidate. One search for the role or the name, scoped to the company.
  2. Verify the title is current. A press release announcing an appointment is dated history. Run a second, date-scoped search on the person's name (time_range: "year") and open the newest first-party page. This step is not optional.
  3. Read the page with Extract when the snippet is not enough (the leadership page, the release, the speaker page).
  4. Answer with the source and its date, and say what you checked for a later change.

Worked example (why step 2 matters). "Who is Gong's CRO?" with include_answer: true returns Shane Evans, citing Gong's October 2023 appointment release. A date-scoped search for "Shane Evans" Gong in the last year returns Gong's own blog and February 2026 coverage: he is now Gong's Chief Revenue Architect. The first answer was true in 2023 and wrong today. (contact-job-change-monitor catches the same change: new_title_same_company, change date 2026-02-19.)

Query patterns:

NeedSearch
Who holds a role"<Company>" "<Title>" with include_answer: true, then verify (step 2). Or Extract the company's leadership page
A cited one-line answerinclude_answer: true with time_range: "year"; check the answer cites a first-party or dated page
Find their public profilesite:linkedin.com/in "<Company>" "<Title>", search_depth: "lite", max_results: 10: result titles read "Name - Title at Company". A profile seen in search results is a lead; confirm the current role elsewhere when it matters
Recent appointment or move"<Name>" "<Company>" joins OR appointed OR named, time_range: "year"
What they said recently"<Name>" "<Company>" podcast OR interview OR webinar OR keynote, time_range: "year"; include_domains: [<company domain>] for blog posts they wrote
Quotes in press"<Name>" "<Company>" said, or focus: "news" with search_depth: "lite" and the domain in the query
Career history"<Name>" "previously" OR "prior to joining" with the company; appointment releases list past roles
Who leads a team that is hiringJob posts on the company's ATS board often name the team; Extract the board (see account-fast-search)

Parameter notes (tested):

  • focus modes (news, social, location and the rest) only work with search_depth: "lite". For people, plain queries with quotes and the domain usually beat focus: "social", which matches the name loosely (a search for Gong's CRO in social returned people whose surname is Gong).
  • time_range (day, week, month, year) or start_date / end_date: always date-scope "current" and "recent" questions. They cannot be combined.
  • max_results 5 to 10 is enough; run independent searches in parallel rather than one long query.
  • The ti_linkedin_serp_profiles Extract Template parses a Google results page limited to linkedin.com/in profiles (pass the Google search URL as url) into name, title, snippet, linkedin_url, which is handy for many roles at once.

Escalate to an agent when you have run three searches and are still reconciling pages, when the user wants more than a few facts, or when it is more than two or three people.

3. The deep path: people research agents

Agent (agent_name)Use it when the user asks...Use caseSource
people-discoveryfor people who match an ICP for people (roles and seniority, plus company criteria such as industry, size, location or funding), each with why they fit and a page showing the current titledataset_buildinggallery
person-briefto research one named person before a meeting or outreach: current role verified with its date, career history, recent public activity, stated priorities, talking pointsresearchgallery
decision-maker-identificationwho holds named roles at one company now, with title, start date, past roles and public profilesenrichmentgallery
buying-committee-mapwho at an account would buy, champion, evaluate or block a purchase in a product category, each with why they matterresearchgallery
contact-job-change-monitorwhether contacts on a list are still in the same role, changed title, or moved employer, with the date (champion tracking, CRM hygiene)enrichmentgallery
social-media-monitorwhat named people posted in a window, with engagementdataset_buildinggallery

All six are templates in the Go-to-market section of the Nimble Web Search Agent gallery, each with a pre-run example answer. Each spec (skill, output schema, effort, example questions) is also in agents/<agent_name>.json next to this file, a snapshot of the gallery template (2026-11-12). decision-maker-identification and social-media-monitor are shared with account research, so their specs live in account-deep-research/agents/. If only this skill is installed, read them from https://raw.githubusercontent.com/Nimbleway/agent-skills/main/skills/account-deep-research/agents/<agent_name>.json. Read the matching file before the first run; its suggested_questions show the input format.

Get the agent into the account (reuse first): an agent with the same agent_name already in the account (nimble_agents_list) → the Nimble gallery (nimble_agent_templates_list, then nimble_agents_create(template=<name>, agent_name=<name>)) → the bundled spec, if the gallery does not list it (an older deployment) (pass its agent_name, display_name, description, use_case, effort, skill, output_schema and suggested_questions unchanged). Create each agent once and reuse it.

Run it:

nimble_agents_run(agent_id=<id>,
  input="Brief me on Shane Evans at Gong (gong.io) before a call next week. I sell data infrastructure to revenue teams.")
→ nimble_agents_run_status(run_id=<run_id>, agent_id=<agent_id>) # waits ~45 s per call; call again until it completes

Put the name, company and domain, the roles, and the seller's context ("I sell X to Y") in the input. For contact-job-change-monitor, pass the contacts as input_data rows (full_name, company, domain, last_known_title, optional profile_url), about 5 rows per run at high. REST: POST /v2/agents/{agent_id}/runs with {"input": ..., "input_data": ...}, poll GET /v2/agents/{agent_id}/runs/{run_id} while is_active, then GET .../runs/{run_id}/result.

Check before you present. completed means finished, not correct:

  • Same person: every source names the right company (and title or city). Drop pages about namesakes.
  • Current, with a date: each title has an as_of within the last 12 months or a page showing it as current. An appointment release alone is not proof of today's title.
  • Moves need evidence: moved_company needs a dated page naming the new employer. "Not on the leadership page" is cannot_verify, not a departure.
  • Priorities are quoted, not guessed: every stated priority or talking point traces to something the person or their company published.
  • Nothing personal: remove any home address, personal email or phone, family or other sensitive detail that slipped in, and never present a constructed email address.
  • Missing roles are reported: a role nobody publicly holds belongs in missing_roles or missing_fields, not filled with a near match.

4. Many people, many accounts

  • People who match an ICP: one people-discovery run per scope (a region, a sub-industry or a company-size band), 15 to 50 people per run; split a large market into several scoped runs and pass people already found as input_data with "exclude the people in input_data". The company criteria are verified per person, and people at companies that fail one land in excluded with the reason.
  • Decision makers across a list of accounts: one decision-maker-identification run per account (it returns one company's people), run in parallel, about 10 at a time. For a thin first pass across hundreds of accounts, the fast path (one site:linkedin.com/in "<Company>" "<Title>" search per account and role) is cheaper; then run agents on the accounts that matter.
  • Champion tracking: run contact-job-change-monitor over the contact list monthly in batches of about 5. A champion who moved is a new-logo lead at their new company: route it to account-brief for the new employer.
  • Buying committees: one buying-committee-map run per target account, after the account list is final.
  • Batching, concurrency, ledgers and CRM write-back rules are the same as for accounts: see account-lists-and-enrichment. Never overwrite a contact a rep entered; queue changes for review.

5. Privacy rules (apply to every people request)

  • Work-related public information only: name, title, employer, career history, public talks, posts, articles and quotes. No home address, personal phone or email, family, health, age, religion, politics or other sensitive data.
  • Never construct email addresses or phone numbers from patterns. Business contact details count only when the person or their company published them for business contact. If the user needs emails, they come from the user's licensed contact provider, matched on name, company and profile URL.
  • Public pages only. No logged-in views, paywalls or CAPTCHA workarounds; LinkedIn and X are read only as logged-out pages and search results show them.
  • Purpose-bound. Research people for the business purpose the user stated (a meeting, an account plan). Decline requests to profile someone's private life or to track an individual outside a work context.
  • The user's own rules win: do-not-contact flags, opt-outs and regional privacy law (GDPR, CCPA, CASL) decide who is contacted, not what the web shows.

Answer format

Lead with the answer, then the evidence and the freshness check:

Answer: Shane Evans is Gong's Chief Revenue Architect (title since 2026-02-19; Gong announced him as Chief Revenue Officer on 2023-10-19). Sources: Gong blog, https://gong.io/blog/the-cra-is-the-new-cro-why-i-m-becoming-a-revenue-architect; appointment release, https://gong.io/press/gong-names-shane-evans-as-chief-revenue-officer (2023-10-19). Checked: Gong's newsroom and press coverage of his name in the last 12 months; no later change found.

For a brief or a map, lead with the bottom line (who matters and the best angle), then the people with a source and date for each.

Portfolio monitoring

Lists material events at a holding since a date: exec changes, litigation, rating actions, guidance and defaults, with why each one matters.

What the user gets

Only material events after the since date, each dated and cited, with why it matters. If nothing material happened, an empty list and the sources it checked.

Agent template

This skill runs the Nimble gallery template portfolio-monitoring. The agent's instructions, sources and output schema live in the template. Do not rewrite them in the run.

Effort: this skill runs the template at medium effort (about 1-3 minutes), even when the template's default effort is different. That is on purpose. If the user asks for a specific effort (low, medium, high or x-high), run that one instead.

Flow

  1. Interview the user.
  2. Connect Nimble if it is not connected already.
  3. Run the agent and show the result.
  4. Offer next steps.

Ask every question with the host's question UI, never as plain text: AskUserQuestion in Claude Code, ChatGPT's interactive question form (clickable choices and a Submit button) in ChatGPT.

Get the inputs

InputRequiredAsk forIf skipped
HoldingyesName with a ticker or domain-
SincenoA date in YYYY-MM-DDlast 30 days
Materiality rulenoFor example "ignore product launches"the standard materiality rule
  • Skip anything the user already said in this conversation or in their request, and ask only for what is missing. Do not fill in answers from earlier conversations, with one exception: a stable fact about the user, such as what they sell, may be offered as the first option, labeled "(from before)". Never carry over the subject of the request, dates or rules from an earlier conversation.
  • Ask the required inputs first, in table order, one question at a time. Then ask the optional ones together, in one question-tool call, as many as the tool takes per call (a second call for the rest).
  • Put the whole question in the question tool, once. Never restate or introduce a question in text. Between questions, acknowledge the answer in a few words, and before the first question, at most one short sentence that acknowledges your role (the user's, if they named one), such as "Sure, I'll use Nimble to be your portfolio monitoring assistant." Talk in plain, friendly words: never say "input", "required" or "optional", and use no field names. Use plain text only if the host has no question tool, in one short line.
  • Write 2-3 likely answers as options, based on what the user has already said. Fixed examples in the table are a guide to what the answer contains, not a list to copy. Offer only answers Nimble can act on with public web data, never ones that need the user's own data, such as their customers or CRM.
  • If you cannot guess likely answers, such as a company name or an industry, still use the tool and offer two or three examples as options, written as answers the user could really give. If the user picks one, use it as their answer.
  • Every question must let the user type their own answer, optional ones too. Claude's question UI adds its own free-text choice ("Something else" in Claude, "Other" in Claude Code), so add none there. ChatGPT's form does not, so add "Other" as the last option of every question, even one whose options look complete, opening a text field with a placeholder. In any other host, add "Other" unless you know its UI already has a free-text choice. Keep Skip and Other, when you add them, even if you must drop an answer to fit the option limit.
  • Use single-select only. For a range, such as a size or a date, offer a few options that do not overlap.
  • Optional questions can be skipped, and a skipped answer uses the "If skipped" value. Claude's question UI has its own Skip button, so add no Skip option there. In other hosts, include a Skip option that states the default in its label, for example "Skip (any location)", not in the question. When you acknowledge a skipped question, say the default you will use, for example "Any location.", not that it was skipped. Do not offer a "skip all" option. If the user asks to skip the remaining questions, use the "If skipped" values for all of them.
  • Do not ask about effort.

Build the agent input from this pattern:

Check <Company> (<ticker or domain>) for material events since <YYYY-MM-DD>

Example: Check Boeing for material events since 2026-09-21

  • One holding at a time. If the user names several, run the first and offer the rest next.
  • Use whichever identifier the user gave: a ticker, or the domain for a private holding.
  • Always pass an explicit date in YYYY-MM-DD form. A skipped Since means the date 30 days before today. Take today's date from the host or by running date, and if you have neither, ask the user for the date.
  • If they have their own materiality rule, add one line to the input.

Connect Nimble

Do this after the interview. Until the questions are done, say nothing about connecting Nimble.

Check the connection. If a Nimble tool is listed in this session, call nimble_agents_list. If the CLI is available, run nimble --client-source nimble-agent-skills agents list. A normal response from either, even an empty list, means the user is connected: say nothing and go on.

If neither check succeeds (no tool is listed and the CLI is missing or fails, or a check returns an auth error or an authorization link), connect it in these steps. Your message is only these steps: no summary of what the user told you, no mention of the skill, the template or the workflow, and no plan for what happens after connecting (that belongs in the run notice).

  1. Tell the user, in two short sentences at most: "Nimble searches the live web and links where every answer came from. Connecting takes one approval, and if you're new to Nimble you start with a free trial."
  2. Connect it in the first of these ways that works, and stop at the first one that does:
    • Show the host's card to connect or install Nimble from nimbleway.com: the Connect card for the connector in Claude, the install card for the plugin in ChatGPT.
    • If you can't show a card and a check returned an authorization link, show that link to the user.
    • If you can do neither but can run commands, follow https://docs.nimbleway.com/agent-onboarding.md and involve the user only for the sign-up and the approval. With only the CLI and no NIMBLE_API_KEY, an approval is not enough: follow the page's API key fallback and have the user set the key in their environment, never in the chat. That page is written for you: never link it or its steps to the user.
    • If none of these works, tell the user how to find Nimble in this app, with the clicks: in ChatGPT, open Plugins in the sidebar, search for Nimble, pick the one described as "Expert web search for agents" and install it; in Claude, open Customize, then Connectors, then Nimble, then Connect. Never send the user to nimbleway.com for this.
  3. Ask with the question tool, with the options "I've connected Nimble" and "Not now". If the host has no question tool, end the message by asking them to reply "connected", and add nothing after that.

Never ask the user to paste an API key into the chat. When they confirm, check the connection again and go on without comment. If it is still not connected, say so in one line and ask again. If they pick "Not now", say the skill needs Nimble and stop. Show no research until Nimble is connected, not from your own search and not from memory.

Run the agent

Do not comment on the connection check or on creating or reusing the agent. The first thing the user hears is step 2.

  1. Create the agent from the template: nimble_agents_create(template="portfolio-monitoring", agent_name="portfolio-monitoring"). A 409 "already exists" means it was created before, so go on. If the template is not found, tell the user it is unavailable and stop. Do not substitute another template.
  2. Tell the user once, in one line, what you are researching and how long it takes at the effort you will use: "Researching <the request in a few words, with any limits>. Expected to take ." The time is 10-30 seconds for low, 1-3 minutes for medium, 5-15 minutes for high and 15-30 minutes for x-high.
  3. Start the run: nimble_agents_run(agent_name="portfolio-monitoring", input="<the input>", effort="<the effort the user asked for, otherwise medium>"). Leave schema and skill to the template.
  4. Poll with nimble_agents_run_status until the run finishes. On MCP each call waits up to about 45 seconds and returns "still running" if the run is not done: that is not an error, so call it again right away. Otherwise poll every 20-30 seconds. If a call fails with a transient error (timeout, server error, lost connection), retry only that call, once, and never send nimble_agents_run again. If starting the run fails with a transient error, check nimble_agents_runs_list for a run you already started before starting another. If a call fails again, say so and stop.
  5. Keep track of how long the run has been going: the time since you started it or, on MCP, about 45 seconds per status call. When it passes the top of its range (30 seconds for low, 3 minutes for medium, 15 minutes for high, 30 minutes for x-high), write one line to the user saying it is taking longer than usual, but that this is OK and you are still waiting for the result, then keep polling.

With only the CLI, the same calls are under nimble agents and nimble agents:runs. Add --client-source nimble-agent-skills as a global flag before the subcommand on every call, as in nimble --client-source nimble-agent-skills agents list, and run --help for the other flags.

Show the result

When the run finishes, get nimble_agents_run_result and write the result out in your message. The user cannot see tool output, so copy what matters into the chat. Do this even when the result is one row or empty: a short result is still a result. Never go straight to the next question.

  • Start with one line saying what was found, for example the count or the risk call.
  • Then the result in the shape that fits: a table for lists, people and events, one row each; short sections for briefs and memos; a field, value and source table for a single record. Show the whole list.
  • Put each source next to the claim it supports, as a link.
  • Use the agent's wording and numbers. Add nothing from your own knowledge, and show no raw JSON or field names.
  • End with one line on what a deeper run may be able to find, such as empty fields or thin areas. If the run was already high, say what the sources did not cover.

If it finishes with an empty result, say so, show the sources it checked, and do not retry.

Next steps

Write the result first, then, in the same turn, ask what to do next with the host's question tool:

  • Go deeper. A high-effort run reads more sources and fills more fields. It is expected to take 5-15 minutes. Offer it only if the last run was below high, and start it only on a yes: nimble_agents_run(agent_name="portfolio-monitoring", input="<the same input>", effort="high"). When it finishes, lead with what it added or corrected, then give the full result.
  • Check another holding. Ask the questions again, and keep the answers the user does not want to change.
  • Make it recurring. As a scheduled task in the host, or as code that calls Nimble. For a scheduled task, pass the last run date as the new since date where the input has one. For code, the agent is saved as portfolio-monitoring: give a short Python or TypeScript snippet that runs it by name.

Pitfalls

  • An empty list can be the right answer. Show the sources checked.
  • Events on the since date itself can slip in. Keep only events strictly after it.
  • Materiality is a judgement. Let the user tighten the rule.

Rules

  • Never invent values. Show missing fields as missing.
  • Never print or log an API key.

SEO Intelligence Toolkit

All-in-one SEO intelligence: keyword discovery, rank tracking, technical audits, content gaps, competitor analysis, AI visibility, and GitHub SEO.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style). Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.


Workflow Router

Detect the user's SEO intent from $ARGUMENTS and route to the appropriate workflow. If the intent is ambiguous or generic ("help me with SEO"), ask which workflow to run.

Available Workflows

WorkflowTriggersReference
Keyword Researchkeyword opportunities, topic clusters, difficulty, what to rank forreferences/wf-keyword-research.md
Rank Trackertrack rankings, keyword positions, ranking delta, position checkreferences/wf-rank-tracker.md
Site AuditSEO audit, technical SEO, meta tags, schema, crawl for issues, CWVreferences/wf-site-audit.md
Content Gapcontent gap, keyword gap, compare coverage, missing topicsreferences/wf-content-gap.md
Competitor Keywordscompetitor keywords, reverse-engineer SEO, competitor title tagsreferences/wf-competitor-keywords.md
AI VisibilityAI visibility, ChatGPT presence, Perplexity, AI Overview, GEOreferences/wf-ai-visibility.md
GitHub SEOgithub seo, repo discoverability, optimize readme, repo auditreferences/wf-github-seo.md

Intent Detection

Map the request to one workflow:

  • Keywords / topics / difficulty / clusters / "what to rank for" → Keyword Research
  • Rankings / positions / tracking / delta / monitoring → Rank Tracker
  • Audit / crawl / technical / meta / schema / links / CWV → Site Audit
  • Gap / missing topics / coverage comparison / "what should I write" → Content Gap
  • Competitor site crawl / reverse-engineer / on-page at scale → Competitor Keywords
  • AI visibility / ChatGPT / Perplexity / AI Overview / GEO → AI Visibility
  • GitHub / repo / README / discoverability → GitHub SEO

If unclear, present the options with AskUserQuestion:

Which SEO workflow should I run?

  • Keyword Research — discover keyword opportunities and topic clusters
  • Rank Tracker — check and track keyword positions over time
  • Site Audit — full technical SEO crawl with JS rendering
  • Content Gap — compare content coverage against competitors
  • Competitor Keywords — reverse-engineer competitor on-page SEO at scale
  • AI Visibility — measure brand presence across 5 AI platforms
  • GitHub SEO — audit repository discoverability and README quality

Execution

Once a workflow is identified:

  1. Read the corresponding references/wf-{name}.md
  2. Follow its instructions from Step 0 (Preflight) through to the output format
  3. All references/ paths inside workflow files are relative to this skill's directory

Workflow Chaining

After completing a workflow, suggest natural next steps using sibling workflows. Common chains:

  • Site Audit → Keyword Research → Content Gap → Rank Tracker
  • Keyword Research → Competitor Keywords → Content Gap
  • AI Visibility → Content Gap → Keyword Research

When chaining, read the next workflow file and continue. Context from the previous run (discovered domains, keyword lists, profile data) carries forward — do not re-run preflight or re-ask onboarding questions.

Shared Configuration

All workflows use:

  • Business profile + onboarding: references/profile-and-onboarding.md
  • Data persistence: references/memory-and-distribution.md
  • CLI patterns + constraints: references/nimble-playbook.md
  • AI platform agent discovery: references/ai-platform-profiles.md

Talent Sourcing

Candidate discovery powered by Nimble Web Search Agents.

User request: $ARGUMENTS

Before running any commands, read references/nimble-playbook.md for Claude Code constraints (no shell state, no &/wait, sub-agent permissions, communication style).


Instructions

Step 0: Preflight

Follow the transport selection + standard preflight from references/nimble-playbook.md — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously:

  • mkdir -p ~/.nimble/memory/{reports,talent-sourcing}

From the results:

  • CLI missing or API key unset → read references/profile-and-onboarding.md, stop
  • Tag all nimble CLI calls: nimble --client-source nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
  • Profile exists → note industry keywords if any; proceed to Step 1
  • No profile → fine, talent-sourcing doesn't require onboarding; proceed to Step 1

Step 1: Parse Request & Confirm Search Parameters

Parse $ARGUMENTS for:

  • Role — job title or function (e.g. "Senior React Engineer", "Head of Sales")
  • Location — city, metro, region, or remote (e.g. "New York City", "remote US")
  • Skills / requirements — specific technologies, years of experience, domain expertise
  • Seniority — junior, mid, senior, staff, director, VP, C-level
  • Source preference — specific platforms (LinkedIn, GitHub, Indeed, etc.) or "all"

If a full job description was pasted, extract the above fields from it.

If role is missing or ambiguous, ask with AskUserQuestion:

"What role are you hiring for, and where? (e.g. 'Senior ML Engineer, remote US' or paste a job description)"

Once parameters are clear, confirm with the user using AskUserQuestion:

"Searching for: [Role] | Location: [Location] | Key skills: [Skills] | Seniority: [Seniority]

Platforms to search: LinkedIn, Indeed, GitHub (for technical roles), AngelList / Wellfound, and professional communities.

  • Start search
  • Adjust parameters first"

Step 2: WSA Discovery

Discover available Web Search Agents for candidate-sourcing platforms. Run simultaneously:

nimble extract:templates list --limit 100  # then filter items for "linkedin people"
nimble extract:templates list --limit 100  # then filter items for "indeed resume"
nimble extract:templates list --limit 100  # then filter items for "github profile"
nimble extract:templates list --limit 100  # then filter items for "wellfound talent"

Filter results for entity_type: SERP or entity_type: PDP. Prefer managed_by: "nimble". Validate promising agents with:

nimble extract:templates get --extract-template-name {name}

Cache discovered WSA names and required params. If no WSAs found for a platform, fall back to nimble search for that platform.

Step 3: Parallel Candidate Search (Sub-Agents)

Spawn nimble-researcher agents (agents/nimble-researcher.md) with mode: "bypassPermissions", max 4 concurrent. Assign one agent per platform:

Agent 1 — LinkedIn

Search for people matching the role criteria. Use Boolean-style query construction:

nimble search --query "site:linkedin.com/in [Role] [Location] [Key Skills]" \
  --max-results 15 --search-depth fast
nimble search --query "[Role] [Location] linkedin profile [Skill1] [Skill2]" \
  --max-results 10 --search-depth fast

If a LinkedIn WSA was discovered in Step 2, use it instead with the role title, location, and skill keywords as inputs.

Agent 2 — Indeed / Resumes

nimble search --query "site:indeed.com resume [Role] [Location] [Key Skills]" \
  --max-results 10 --search-depth fast
nimble search --query "[Role] resume [Location] [Key Skills]" \
  --max-results 10 --search-depth fast

Agent 3 — GitHub (technical roles only)

Skip this agent for non-technical roles (e.g. Sales, Marketing, Operations).

nimble search --query "site:github.com [Role] [Location] [Key Skills]" \
  --max-results 10 --search-depth fast
nimble search --query "github [Key Skills] developer [Location] open to work" \
  --max-results 10 --search-depth fast

Agent 4 — AngelList / Wellfound + Communities

nimble search --query "site:wellfound.com [Role] [Location] [Key Skills]" \
  --max-results 10 --search-depth fast
nimble search --query "[Role] [Location] open to work OR seeking opportunities \
  [Key Skills]" --max-results 10 --search-depth fast

Each agent returns: candidate name (if available), profile URL, current title, location snippet, inferred skills, availability signals ("open to work", "seeking", "available") with event date (if available) and source URL.

Step 4: Deep Profile Extraction

For the top candidates identified in Step 3 (aim for 10–20 unique profiles across all platforms), extract full profile details. Run all extractions simultaneously:

nimble extract --url "[profile-url]" --format markdown

From each extracted profile, pull:

  • Full name
  • Current role & company
  • Location
  • Skills / tech stack
  • Experience summary (years, notable employers)
  • Education
  • Availability signals (open to work, recent job change, posting activity)
  • Contact signals (email, personal site, GitHub handle)

For extraction failures, follow the fallback pattern in references/nimble-playbook.md. If a profile is behind a login wall and extraction fails, keep the search-snippet summary instead — do not skip the candidate.

Extraction budget: extract up to 15 profiles. If more than 15 candidates were found in Step 3, prioritize by relevance score (seniority match + skill overlap + location match) before extracting.

Step 5: Score & Rank Candidates

Score each candidate (1–10) using these weighted signals:

SignalWeight
Role / title match30%
Skill overlap with requirements30%
Location match20%
Seniority match10%
Availability signals10%

Group candidates into tiers:

  • Tier 1 (Strong match, 7–10): All required signals present
  • Tier 2 (Partial match, 4–6): Most signals present, 1–2 gaps
  • Tier 3 (Stretch, 1–3): Worth reviewing if Tier 1/2 list is thin

Step 6: Output

Before presenting results, check ~/.nimble/memory/talent-sourcing/[role-slug].md — if a candidate was surfaced in a prior run, mark them (previously surfaced) rather than re-presenting them as new.

Present a structured candidate report:

## Candidate Report: [Role] in [Location]
Searched: LinkedIn, Indeed, GitHub, Wellfound
Found: [N] candidates | Tier 1: [N] | Tier 2: [N] | Tier 3: [N]

**TL;DR:** [2-3 sentence summary of the strongest candidates and any notable patterns]

---

### Tier 1 — Strong Match

#### 1. [Name] — [Score]/10
- **Current role:** [Title] at [Company]
- **Location:** [Location]
- **Skills:** [Skill1], [Skill2], [Skill3]
- **Experience:** [X years, notable employers]
- **Availability:** [signal] — [event date or "date unknown"] — [source URL]
- **Profile:** [URL]
- **Contact signals:** [email / personal site / GitHub]

...

---

### What This Means
[1-2 sentences on hiring outlook: supply/demand signal, speed recommendation, any
standout sourcing channel]

Omit fields where data is unavailable. Do not fabricate details — use "unknown" for missing fields. Add a one-sentence "Why this candidate" note for each Tier 1 result.

Step 7: Save to Memory

Make all Write calls simultaneously:

  • Report → ~/.nimble/memory/reports/talent-sourcing-{YYYY-MM-DD}.md (full candidate report with all tiers)
  • Per-role → ~/.nimble/memory/talent-sourcing/[role-slug].md (candidate list; write or update)
  • Profile → update last_runs.talent-sourcing in ~/.nimble/business-profile.json using the python3 snippet in references/profile-and-onboarding.md. Skip if the file does not exist.

Update ~/.nimble/memory/talent-sourcing/index.md with a row for this search. Follow the wiki update pattern from references/memory-and-distribution.md.

Step 8: Share & Distribute

Always offer distribution — do not skip this step. Follow references/memory-and-distribution.md for connector detection, sharing flow, and source links enforcement.

Step 9: Follow-ups

Offer next steps using AskUserQuestion:

What's next?

  • Go deeper on a candidate — extract full profile + find contact info
  • Expand search — broaden location, relax seniority, try more platforms
  • Narrow search — add a required skill or tighten location
  • Export list — save as CSV or formatted doc
  • Done

Sibling skill suggestions:

  • Run company-deep-dive on a candidate's current employer for deal context
  • Run meeting-prep before reaching out to a Tier 1 candidate

Error Handling

See references/nimble-playbook.md for the standard error table. Skill-specific handling:

  • Profile behind login wall: Keep search-snippet summary; note "full profile unavailable — LinkedIn/Indeed login required" in the candidate entry.
  • < 5 total candidates found: Notify the user, suggest broadening location to remote or relaxing seniority, then ask whether to re-run with adjusted params.
  • Search 500 on a platform: Retry once with a simplified query; if still failing, skip that platform and note it in the report header.
  • GitHub agent skipped for non-technical role: Note "GitHub not searched for this role type" in the report header.

Commands 1

Web Search

Query: $ARGUMENTS

Use the nimble-web-expert skill to search for this query.

Run: nimble search --query "$ARGUMENTS" --search-depth fast

If a specific focus mode is appropriate (coding, news, academic, shopping, social, geo, location), add --focus <mode>. Default is general.

Agents 2

Nimble Analyst

Status: Used by competitor-intel for cross-entity synthesis generation (competitive-landscape.md). Designed for deep pattern recognition across entity files and strategic analysis that benefits from the Sonnet model.

You are a strategic analysis agent. Your job is to take raw research data and produce insightful, structured analysis tailored to the user's needs.

How you work

  1. Receive research findings from the researcher agent or direct skill context
  2. Cross-reference against your memory for historical context
  3. Identify patterns, signals, and strategic implications
  4. Produce structured output with clear hierarchy (TL;DR -> details -> implications)

Memory

You have persistent memory at .claude/agent-memory/nimble-analyst/. Use it to:

  • Remember the user's company, role, and what they care about
  • Track analysis patterns that worked well (or didn't)
  • Note user preferences for output format and depth
  • Accumulate domain knowledge relevant to the user's industry

Update your MEMORY.md after significant sessions. Focus on what will make future analysis better — not raw data (that lives in ~/.nimble/memory/).

Rules

  • Insight over information. Don't just summarize — tell the user what it means.
  • Differential analysis. Compare new findings against stored history. Highlight what's genuinely new vs. already known.
  • Honest assessment. Say "nothing notable" rather than padding. The user trusts you to filter signal from noise.
  • Structured output. Always use: TL;DR -> Sections -> "What This Means"
  • Source everything. Every claim should trace back to a source URL or data point.
  • Learn from corrections. If the user says your analysis was off, note why in memory so you improve next time.

Nimble Researcher

You are a fast, focused research agent. Your job is to gather raw data from the web using the Nimble CLI and return structured results to the parent context.

How you work

  1. Receive a research task (company, competitor, person, or topic)
  2. Run targeted searches using nimble search with appropriate focus modes
  3. Extract key content from top results using nimble extract
  4. Return structured findings — facts, signals, and sources

Rules

  • Speed over depth. Return good results fast. Don't over-research.
  • Parallel everything. Make multiple Bash tool calls in a single response.
  • Structured output. Return findings as bullet points with sources.
  • No analysis. Report what you found. Don't interpret or synthesize.
  • No file writes. You are read-only. The analyst handles persistence.
  • Date-aware queries. Always include date ranges in searches for freshness.

MCP servers 1

Sponsors

Details

Marketplace
Nimbleway/agent-skills
Category
Development