SEO Keyword Research & Content Suggestions (React/Next.js)

Produces a markdown SEO report for the current React/Next.js project: ask where content lives → business summary → competitors → keyword opportunities → content suggestions with route-aware placement.

Hard constraint: no paid SEO API/tool is connected. There is no Ahrefs/SEMrush/Ubersuggest/DataForSEO data source. Every volume and difficulty (KD) figure in the output is an estimate derived from web search signals and reasoning, not a real metric. Never present estimates as if they came from a tool. Every report must carry the disclaimer in Step 5's template, and every keyword table must use a "Confidence" column, not a fake precise number.

Step 0 — Ask where the content actually lives (mandatory, do this first)

Do not read files or search the web yet. In a React/Next.js project the real business content can live in wildly different places depending on the setup, and guessing wrong wastes a pass. Ask the user directly, before doing anything else:

"Where does this site's actual content live? For example:

• Hardcoded in components/pages (e.g. app/, pages/, components/)
• MDX/Markdown files in a content directory (e.g. content/, posts/)
• A headless CMS (Sanity, Contentful, Strapi, Payload, etc.) — and if so, can I query it, or should I read from exported/cached data in the repo?
• A data/ folder of JSON/TS objects (services, products, locations, etc.)
• Something else?

Also — is there an existing README.md or project doc that already describes the business (services, products, location, audience)?"

Wait for the answer. Only proceed to Step 1 once you know where to look. If the user says "just figure it out," fall back to scanning in this order and say what you found before continuing: README.md → content//posts//blog/ (MDX/MD) → app/ or pages/ route files and their metadata exports → data//lib/ constants → CMS client/config files (e.g. sanity.config.ts, contentful.ts) — but flag that you're guessing and confirm with the user before moving to Step 2.

Step 1 — Understand the project

Now read whatever the user pointed you to (or what you found in the fallback scan). Depending on the setup, that might mean:

• MDX/Markdown files: read the frontmatter and body of posts/pages for real topics already covered and the tone/voice used
• App/Pages Router files: check route structure (app/**/page.tsx, pages/**/*.tsx) for what pages already exist, and read generateMetadata/next-seo/<Head> config for current titles, descriptions, and target keywords already in use
• Headless CMS: if you have API/MCP access, query it; otherwise ask the user for a content export, or a few representative pages' worth of pasted content
• data//lib/ constants: read service/product/location arrays or objects directly — these are often the cleanest source of truth
• package.json / README.md: stack, project name, and often a description of what the business does

Extract and hold onto:

• What the business/site actually is (industry, one-liner)
• Concrete services or products offered (the actual names used on-site, not paraphrases)
• Location/service area, if it's a local business — this changes keyword strategy a lot (local modifiers matter more than volume)
• Target audience (residents, businesses, a specific demographic, etc.)
• Existing blog/content already published (route paths or MDX slugs), so you don't suggest what's already covered

If what you're given is still too thin (e.g. a bare scaffold with no real content anywhere), say so explicitly and ask the user for a one-paragraph description rather than inventing a business.

Step 2 — Find real competitors

Use web_search (and web_fetch on promising results) to find actual competitors:

• Search for the core services/products + location (if local) or + industry (if not)
• Search for the site's own name/domain + "vs" or "alternatives" if it's an established brand
• Prefer competitors that are genuinely comparable in size/scope — skip huge national players if this is a small local business, they're not real competitors for ranking purposes

For each of 3–6 competitors found, note:

• Domain and a one-line description of what they offer
• Their apparent content strategy: do they have a blog? What topics? (fetch their blog/sitemap index page if reachable)
• Anything they rank for or emphasize that the project's own site doesn't cover yet — this is the gap you're hunting for

Step 3 — Build a keyword candidate list

Generate seed keywords from three sources, not just one:

1. The project's own services/products (from Step 1) — direct "service + modifier" terms
2. Competitor content gaps (from Step 2) — topics competitors cover that this project doesn't
3. Question-based / long-tail terms — search Google-style queries and note "People also ask" style questions, forum threads (Reddit, Quora) discussing the topic, and autocomplete-style suggestions that surface in search results

For each candidate keyword, do a real web_search for that exact phrase and read the SERP signals, don't just guess from the term alone.

Step 4 — Estimate volume & difficulty from SERP signals

Since there's no keyword tool, infer volume and difficulty from what the search results actually show:

Volume signals (higher → lower):

• Term appears as an autocomplete suggestion or "People also ask" entry → decent volume
• Multiple recent, well-produced articles target the exact phrase → decent volume
• Only old, thin, or zero dedicated content exists on this exact phrase → likely low volume (flag as long-tail, not "high volume")
• Very generic single/two-word terms are almost always high volume but also high difficulty — call this out

Difficulty (KD) signals (lower → easier):

• Top 10 results are mostly forums, local business pages, small blogs, or "listicle" aggregators, not major brands/publishers → likely low difficulty
• Top 10 dominated by major national brands, .gov/.edu, or big publishers → likely high difficulty
• The exact phrase has no dedicated page in the top 10 (only broader pages loosely matching) → content gap, often easier to win
• Local/service-area modifiers ("in [city]", "near me", "[neighborhood]") almost always lower difficulty than the bare term — always generate local variants for local businesses

Label every keyword's volume and difficulty as Low / Medium / High, never a fabricated number, and add a one-line "why" citing what you saw in the SERP.

Step 5 — Write the report

Save as markdown to the project (e.g. seo/keyword-research-<YYYY-MM-DD>.md or docs/seo/... — check for an existing docs/ or seo/ folder first, otherwise ask the user where to put it). Structure:

# SEO Keyword Research — [Project Name]
_Generated [date]. Estimates are based on web search signals, not a paid SEO tool — treat Volume/KD as directional, not exact._

## 1. Business Summary
[2-4 sentences: what this site/business does, services/products, audience, location if local]

## 2. Competitors
| Competitor | What they offer | Content gap they expose |
|---|---|---|
| ... | ... | ... |

## 3. Keyword Opportunities
| Keyword | Intent | Est. Volume | Est. Difficulty | Why (SERP signal) |
|---|---|---|---|---|
| ... | informational/commercial/local | Low/Med/High | Low/Med/High | ... |

Focus the table on the **High-volume + Low/Medium-difficulty** rows — that's the target set. Include a handful of Medium-volume/Low-difficulty long-tail ones too; those are often the fastest wins.

## 4. Content Suggestions
For each priority keyword or cluster:
- **Type:** Blog post / Service page / Landing page
- **Working title**
- **Target keyword** + 2-3 secondary keywords to naturally include
- **Angle:** why this angle, what makes it different from what competitors have
- **Suggested route/file:** match the project's actual convention found in Step 1 — e.g. `app/blog/[slug]/page.tsx` → `app/blog/service-in-city/page.tsx`, or a new MDX file in `content/blog/service-in-city.mdx`, or a new entry in the CMS
- **Metadata:** suggested `title` and `description` for `generateMetadata`/`next-seo`/frontmatter, sized correctly (title ~50-60 chars, description ~150-160 chars)

## 5. Notes / Next Steps
[Anything that needs the user's input — e.g. "no volume data available, confirm with Search Console/GSC data if you have it" or gaps in project context]

Notes for running this well

• Never skip Step 0. Don't scan the filesystem or search the web before the user has told you (or you've confirmed a fallback guess with them) where the content actually lives — guessing wrong in a React/Next.js project (CMS vs. MDX vs. hardcoded) wastes the whole pass.
• Always ground Step 1 in the actual project content before searching anything — generic SEO advice without project context is not the point of this skill.
• Be honest in the report when confidence is low (thin project context, sparse SERP signal, etc.) rather than padding it out.
• If the user has Google Search Console, Google Analytics, or an SEO tool connected via MCP, prefer that real data over estimation for any keyword it covers — check available tools before starting Step 4.
• Keep the keyword table to a focused, actionable set (roughly 15-30 keywords) rather than an exhaustive dump.