Competitor analysis skill

README.md

@@ -22,6 +22,7 @@ This plugin includes the following skills (see `skills/` for details):
 | [agent-experience](skills/agent-experience/SKILL.md) | Audit how agent-friendly a product, SDK, or docs site is — drops Claude subagents at it with tiny prompts, captures their traces, and scores setup friction, speed, error recovery, and doc quality |
 | [company-research](skills/company-research/SKILL.md) | Discover target companies matching your ICP using the Browserbase Search API, deep-research each one, and score fit into a research report and CSV |
 | [event-prospecting](skills/event-prospecting/SKILL.md) | Extract speakers from a conference page, filter their companies against your ICP, and deep-research the best-fit people into a person-first prospecting report |
+| [competitor-analysis](skills/competitor-analysis/SKILL.md) | Auto-discover a company's competitors via the Browserbase Search API, deep-research each across marketing, signal, benchmark, and strategic-diff lanes, and compile a browsable HTML report with an overview, per-competitor deep dives, a feature/pricing matrix, and a mentions feed |
 
 ## Installation
 

skills/competitor-analysis/.gitignore

@@ -0,0 +1,2 @@
+profiles/*.json
+!profiles/example.json

skills/competitor-analysis/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browserbase, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/competitor-analysis/references/battle-card-subagent.md

@@ -0,0 +1,127 @@
+# Battle Card subagent prompt
+
+## Contents
+- [Placeholders to substitute](#placeholders-to-substitute) — `{OUTPUT_DIR}`, `{COMPETITOR_SLUG}`, etc.
+- [Prompt](#prompt) — full subagent instruction template (paste with placeholders filled in)
+- [Wave management](#wave-management) — launch policy: one Agent message per run, all competitors in parallel
+
+Main agent substitutes placeholders per competitor. Launch AFTER Step 5c fact-check completes — this lane depends on `matrix.json` cells having `sources` URLs.
+
+## Placeholders to substitute
+
+- `{OUTPUT_DIR}` → the absolute path to the output directory (the per-run directory from Step 0; no `~` or `$HOME`)
+- `{COMPETITOR_SLUG}` → e.g. `rival-co`
+- `{COMPETITOR_NAME}` → e.g. `Rival Co`
+- `{USER_SLUG}` → e.g. `exa`
+- `{USER_COMPANY_NAME}` → e.g. `Exa`
+- `{USER_PRODUCT_ONE_LINER}` → pulled from Step 1 profile
+- `{USER_WINNING_SUMMARY}` → matrix.json `userCompany.winningSummary`
+- `{USER_LOSING_SUMMARY}` → matrix.json `userCompany.losingSummary`
+
+## Prompt
+
+```
+You are the Battle Card synthesis subagent. Produce an evidence-grounded
+battle card a real AE would use on a call.
+
+TOOL RULES — CRITICAL, FOLLOW EXACTLY:
+1. You may ONLY use the Bash tool. No exceptions.
+2. BANNED TOOLS: WebFetch, WebSearch, Write, Read, Glob, Grep, browse cloud search,
+   browse cloud fetch — ALL BANNED. This is a SYNTHESIS lane, not a research lane.
+   You read files that already exist; you do not make new network calls.
+3. Read ALL inputs in ONE Bash call via `cat`. Write output in ONE heredoc.
+4. NEVER use ~ or $HOME — full literal paths only.
+
+INPUTS (all already exist on disk — read in one Bash call):
+- {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.marketing.md
+- {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.discussion.md
+- {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.social.md
+- {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.news.md
+- {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.technical.md
+- {OUTPUT_DIR}/{USER_SLUG}.md              # user's own merged file
+- {OUTPUT_DIR}/matrix.json                 # fact-checked matrix — cells
+                                           # must have a `sources` URL to
+                                           # be trustworthy; reject any
+                                           # cell without one
+
+CONTEXT:
+- User's company: {USER_COMPANY_NAME}
+- User's product: {USER_PRODUCT_ONE_LINER}
+- User's verified moats (from matrix.json userCompany.winningSummary):
+  {USER_WINNING_SUMMARY}
+- User's verified gaps (from matrix.json userCompany.losingSummary):
+  {USER_LOSING_SUMMARY}
+- Competitor: {COMPETITOR_NAME}
+- Competitor slug: {COMPETITOR_SLUG}
+
+TASK — produce three sections, every claim traceable to an input bullet
+or matrix.sources URL:
+
+1. LANDMINES (3-5 items) — concrete verifiable facts that HURT
+   {COMPETITOR_NAME} in a deal. Each:
+   - States a specific, verifiable fact (not "their results are weak" —
+     "they scored 73% nDCG@10 on the Nov 2025 search-bench leaderboard")
+   - Cites a source URL pulled from an actual bullet in one of the
+     input partials (Mentions / Benchmarks / Research Findings)
+   - Includes a one-line "how to use it" talking point
+   - Prefers third-party sources over competitor's own marketing
+   - If no evidence exists for a potential landmine, OMIT it. 3 cited
+     landmines > 5 half-invented ones.
+
+2. OBJECTION HANDLERS (3-5 items) — "If prospect says: {objection} →
+   You say: {response}". Objections should reflect the competitor's
+   strongest marketing lines (e.g. if their homepage says "99.99%
+   uptime", the objection is "we hear {user} has no uptime guarantee").
+   Responses must reference a real user moat from winningSummary —
+   never a hallucinated feature.
+
+3. TALK TRACKS (2-3 items) — 1-2 sentence opening pitches. Each leads
+   with a user winningSummary differentiator and names a specific gap
+   in {COMPETITOR_NAME}. Confident, factual, no hyperbole.
+
+ADVERSARIAL SELF-CHECK before writing:
+- [ ] Every landmine cites a URL that appears in one of the input
+      partials. No invented URLs.
+- [ ] No claim contradicts a fact-checked cell in matrix.json.
+- [ ] No talk track claims a user feature where matrix.json shows
+      userCompany.features[X] = false.
+- [ ] Objections are realistic (what a prospect would actually raise),
+      not strawmen.
+
+OUTPUT — write via a single heredoc to
+  {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.battle.md
+
+cat << 'BATTLE_MD' > {OUTPUT_DIR}/partials/{COMPETITOR_SLUG}.battle.md
+---
+competitor_name: {COMPETITOR_NAME}
+lane: battle
+generated_at: {YYYY-MM-DD}
+---
+
+## Battle Card
+
+### Landmines
+
+- **{one-line fact}** — {how to use it in the call}. (source: {url})
+
+### Objection Handlers
+
+- If they say: "{objection verbatim}"
+  You say: {response citing user's moat} (evidence: {url})
+
+### Talk Tracks
+
+1. {1-2 sentence pitch}
+BATTLE_MD
+
+REPORT BACK only one line:
+  "{COMPETITOR_SLUG} battle: {N} landmines, {M} objections, {K} tracks, all cited."
+
+Do NOT return the card content.
+```
+
+## Wave management
+
+- Launch 1 battle-card subagent per competitor. All can run in parallel (synthesis is fast and uses no shared state beyond already-written partials).
+- Depth: only run in `deep` or `deeper` modes. `quick` mode does not have the research depth to ground battle cards credibly.
+- Budget: ~3-5 Bash calls per subagent (1 big cat, 1 big heredoc, maybe 1-2 sanity checks).

skills/competitor-analysis/references/battle-card.md

@@ -0,0 +1,91 @@
+# Battle Card — format spec
+
+The Battle lane is the **6th** subagent lane in deep/deeper mode. It runs AFTER Step 5c fact-check completes — it reads only existing partials + the fact-checked `matrix.json`, **never makes new `browse cloud` calls**. This is a pure synthesis lane.
+
+Output file: `{OUTPUT_DIR}/partials/{slug}.battle.md`. `merge_partials.mjs` unions its `## Battle Card` section into the consolidated `{slug}.md`. `compile_report.mjs` renders it as a brand-accented card on the per-competitor HTML page.
+
+## The three sections
+
+### Landmines (3-5 items)
+
+Concrete, verifiable facts about the competitor that **hurt them in a deal**. Every item must cite a URL from an existing partial (Mentions, Benchmarks, or Research Findings). Prefer third-party evidence (benchmarks, reviews, news) over the competitor's own marketing — marketing claims are weak ammunition.
+
+Format:
+```
+### Landmines
+
+- **{one-line factual claim}** — {how an AE uses it in the call}. (source: {url})
+```
+
+Example:
+```
+- **Rival Co placed 4th of 7 on the Nov 2025 search-bench retrieval leaderboard (73% nDCG@10)** — use if prospect cares about relevance, but only after confirming their volume tier; Rival Co's reranking add-on is paywalled behind Scale ($499/mo). (source: https://github.com/example-org/search-bench)
+```
+
+### Objection Handlers (3-5 items)
+
+Format: "if prospect says X → you say Y, citing a real user moat from `userCompany.winningSummary`." Every response must reference a feature/integration the fact-checked matrix confirms the user has. Never respond with a claim that contradicts a fact-checked matrix cell.
+
+Format:
+```
+### Objection Handlers
+
+- If they say: "{objection verbatim}"
+  You say: {response citing user's moat} (evidence: {url})
+```
+
+Example:
+```
+- If they say: "Rival Co is $99/mo cheaper than your Scale tier"
+  You say: "Rival Co's reranking is a paid add-on you'll need for production relevance — once you add it the price gap closes. Our Scale tier includes neural reranking and a research endpoint; matrix.json confirms Rival Co's feature set doesn't cover the research API." (evidence: https://docs.rivalco.com/changelog)
+```
+
+### Talk Tracks (2-3 items)
+
+One-to-two sentence opening pitches an AE can memorize. Lead with a user winningSummary differentiator; name the specific gap in the competitor. No hyperbole, no claims not grounded in fact-checked matrix cells.
+
+Format:
+```
+### Talk Tracks
+
+1. {1-2 sentence pitch}
+```
+
+Example:
+```
+1. For production RAG, Exa is the only provider in the category with BOTH a first-party neural index AND a dedicated research/answer endpoint — Rival Co shipped neither, Serper shipped neither, and one competitor replaced its answer endpoint with a thin LLM wrapper last quarter.
+```
+
+## Markdown file shape
+
+```markdown
+---
+competitor_name: Rival Co
+lane: battle
+generated_at: 2026-04-24
+---
+
+## Battle Card
+
+### Landmines
+- **Fact 1** — usage. (source: url)
+- **Fact 2** — usage. (source: url)
+
+### Objection Handlers
+- If they say: "..."
+  You say: ... (evidence: url)
+
+### Talk Tracks
+1. Pitch 1
+2. Pitch 2
+```
+
+## Quality gates — Adversarial self-check (subagent MUST run before writing)
+
+- [ ] Every landmine cites a URL that appears in one of the input partials (Mentions / Benchmarks / Research Findings). No invented URLs.
+- [ ] No claim contradicts a fact-checked cell in `matrix.json` (cells must have a `sources` URL to be trustworthy).
+- [ ] No talk track claims a user feature where `matrix.json` shows `userCompany.features[X] = false`.
+- [ ] Objections are realistic — they're what a prospect would actually raise based on the competitor's strongest marketing lines, not strawmen.
+- [ ] Third-party evidence preferred over competitor's own marketing (benchmarks, reviews, news > their docs/pricing).
+
+If a potential landmine has no evidence in the partials, OMIT it. It is better to ship 3 cited landmines than 5 half-invented ones.

skills/competitor-analysis/references/example-research.md

@@ -0,0 +1,130 @@
+# Example Competitor Research File
+
+## Contents
+- [Template](#template) — full worked example for a fictional "Rival Co"
+- [Field Rules](#field-rules) — frontmatter fields, body section order, mention/findings format
+- [Writing via Bash Heredoc](#writing-via-bash-heredoc) — required pattern for subagents to avoid permission prompts
+
+Each enrichment subagent writes one markdown file per competitor to `{OUTPUT_DIR}/{competitor-slug}.md`, where `{OUTPUT_DIR}` is the per-run Desktop directory set up by the main agent in Step 0 (e.g., `~/Desktop/acme_competitors_2026-04-23/`). The YAML frontmatter contains structured fields for report/matrix compilation. The body contains per-section research plus aggregated mentions and benchmarks.
+
+## Template
+
+```markdown
+---
+competitor_name: Rival Co
+website: https://rivalco.com
+tagline: The fastest way to give your agents the web
+positioning: Developer-first web search API
+product_description: Web search & retrieval API for AI agents and RAG pipelines
+target_customer: AI engineers, RAG/agent teams, SaaS companies
+pricing_model: Usage-based + seat tiers
+pricing_tiers: Free (1K searches) | Pro $99/mo | Scale $499/mo | Enterprise Contact
+key_features: web search API | neural/semantic search | site crawler | reranking | live crawl
+integrations: LangChain | LlamaIndex | Python SDK | TypeScript SDK
+headquarters: San Francisco, CA
+founded: 2023
+employee_estimate: 11-50
+funding_info: Seed, $5M (2024)
+strategic_diff: Similar retrieval API; weaker neural relevance, but cheaper entry tier
+---
+
+## Product
+Web search and retrieval API for AI agents. Exposes a REST search endpoint with both
+keyword and semantic/neural modes, plus a site crawler and live-crawl fallback.
+Positioned at AI engineers building RAG and agent pipelines.
+
+## Pricing
+- Free: 1K searches/month, 1 API key
+- Pro ($99/mo): 100K searches, reranking, basic support
+- Scale ($499/mo): 1M searches, neural search, live crawl, higher rate limits
+- Enterprise: custom pricing, SSO, dedicated support
+
+## Features
+- Keyword + neural/semantic search modes
+- Site crawler with scheduled recrawls
+- Result reranking and content highlights
+- Live-crawl fallback for fresh pages
+- REST API with JSON responses
+- Python and TypeScript SDKs
+
+## Positioning
+Marketing emphasizes "AI-native" and developer-first DX. Landing page hero:
+"Give your agents the web." Targets solo devs through mid-market AI teams.
+
+## Comparison vs {user_company}
+- **Overlaps**: Web search API, neural search mode, crawler, LangChain integration
+- **Gaps**: No dedicated research/answer endpoint, weaker neural relevance benchmarks, no news endpoint
+- **Where they win**: Lower entry price ($99 vs $199), simpler pricing tiers
+- **Where you win**: Stronger neural relevance (per public benchmarks), research API, larger integration ecosystem
+
+## Mentions
+- **[Benchmark]** retrieval-quality leaderboard — Rival Co 73% nDCG@10, 4th of 7 tested (source: https://github.com/example-org/search-bench/pull/92, 2026-03-14)
+- **[Comparison]** Exa vs Rival Co — side-by-side review (source: https://example.com/exa-vs-rivalco, 2026-02-01)
+- **[Reddit]** r/LangChain thread: "Moved from Rival Co to X after relevance issues" — 24 upvotes (source: https://reddit.com/r/LangChain/comments/abc123)
+- **[HN]** "Show HN: Rival Co raises seed to build..." — 112 points, 48 comments (source: https://news.ycombinator.com/item?id=12345)
+- **[LinkedIn]** CEO post on product launch — 412 reactions (source: https://linkedin.com/posts/rivalco-launch)
+- **[YouTube]** "Rival Co vs Exa" review by Dev YouTuber — 8.2K views (source: https://youtube.com/watch?v=xyz)
+- **[News]** TechCrunch coverage of seed round (source: https://techcrunch.com/2024/11/rival-co-seed)
+- **[Review]** G2 4.3/5 (31 reviews), main complaint: stale results (source: https://g2.com/products/rival-co)
+
+## Benchmarks
+- **search-bench PR #92** — Rival Co 73% nDCG@10 on retrieval quality, 4th of 7 tested (https://github.com/example-org/search-bench/pull/92)
+- **retrieval-latency blog** — Rival Co 480ms p50, 2nd fastest (https://example.com/search-latency-2026)
+
+## Research Findings
+- **[high]** Usage-based pricing starts at $99/mo for 100K searches (source: rivalco.com/pricing)
+- **[high]** Series seed, $5M raised Nov 2024 (source: TechCrunch)
+- **[medium]** CEO LinkedIn emphasizes AI-agent use cases (source: linkedin.com/in/rivalco-ceo)
+- **[low]** Possibly a team under 20 based on careers page (source: rivalco.com/careers)
+
+## Battle Card
+
+### Landmines
+- **Rival Co scores 73% nDCG@10 on the search-bench leaderboard (4th of 7 tested)** — use against relevance-sensitive prospects; they rank below Exa on the same test. (source: https://github.com/example-org/search-bench/pull/92)
+- **G2 average 4.3/5 with "stale results" as top complaint across 31 reviews** — cite when prospect raises freshness concerns. (source: https://g2.com/products/rival-co)
+
+### Objection Handlers
+- If they say: "Rival Co is $99/mo — cheaper than your Pro tier"
+  You say: "Cheaper upfront, but compare total cost of poor relevance — their 73% nDCG@10 means more irrelevant results your agent has to filter or re-query, and re-queries aren't free." (evidence: https://github.com/example-org/search-bench/pull/92)
+
+### Talk Tracks
+1. For RAG pipelines where relevance drives answer quality, Exa ships a neural index and a dedicated research/answer endpoint as table stakes; Rival Co has neither in their 2024 product set.
+```
+
+## Field Rules
+
+- **YAML frontmatter**: All structured fields go here. Extracted for matrix + CSV compilation.
+- **`pricing_tiers`**: Pipe-separated (`|`) with tier name + short price. `compile_report.mjs` parses on `|` for the matrix view.
+- **`key_features`**, **`integrations`**: Pipe-separated lists.
+- **`strategic_diff`**: One-line summary (shown in overview table).
+- **Body sections**: `## Product`, `## Pricing`, `## Features`, `## Positioning`, `## Comparison vs {user_company}`, `## Mentions`, `## Benchmarks`, `## Research Findings`, `## Battle Card` (deep/deeper modes only; synthesized by the Battle lane after fact-check).
+- **Mentions format**: `- **[SourceType]** title | snippet (source: url, date)` — `SourceType` is one of `Benchmark`, `Comparison`, `News`, `Reddit`, `HN`, `LinkedIn`, `YouTube`, `Review`, `Podcast`, `X`.
+- **Findings format**: `- **[confidence]** fact (source: url)` — `confidence` is `high`, `medium`, or `low`.
+- **Filename**: `{OUTPUT_DIR}/{competitor-slug}.md` where slug is lowercase, hyphenated.
+
+## Writing via Bash Heredoc
+
+Subagents write these files using bash heredoc to avoid security prompts. Use the full literal `{OUTPUT_DIR}` path — no `~` or `$HOME`:
+
+```bash
+cat << 'COMPETITOR_MD' > {OUTPUT_DIR}/rival-co.md
+---
+competitor_name: Rival Co
+website: https://rivalco.com
+...
+---
+
+## Product
+...
+
+## Pricing
+...
+
+## Mentions
+- **[Benchmark]** ...
+COMPETITOR_MD
+```
+
+Use `'COMPETITOR_MD'` (quoted) as the delimiter to prevent shell variable expansion.
+
+**IMPORTANT**: Write ALL competitor files in a SINGLE Bash call using chained heredocs to minimize permission prompts.