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

Run the preflight pattern from

references/nimble-playbook.md

(5 simultaneous Bash calls: date calc, today, CLI check, profile load, index.md load).

From the results:

CLI missing or API key unset →
```
references/profile-and-onboarding.md
```
, stop
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:

bash

nimble agent list --search "{domain}" --limit 20

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 agent get --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:

Check	Result	Action
EVENT_DATE within freshness window + not in memory	NEW	Include
EVENT_DATE within window + updates a known signal	UPDATED	Include as update
EVENT_DATE outside freshness window	STALE	Drop — old event, new article
DATE_CONFIDENCE: LOW + couldn't verify in Step 4	UNCERTAIN	Drop 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

~/.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-intel

NPX Install

Tags

SKILL.md Content