Groups keywords by shared Google results, plans one page per group with its core page to link up to, validates the map and keeps a Google Sheet in sync.
---
name: "topical-map-builder"
description: "Build and grow a topical map from your keyword list: group keywords by shared Google top-10 results (3 or more shared = one page), plan one page per group with a category, type and core page to link up to, validate, and sync to a Google Sheet."
---
# Topical map (your site)
> **Shared from the growthvibes.ai content pipeline.** [How the whole pipeline works](https://growthvibes.ai/resources/how-i-built-an-seo-content-automation/). This is the skill we run, with our IDs, keys and private details taken out. Anything in angle brackets (`<like this>`) is yours to fill in. It is built to run unattended: it never asks questions, it decides and writes its assumptions down.
## What you need
- **Firecrawl API key** in `.env` (`FIRECRAWL_API_KEY`): `scripts/fetch-serps.mjs` pulls the Google top 10 for every keyword, about 2 credits each. Node 18 or newer.
- Your keyword list with volume and difficulty (a CSV, a list or Ahrefs screenshots).
- A `data/topical-map/` folder in your project: the scripts keep `keywords.csv`, `keywords-final.csv` and `pages.csv` there, and read `config.json` for your categories, e.g. `{"categories": {"seo": "/services/seo", "automation": "/services/automation", "guides": "/"}}` (category to the core page it links up to).
- **Optional:** the Google Sheets connector (we keep the map in a sheet with pivots; `scripts/sheet-io.mjs` syncs it) and [treg](https://treg.to) (DataForSEO keyword overview) for missing volumes.
- Bundled scripts: `fetch-serps.mjs`, `add-keywords.mjs` (incremental placement), `validate.mjs`, `sheet-io.mjs`, `page-context.mjs`, `lib.mjs`.
## Fill in before the first run
- Your categories, core pages, priorities and the Google Sheet id (if you use one), wherever ours appear.
the author finds new keywords over time. This skill adds them to the existing map in one go, with no step-by-step prompting. It is incremental: existing pages, categories, priorities and statuses stay as they are. Background and the method behind the map: the build write-up (https://growthvibes.ai/resources/how-i-built-an-seo-content-automation/).
Run it when the author shares keywords (a list, a CSV, Ahrefs screenshots) or asks to add or map keywords, or to check the map.
## The rules (the author's, final)
- **One group of keywords = one article.** The **page keyword** (the parent) is the keyword with the most monthly searches in its group. The other keywords are children: they are covered as sections of that article, never as separate articles.
- A child shares at least **3 of the Google top 10 results** with the page keyword (US results, from `fetch-serps.mjs`).
- **Categories**: `agents-automation` = AI automation, mainly for marketing (ads agents, marketing agents, sales and outreach agents, n8n, Claude and skills tutorials). `seo-aeo` = SEO, AEO, keyword research and SEO agents. `ai-growth` = umbrella pages that link to the homepage. `vibe-coding` = small adjacent topic. `growth-marketing` is unused. When in doubt between agents-automation and growth-marketing, it is agents-automation.
- **Every page links up** to one core page (ours shown; set yours in `config.json`): `/services/ai-automation-agents`, `/services/seo-aeo`, or `/` (homepage, ai-growth only). Core pages do not link down.
- **Priority**: P1 = first resources to write (winnable, supports a service or the tutorial layer), P2 = service and AI Labs pages, P3 = next resources, P4 = later.
- **Article types**: `tutorial`, `explainer`, `listicle`, `tool_review`, `comparison`, `service_roundup`.
- **Leave `section` (core/adjacent) blank on new pages.** the author has not decided what that column means.
- Copy rules apply to titles: plain, specific, no AI filler, no em dashes.
## Where things live
| What | Where |
|---|---|
| Keywords with volume, KD | `data/topical-map/keywords.csv` |
| Which keyword sits in which page | `data/topical-map/keywords-final.csv` (`page_keyword`, `role`) |
| The plan, one row per page | `data/topical-map/pages.csv` |
| Approved rule breaks, with a reason | `data/topical-map/exceptions.csv` |
| Raw first-pass grouping (history, do not rerun) | `clusters.csv`, `groups.csv`, `cluster.mjs` |
| Scripts | `scripts/`: `add-keywords.mjs`, `validate.mjs`, `sheet-io.mjs`, `fetch-serps.mjs`, `lib.mjs` |
| Run reports | `work/topical-map/last-run.md` and `last-run.json` (git-ignored) |
| Google Sheet "your site topical map" | id `<your Google Sheet id>` |
Sheet tabs (sheetId): Read me 0, **Pages 1**, **Keywords 2**, Parent and child pivot 3, Summary 4, Next up 6.
- Pages columns: A parent_keyword, B child_keywords (formula), C decision, D skip_reason, E category, F section, G central_entity, H contextual_domain, I article_type, J links_up_to, K suggested_title, L suggested_slug, M priority, N status, O total_volume (formula), P notes.
- Keywords columns: A parent_keyword, B keyword, C role, D volume, E kd, F branded, G local, H intent, I child_keywords (formula), J category, K section, L priority, M decision (J to M are lookups into Pages).
- Pivots, filters, dropdowns and formulas already cover Keywords to row 2000 and Pages to row 1000. Past that, extend them.
Before the first Google Sheets call, read the `anthropic-skills:google-workspace` skill and its `references/sheets.md` (value parsing, field masks, numeric sheet IDs).
## The run (do all of it, report at the end)
**0. Pull the author's edits from the sheet.** He edits category, priority, status and decision in the Pages tab, so the sheet can be newer than the CSV. `get_values` on `Pages!A1:P1000`, save the result to a JSON file (use the path the app gives for large results), then:
`node scripts/sheet-io.mjs pull <file.json>`
It copies his edits into `pages.csv` and lists any page that exists on only one side. Resolve those before going on.
**1. Make the input CSV** at `work/topical-map/input.csv`, columns `keyword,volume,kd,branded,local,intent,ahrefs_parent_topic`. From screenshots: read keyword, volume and KD as shown; `branded` = Y for brand or product names; `local` = Y for places or "near me"; `intent` uses Ahrefs letters (I, C, T, N, B, L as shown). Lowercase every keyword. If volumes or KD are missing, look them all up in one call with treg: `treg call dataforseo.x.dataforseo-labs-google-keyword-overview-live --method POST --data '[{"location_code":2840,"language_code":"en","keywords":["kw1","kw2"]}]'` (about $0.013 for 10 keywords, up to 700 a call). Fill only the blanks: these numbers differ from Ahrefs and the KD is on another scale, so never overwrite a number the screenshots show, and list every keyword that got one in the report. If it fails, leave them blank and they are reported. Do not look up volumes for keywords the screenshots already show.
**2. Place the keywords.** Firecrawl costs about 2 credits per new keyword; ask first for more than 300 keywords.
`node scripts/add-keywords.mjs work/topical-map/input.csv`
(`--dry-run` previews without writing data files.) It skips keywords already mapped (updating a changed volume), fetches the Google top 10 for new ones, and then:
- puts a keyword into the existing page whose page keyword it shares 3+ results with (the one it shares most with wins; ties and second overlaps are reported);
- if the new keyword has more volume than that page keyword and shares 3+ with every member, it becomes the page keyword (same slug and status; the change is noted in the page's notes and reported);
- groups the keywords that fit no page into new pages, added to `pages.csv` as `plan_needed`.
Read `work/topical-map/last-run.md`.
**3. Plan the new pages.** For each `plan_needed` row, start an **Opus** subagent (Agent tool, model opus) with the rules above, the new page's keywords and volumes, the page's `near` warnings, and these instructions:
- Fill only the `plan_needed` rows of `pages.csv`: `decision` (`build_page`, or `skip` with a `skip_reason` for job searches, wrong location, wrong industry and the like), `category`, `central_entity`, `contextual_domain`, `article_type`, `links_up_to`, `suggested_title`, a unique `suggested_slug` (lowercase, hyphens; check it against `pages.csv` and the published articles in Sanity), `priority`, `status` (`new` unless the topic is already published, drafted or in the Notion Content Calendar), and one short `notes` sentence. Leave `section` blank.
- Check that the page does not overlap one that exists (the `near` warnings): if it should be part of that page, say so instead of planning it.
- Prompt-style keywords with no KD stay out of P1.
Simple steps (reading screenshots, running scripts, the sheet sync) do not need Opus.
**4. Validate.** `node scripts/validate.mjs`. It must end with `OK: no errors`. Fix real problems. A rule break that the author accepts goes in `exceptions.csv` with a reason; never add one on your own to make the check pass, and list every new one in the report. Warnings about pages that overlap are shown to the author, not hidden.
**5. Update the sheet** (rows and formulas, never rebuild the tabs).
- `get_values` for `Keywords!A1:H2000` and `Pages!A1:P1000`, save both to files, then `node scripts/sheet-io.mjs delta <keywords.json> <pages.json>`. It writes `work/topical-map/sheet-delta.json`.
- `keywords.updates`: `update_values` each row's A:H.
- `keywords.append`: `update_values` at `appendRange`, then copy the formulas for the new rows from `Keywords!I2:M2` with `update_spreadsheet` `copyPaste` (sheetId 2, `PASTE_FORMULA`).
- `pages.renames`: `update_values` column A of that row.
- `pages.statusUpdates`: `update_values` column N (status) of that row. Your writing pipeline can move a page to drafted or published in `pages.csv` when it finishes an article; this carries it to the sheet. Status only moves forward (new, calendar_idea, drafted, published), in both directions of the sync.
- `pages.append`: for each new page `update_values` A, C:N and P at `appendStartRow`, then copy B and O from row 2 with `copyPaste` (sheetId 1, `PASTE_FORMULA`).
- Check: the "Parent and child pivot" Grand Total keywords equals the rows in `keywords.csv`, and the Summary pivots show the new pages.
- If Keywords passes row 1,900 or Pages passes 900, extend the pivot sources, filters, dropdowns and the `Next up` formula first.
**6. Commit the data.** `git add data/topical-map` and commit "Topical map: add N keywords" (with the attribution line the session gives), push to `main`. These are data files, not site changes, so they do not need the author's design review.
**7. Report, in plain English and short:** how many keywords went into existing pages (name the pages), the new pages with category and priority, and a "needs your call" list (ties, higher-volume keywords that could not take over a page, exceptions added, keywords with no volume, pages that overlap another). Say what it cost in Firecrawl credits.
## Not automatic (do when the author asks)
- **Coverage review.** The map is built from keyword demand. Koray's method also maps the topic itself: what a reader of AI automation or AEO needs next, even with no search volume. Start an Opus subagent per core area to list missing subtopics against `pages.csv`, then offer them as ideas. Look up their volume only after the author agrees.
- **Re-grouping everything.** `cluster.mjs` rebuilds from scratch and would undo the merges and the planned pages. Do not run it on the real data.
The plan behind every article in my content automation. Two keywords belong on the same page only if Google shows mostly the same results for both. This skill reads that from the search results, groups your keywords, plans the pages and keeps the map growing as you find more keywords.
What it does
Fetches the Google top 10 for every keyword with the bundled script
Groups keywords that share 3 or more results; the highest-volume one becomes the page keyword
Places new keywords into existing pages, or plans new pages for the leftovers
Gives every page a category, an article type, a slug and the core page it links up to
Validates the map: no duplicate pages, no page without a link up
Syncs a Google Sheet without overwriting your edits
What you need
Claude Code and Node 18 or newer
FIRECRAWL_API_KEY in .env (about 2 credits per keyword)
Your keyword list with volume and difficulty (CSV, list or screenshots)
A data/topical-map/config.json with your categories and the core page each links up to
Optional: the Google Sheets connector and a keyword-volume source
How it works
Pull your edits. If you keep the map in a sheet, your changes come in first.
Make the input. One CSV row per new keyword.
Place.scripts/add-keywords.mjs fetches results and groups by overlap.
Plan. New pages get a category, type, title, slug and priority.
Validate.scripts/validate.mjs must end with no errors.
Sync. Rows and formulas to the sheet, never a rebuild.
Try asking
“Add these 40 keywords to the topical map.”
“Here are Ahrefs screenshots, map the keywords.”
Install it
Download the ZIP above.
Claude Code: unzip it into .claude/skills/ in your project (or ~/.claude/skills/ for all projects). Keep the folder name; the scripts folder goes with it.
Add the keys from “What you need” to a .env file in your project, and connect the MCP servers it uses.
Claude.ai: upload the ZIP under Settings, Capabilities, Skills. The instructions work there too; the scripts need Claude Code.
Download the ZIP and unzip it into .claude/skills/ inside your project (or ~/.claude/skills/ for every project). Keep the folder name. The scripts folder inside it travels with the skill.
Can I use it in Claude.ai?
You can upload the ZIP under Settings, Capabilities, Skills, but the bundled scripts need a terminal, so Claude Code is the better home. The instructions still work in Claude.ai with the same connectors.
Is anything private left in it?
No. Our IDs, keys, database links and private details were removed. Anything in angle brackets is a placeholder for your own setup.