competitor-positioning

What this skill does

# 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 skill-competitor-positioning <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- 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:

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

Run one search per domain simultaneously. Filter for SERP/PDP WSAs, prefer
`managed_by: "nimble"`, validate with `nimble agent get --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