openseo-keyword-research
Discover keyword opportunities with MEASURED volume, keyword difficulty, CPC, and intent from OpenSEO, then write them into brand/keyword-plan.md. Use this skill whenever someone asks for keyword diff
SKILL.mdskills/openseo-keyword-research/SKILL.md
GitHubOpenSEO Keyword Research
Turn seed topics into a prioritized, MEASURED keyword opportunity set and land it in brand/keyword-plan.md. mktg's keyword-research is the playbook (methodology); this skill is the measured-data engine behind it when OpenSEO is configured.
On Activation
- Readiness check:
mktg seo status --json --fields readiness,catalog.endpointError,project— if readiness isnot_configured, stop spending: state the gap and hand off to Exa-backedkeyword-researchwith metrics markedunknown. For a ready state, verify live access with the freewhoamiMCP tool before paid calls. - Project binding: read
.seo/openseo.jsonforprojectId. Missing → runopenseo-project-setupfirst (or ask the user for the project id). - Brand grounding: read
brand/positioning.md+ existingbrand/keyword-plan.md(tolerate templates). Business-fit beats volume-fit — the positioning file is the filter.
OpenSEO MCP Tools
get_search_console_performance: when GSC is connected, START here. HighrowLimit, filter average position ~5–20 client-side (the API sorts by clicks, not position). These striking-distance terms are the fastest wins — and zero extra credit cost.get_keyword_metrics: hydrate up to 700 keywords per call with volume, KD, intent, CPC, trends. Use on striking-distance terms and every candidate set.research_keywords: discovery from 1–5 seeds per call; prefer ~150 results unless exhaustive research was requested.get_ranked_keywords: when the brief includes a domain/page — exact ranking rows (near-misses, competitor-owned terms).get_serp_results: inspect SERPs for top candidates when intent is ambiguous. Keep batches small (≤10 queries).list_saved_keywords: avoid re-researching what's already saved.save_keywords: a free shared-state mutation. Use only after confirmation, with concise tags (topic:<t>,intent:<i>,page:<slug>).
Workflow
- Normalize seeds into 2–5 distinct research angles filtered by positioning.
- GSC connected? Pull striking-distance terms first and hydrate with
get_keyword_metrics. Work that list before broad discovery. research_keywordsper angle;get_keyword_metricsto hydrate;get_ranked_keywordsif a domain is in the brief.- Remove irrelevant, duplicate, branded-only, and off-intent terms.
- Prioritize by practical opportunity: business fit → clear intent → reasonable KD → volume/CPC signal → winnable SERP.
get_serp_resultsfor high-potential or ambiguous terms when SERP intent would change the call.- Write the shortlist into
brand/keyword-plan.md(preserve its required sections perbrand/SCHEMA.md; confirm before overwriting populated sections). - Present: best opportunity theme, top keywords now, keywords to save, SERP caveats. Then next actions:
openseo-keyword-clustering,seo-content, or save.
Cost Discipline
- State estimated call counts before bulk pulls (>200 keywords) and get confirmation.
- Small exploratory batches are fine without asking.
- GSC-first ordering exists precisely to avoid spending credits on data the user already owns.
Anti-Patterns
- Inventing metrics when OpenSEO returns nothing — because a hallucinated KD of "about 35" silently becomes the foundation of a content plan. If OpenSEO doesn't return a value, write
unknown. - Volume-first prioritization — because a 10k-volume term that doesn't match the product converts nobody and burns months. Positioning filters the list before metrics rank it.
save_keywordswithout explicit confirmation — saves do not burn provider credit, but they mutate shared OpenSEO account state and broad tags can disrupt other workflows. Ask, state the count and tag change, then save.- Skipping the GSC-first pass when GSC is connected — because striking-distance terms (positions 5–20) are provably the cheapest wins in SEO and they're free to read. Discovery research before first-party data is wasted spend.
- Overwriting a populated
keyword-plan.mdwithout confirmation — because that file is brand memory other skills build on (seo-content,seo-machine). Merge; confirm destructive rewrites.
Close the loop
After writing files, log completion so mktg plan / mktg status count the work (bare mktg run only logs loaded):
mktg run openseo-keyword-research --complete --writes <paths written> --result success --json
Progressive Enhancement
| Level | Behavior |
|---|---|
| L0 (no OpenSEO) | Hand off to Exa-backed keyword-research; metrics unknown |
L1 (OPENSEO_API_KEY) |
Metrics via available calls; MCP steps deferred |
| L2 (MCP connected) | Full workflow incl. SERP validation |
| L3 (GSC connected) | Striking-distance-first ordering; highest-signal path |
Adapted from every-app/open-seo .agents/skills/keyword-research (MIT). Workflow and tool guidance upstream; mktg brand-memory writes, positioning filter, and cost discipline added here.