competitor-gap

---
name: competitor-gap
description: Finds the subjects your rivals rank for and you never covered, ranked and with a verdict on each. Use when competitors keep appearing for searches you thought were yours.
---

# Find the pages ranking for you that you never wrote

A ranked list of what your three closest rivals cover and you do not.

## Claude does

1. Ask for four things and refuse to start without them: your domain, three rival domains, your market and language, your service area if local. If the user cannot name three rivals, tell them to search five of their own core terms and read off who keeps appearing.
2. Verify those rivals. Search the core terms and confirm each domain appears. A rival who never ranks for the same queries produces a gap list nobody searches for.
3. Use public pages only: sitemaps, titles, H1s, slugs. Refuse to guess traffic, volume or revenue you cannot see.
4. Build the gap the superseo-skills way: compare against the top three ranking pages per topic, not a rival's whole site. A gap counts only when two of the three rivals cover it and you do not. One rival is a lead, not a finding.
5. Sort by buying intent: money pages, comparison and alternative pages, questions asked before buying. Drop anything that cannot end in an enquiry.
6. Size each gap from the published CTR-by-position table, and say that positions 1 to 10 differ hugely and AI Overviews and local packs cut clicks further. Label every figure an estimate.
7. Verdict each gap with a stated trigger, in SE Ranking's shape: WRITE, MERGE INTO an existing page, or SKIP.

## Then Codex does

Codex takes the mechanical half: fetching four sitemaps, pulling titles, H1s and slugs from thousands of URLs, de-duplicating near-identical topics across three domains, diffing against your own site, and writing the table plus a CSV. Slow, repetitive fetching and string work. Fill the placeholders first.

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

Placeholders Claude fills in first: {YOUR_DOMAIN}, {COMPETITOR_1}, {COMPETITOR_2}, {COMPETITOR_3}, {MARKET_AND_LANGUAGE}, {CORE_TERMS}.

## Claude checks

1. Open five gap rows at random and load the rival URL. Page gone, or not covering the claimed topic, means the crawl is wrong.
2. Check the reverse: five topics you already cover must not appear as gaps. A false gap sends someone to rewrite what they have.
3. Confirm every finding has two or more rivals behind it, single-rival items sitting in the leads list.
4. Verify no traffic or volume figure is presented as measured. The research found vendor percentages repeated as fact that the source never stated; police that here.
5. Confirm the list would not create doorway pages. Over 30 near-identical variants gets cut back, with the reason stated.
6. Any check fails, return the rows to Codex and rerun. Never patch the table by hand.

## Rules

- A gap is real only when a rival page ranks for the query, not merely exists.
- Compare against the top three ranking pages, never a rival's whole site.
- Never present an estimate as a measurement, or quote a percentage a source did not state.
- Never produce 30 or more near-duplicate location pages from one gap.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude does the crawling and tabulation itself in smaller batches, and says so up front.

## Built from

- inhouseseo/superseo-skills, https://github.com/inhouseseo/superseo-skills, 305 stars via api.github.com, 5 Sep 2026; top-three gap method, CTR-by-position table.
- seranking/seo-skills, https://github.com/seranking/seo-skills, 135 stars via api.github.com, 5 Sep 2026; numbered workflow, evidence folder, verdicts with triggers.
- AgriciDaniel/claude-seo, https://github.com/AgriciDaniel/claude-seo, 16,344 stars via api.github.com, 5 Sep 2026; the 30-page and 50-page doorway limits.

# Find the pages ranking for you that you never wrote - Codex task

Crawl public pages and build a topic gap table. You have no memory of any prior conversation; everything needed is below.

## You are given

- {YOUR_DOMAIN} - the client's own website.
- {COMPETITOR_1}, {COMPETITOR_2}, {COMPETITOR_3} - three rival domains in the same search results.
- {MARKET_AND_LANGUAGE} - country and language the pages are judged in.
- {CORE_TERMS} - the subjects the client sells, used to decide relevance.

## Produce

Everything goes in an `evidence/` folder so any row can be re-checked.

1. `evidence/inventory-<domain>.csv`, one per domain, one row per public URL. Columns: url, page_title, h1, slug_words, last_modified_from_sitemap, http_status. Sources: sitemap.xml (follow sitemap index files), Sitemap lines in robots.txt, on-site navigation. Skip 404s, off-domain redirects, and paginated, tag or author archives.
2. `evidence/topics.csv`, one row per normalised topic. Columns: topic, covered_by_you, covered_by_c1, covered_by_c2, covered_by_c3, competitor_count, example_urls. Normalise by lower-casing, stripping stop words, and merging topics whose title and slug words overlap by 70 per cent or more.
3. `gap-report.md`. A table of every topic where covered_by_you is no and competitor_count is 2 or more, sorted by competitor_count then by how many of {CORE_TERMS} the topic touches, split into three sections: money pages, comparison and alternative pages, questions asked before buying. Below it, a short list of topics only one rival covers, labelled leads, not findings.
4. `gap-report.csv`, the same rows machine readable.

## Rules

- Public pages only. No logins, no paywalled content, nothing robots.txt disallows. Roughly one request per second per domain.
- Never invent a URL, title, traffic figure or keyword volume. Not fetched means not in the table.
- Do not estimate search volume or traffic. That is not your half of the job.
- Every claimed rival topic needs a real example URL that returned HTTP 200 during this run.
- If a location or service pattern would create 30 or more near-identical rows, collapse them into one row, note the count, and print a warning. Never emit 50 or more variants of the same page.
- British English. No em dashes.
- A missing or unreadable sitemap is reported, never filled in with guesses.

## Return

Print to stdout, in order:

1. The four file paths written.
2. Per domain: URLs discovered, URLs fetched with status 200, URLs skipped and why.
3. Counts of topics with competitor_count 3, then 2, then 1.
4. The top ten gap rows as plain text: topic, competitor_count, one example URL.
5. Any domain whose sitemap was missing, blocked or unreadable.
6. Any collapsed near-duplicate pattern and how many rows it stood in for.