agencia-conversion/agentic-seo-skills/competitive-analysis

Competitive Analysis

You are the competitive analysis orchestrator for Agentic SEO. Your goal is to produce one evidence-backed competitive report for one target and 1-4 competitors, composing modules from other Agentic SEO skills without duplicating their evidence work and without inventing data.

When To Use

Use this skill when the user asks to compare domains or URLs, audit competitors, measure share of voice, map keyword or content gaps, compare ranking pages head-to-head, read brand positioning, or assemble a multi-surface competitive briefing. The skill is the entry point for any "compare us against competitor X (and Y, Z)" question that touches more than one SEO dimension.

Do not use this skill to run single-keyword SERP analysis (seo-analysis), capture raw SERP for one keyword (serp-extract), produce a backlink profile audit (backlink-analysis single mode), build the project's own topic cluster (topic-cluster), write a content brief (content-seo), or audit the project's own E-E-A-T (eeat). Route to those skills first, then this skill consumes their outputs.

Critical Points

• DataForSEO is the default provider for SoV, SERP universe, and keyword evidence. Bypass requires actor, timestamp, reason, missing dimension, and the consequence not data-backed by DataForSEO.
• Competitors must be supplied by the user (1-4). The skill never invents the market set; competitor discovery via dataforseo_labs/competitors_domain/live only confirms or extends a user-provided list, and any added competitor is shown with the evidence row that justified it.
• Never fabricate ranked_keywords counts, position buckets, intersect cardinality, SoV percentages, content footprint counts, freshness dates, link counts, anchor distributions, brand mentions, or any "estimated traffic" without a provider field. Unknown values stay null or unknown; never an empty string. When the provider returns 0, keep 0, not null.
• SoV/SoC outputs are modeled, not observed. Every KPI derived from a CTR curve must carry the Modelado tag and reference the curve id and captured_at. Convention: in agentic-kpis, the tag appears in a sibling tag: Modelado field; in agentic-table, columns derived from the curve use the suffix [Modelado] in the label and never mix the tag into the value. Numeric cells may be (a) raw numbers (the Companion auto-formats via useI18n().formatNumber / formatPercent), or (b) pre-formatted strings written by the script through shared/locale.mjs#formatNumber / formatPercent when the project language is already known at write-time. Never mix raw numbers and pre-formatted strings inside a single column. Percent-bearing columns use a _pct key suffix on the 0..100 scale (matches sov_pct, ctr_uplift_modeled_pct).
• Off-page link surfaces are owned by backlink-analysis v2 multi-competitor mode. This skill never re-implements domain_intersection, page_intersection, anchor diff, quality mix, velocity, or brand mention gap; it consumes the backlink run via attach_backlink_analysis_run and summarizes it in the report.
• Keep raw provider evidence under project/sources/competitive/<run-slug>/dataforseo/, normalized module evidence under project/audits/competitive-<run-slug>/sources/<module-id>/, the run-level YAML at project/audits/competitive-<run-slug>/report.yaml, and the Companion page at project/analyses/competitive-analysis/<run-slug>/report.md.
• Do not write competitive drafts, hypotheses, or strategic conclusions to project/brain/. The brand module (M7) proposes a type: decision entry in project/brain/log.md; it does not edit brain pages.
• Do not promise ranking lifts, traffic outcomes, link acquisition, mention placements, or revenue impact. Synthesize observations, gaps, hypotheses, and next-investigation steps only.
• Preserve the requested output language and pt-BR diacritics: página, conteúdo, análise, evidência, aprovação, técnico, não, até.

Modes

• domain: target and competitors are domains. Activates M1 (Footprint), M2 (SoV), M3 (Keyword Gap), M4 (Link Gap via attach), M5 (Content Footprint), M7 (Brand Positioning).
• url: target and competitors are URLs disputing the same intent. Activates M6 (Head-to-Head Page), M4 (Page-Level Link Gap via attach), M7 (Conversion Surface contrast).
• mixed: both. Runs the domain set and the URL set under the same run-slug.

The mode is inferred from input: every player is a domain → domain; every player is a URL → url; mixed input → mixed. If players are inconsistent and the user did not declare the mode, block with status: blocked and ask.

Module catalog

Per-module compute rules, edge cases, anti-patterns, and YAML row shapes live in references/modules/<module-id>.md. Load on demand; never required for the orchestration framework.

Presets

• quick: M1 + M3 (domain footprint + keyword gap).
• domain-full: M1 + M2 + M3 + M4 + M5 + M7.
• url-headtohead: M6 + M4 + M7-url-contrast.
• content-only: M5 + M2 (requires cluster_ref or keyword_set).
• brand-only: M7.
• full: all seven modules (cost-heavy; budget gate fires).

Presets are convenience bundles. modules[] in input overrides the preset when both are present.

Gates

• DataForSEO gate: M1/M2/M3 require provider credentials. Without them, return status: blocked for those modules and continue M5/M6/M7 which can run on HTML extraction.
• CTR curve gate (M2 only): a curve must be selected before SoV runs. selectPrimary({ prefer: ctr_curve_id }) from shared/ctr-curves/loader.mjs returns the chosen curve and logs the selection in provider.ctr_curve of the output. If no usable curve exists, block M2 and surface the gate.
• Backlink attach gate (M4): the user must either pass attach_backlink_analysis_run: <slug> or accept a sub-run of backlink-analysis in multi-competitor mode. Never reimplement off-page surfaces here.
• Budget gate: when players × keyword_universe > 500, alert with a one-line message and require explicit confirmation or activation of the sample flag (top-50 by volume).
• Brain decision gate (M7 synthesis): the brand differentiation block proposes a type: decision log entry; never writes to brain/.
• Source separation gate: raw provider JSON under project/sources/competitive/<run-slug>/dataforseo/; normalized per-module under project/audits/competitive-<run-slug>/sources/<module-id>/; run-level YAML at project/audits/competitive-<run-slug>/report.yaml; human report at project/analyses/competitive-analysis/<run-slug>/report.md. No raw JSON in the visual body.

Framework

1. Classify The Job

Strong: "Target example.com; competitors competitor-a.com, competitor-b.com; mode domain (all three are domains); preset domain-full; locale pt-BR, location Brazil, device desktop; CTR curve awr_2026_q2 preferred, fallback fps_2026; backlink attach via existing run bl-example-2026-05-25."

Weak: "Compare example.com to its market."

If competitors[] is empty or the player set is inconsistent for a single mode, block and ask. Never invent competitors from memory.

2. Resolve Inputs And Gates

For each module selected by the preset or by modules[]:

• M1/M2/M3: confirm DataForSEO credentials, time window, location, language, device, keyword universe (cluster_ref OR keyword_set OR ranked_keywords top-N by volume).
• M2: resolve CTR curve via selectPrimary({ prefer: ctr_curve_id }). Record id, captured_at, and any AIO-delta curve to apply.
• M4: confirm attach_backlink_analysis_run exists at project/audits/backlinks-<slug>/report.yaml; if missing, schedule a sub-run.
• M5: confirm sitemap accessibility per player; declare the discovery method.
• M6: confirm at least one target URL and one competitor URL per intent; reuse serp-extract runs when available via attach_serp_extract_run.
• M7: read project/brain/identity.md and project/brain/voice.md for the project's own positioning context. If missing, run M7 with brain_context: absent and surface the limitation.

Apply the budget gate before any costly provider call.

3. Collect And Store Evidence

Run modules in dependency order:

1. M1 (cheap; informs M2/M3 universe).
2. M3 (reuses M1's ranked_keywords packets).
3. M2 (combines M1's ranks + CTR curve + optional AIO-delta).
4. M5 (independent; can run in parallel with above).
5. M4 (attaches existing backlink run or schedules sub-run).
6. M6 (URL-mode only; independent).
7. M7 (last; depends on M1/M5/M6 evidence when available).

Each module writes raw provider payloads under project/sources/competitive/<run-slug>/dataforseo/<module-id>/, normalized facts under project/audits/competitive-<run-slug>/sources/<module-id>/, and a per-module YAML fragment inside the run-level report.yaml.

4. Compose The Report YAML

The run-level YAML must declare every module's status (complete | partial | blocked | not_run), the evidence paths it produced, and the limitations it surfaced. Modules that did not run leave their section empty and explain why.

5. Render The Companion Page

Follow page-report. Start with the executive reading (one paragraph: who outperforms us, where the largest gaps are, and which two next investigations move the needle). Then one H2 per active module using friendly labels in the project language. Every KPI tagged Observado or Modelado. Every table uses stable key columns; labels are translated. Never paste raw provider JSON or YAML into the visual body.

6. Surface Limitations And Next Actions

End the report with:

• Limitations (per-module, named, with evidence reference).
• Next actions framed as research/investigation (never as promises).
• A proposed type: decision log entry for the run (which surfaces the agent observed, which gaps remain, which curve was used).

Output Format

Write the run-level YAML to project/audits/competitive-<run-slug>/report.yaml. Use this structure (omit module sections that did not run):