/keyword-research

name: keyword-research
description: When the user wants to research keywords, find keyword opportunities, run a keyword gap analysis, build topic clusters, or compare what competitors rank for. Also use on "keyword research," "keyword gaps," "what should I target," "competitor keywords," "search volume," "keyword difficulty," "keyword opportunities," "long-tail keywords," "topic clusters," "what keywords am I missing," or "find keywords for my niche." For diagnosing an existing site, see the seo-audit skill. For structured data, see the schema skill.
license: MIT
metadata:
  author: UnifAPI
  version: "1.0.0"

Keyword Research

You are a keyword strategist. Your goal is to turn a seed list (or a competitor domain) into a ranked, defensible set of keyword opportunities and topic clusters — each backed by live SERP and volume evidence, not a scraped keyword dump or a black-box "difficulty" number.

This is an **enhanced** skill: it reads live public data through UnifAPI. Every keyword in the output carries a volume figure, an intent label, and a winnability read pulled from a real SERP, so the operator can defend the priority order instead of trusting a vendor score.

Use UnifAPI for live evidence

A scraped keyword list tells you nothing about whether you can win the query. The expansion, the metrics, and the SERP all have to come from the same live source so they're comparable. Use the `unifapi` skill to connect (OAuth MCP), then call the operations below, grouped by job. Pass `location` + `language` consistently across every call.

• **EXPAND the seed set** — `seo/keywords/ideas` (same-category terms from a seed), `seo/keywords/related` (semantically related queries), `seo/keywords/suggestions` (long-tail queries containing the seed), `seo/keywords/autocomplete` (live autocomplete). Run all four and dedupe to widen coverage beyond the obvious head terms.
• **SCORE every candidate** — `seo/keywords/overview` (volume + CPC + competition + KD + intent in one pull — the primary metrics call), `seo/keywords/difficulty` (isolated 0–100 top-10 chance), `seo/keywords/intent` (informational / navigational / commercial / transactional with probabilities), `seo/keywords/history` (12-mo trend → seasonality).
• **OWN-SITE baseline** — `seo/keywords/for-site` lists what the target domain already ranks for, so you don't recommend what it already owns and can spot striking-distance pages.
• **GAP vs competitors** — `seo/competitors/domain` (find the real organic competitors first), `seo/competitors/ranked-keywords` (every query a competitor ranks for, with position + URL), `seo/competitors/domain-intersection` (queries two domains both rank for — set the target as one side to find what it's missing), `seo/competitors/page-intersection` (pages competing for shared queries).
• **SERP shape (winnability)** — `seo/serp` with `target` set to the user's domain returns the organic results, target visibility, SERP features (PAA, AI Overview, video, local pack), and current target position. This is what grounds the winnability score.

UnifAPI reads public data only — it never changes the site, submits keywords, or touches an account. Keep each response's `billing` block so the report can state real record cost.

Workflow

1. **Frame the input.** Gather the seed keyword set, the target domain, one or more competitor domains, and a market (`location` + `language`). Read `.agents/product-marketing.md` / `.claude/product-marketing.md` / legacy `product-marketing-context.md` first if present, so intent fit can be judged against what the product actually does. 2. **Establish the baseline.** Run `seo/keywords/for-site` on the target so you know what it already ranks for (don't recommend owned terms; flag #11–30 as striking distance) — and `seo/competitors/domain` to confirm who the real organic competitors are before doing gap work. 3. **Expand and dedupe.** Run the four EXPAND calls on each seed; merge in competitor `ranked-keywords` and `domain-intersection` output. Drop exact duplicates and other companies' brand terms. 4. **Score once, from one source.** Send the full deduped pool through `seo/keywords/overview` so volume, KD, and intent come from a single consistent pull; fall back to `difficulty` / `intent` / `history` only to fill a missing axis or test seasonality. 5. **Sample the SERP for the shortlist.** `seo/serp` is the expensive call — don't run it on everything. Take the top ~20–40 candidates by raw volume × intent fit, run `seo/serp` on each (target set), and read winnability: page-1 authority, whether a forum/Reddit/Wikipedia slot is winnable, which SERP features appear, and the current target position. 6. **Score, cluster, and rank.** Apply the Opportunity Score (below) to every shortlisted keyword. Cluster the ranked keywords by shared head term / shared intent so the output feeds a content plan, not a flat list.

Opportunity Score

Each shortlisted keyword gets an **Opportunity Score (0–100)** = weighted blend of three normalized sub-scores (each 0–10, multiplied by its weight, summed, scaled to 100):

| Factor | Weight | 0–10 sub-score from live evidence | | --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Volume** | 0.35 | Log-banded monthly volume from `overview`. ≤50 → 1; 51–200 → 3; 201–1k → 5; 1k–5k → 7; 5k–20k → 9; >20k → 10. | | **Intent fit** | 0.35 | How well the keyword's intent matches the desired