keyword-research
π―SkillHelps you find search words worth targeting for your website using OpenSEO data. It checks how often people search them and how hard they are to rank for, saves the good ones, and delivers a report.
Installation
npx skills add every-app/open-seo --skill keyword-researchRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/keyword-researchInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/keyword-research/ - All projects
~/.claude/skills/keyword-research/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βDiscover keyword opportunities, evaluate metrics and SERPs, and save/tag promising terms.
OpenSEO Keyword Research
Goal
Turn seed topics into a prioritized keyword opportunity set using OpenSEO MCP data. The output should help the user decide what to target, what to save, and what to research next.
Required inputs
projectId- One or more seed topics, products, pages, competitors, or audience problems
- Optional market/location/language
If projectId is missing, use list_projects first. If the target market/location/language is unclear and would materially affect keyword metrics, ask the user; otherwise use the MCP tool defaults.
Project context
The project-context tools are free and shared with the app and other agents.
- Call
get_project_contextfirst and ground the research in it β the business, the goal, the markets, and the competitors and key pages already saved. - This skill needs
business_overviewandcurrent_goal. If either is empty, run a minimal inline setup: ask the user, or infer from the site and confirm, just enough to fill them, write them back withupdate_project_context, then continue the research. Never front-load the full interview; suggestseo-project-setupat the end for the rest. - Before spending credits, check the research log. If the same research ran within the last 30 days, reuse that result and say so instead of re-buying it.
- On finish, write back what is durable β a sharpened
business_overvieworcurrent_goal, competitors that kept appearing in the SERPs viaaddCompetitors, pages the keywords should land on viaaddKeyPagesβ and append a research log entry:{ appendResearchLog: { summary: "Keyword research: <seeds/market>. Verdict: <conclusion>" } }.
Deliver as a report
Deliver through the seo-report skill, saving with skill: "keyword-research". If that skill is not available, say so and stop before writing HTML.
OpenSEO MCP tools
research_keywords: primary discovery tool. Use 1-5 seeds per call and prefer 150 results unless the user asks for exhaustive research. For demand in one city, county, or region, callsearch_serp_locationsand pass the returnedlocationNameon the seed: volume, CPC, and competition become local; keyword ideas, KD, and intent stay national.get_keyword_metrics: hydrate up to 700 known keywords with volume, keyword difficulty (KD), search intent, CPC, and monthly trends in one call. Use it to score candidate or known terms β including the Search Console striking-distance queries from step 1.get_ranked_keywords: pull exact ranking keyword rows when a target domain or page is part of the research brief.get_search_console_performance: when Search Console is connected, start from the project's real first-party demand β queries already earning impressions and near-ranking ("striking distance") terms. PassminPosition: 5, maxPosition: 20, minImpressions: 50so the server filters the striking-distance rows for you (Google sorts by clicks and can't filter by position itself). Then hydrate those striking-distance queries withget_keyword_metricsto attach difficulty and intent.get_serp_results: inspect SERPs for the top candidate terms, especially when intent is ambiguous. Pass the samelocationNamefor the SERP in one city, county, or region.search_local_businesses,get_local_serp_results, andget_google_business_questions: use for local SEO topics when a business/location radius matters.list_saved_keywords: avoid duplicating already-saved work or use existing tags as context.save_keywords: save selected keywords only after explicit user confirmation.
Workflow
- Normalize seeds into a small set of distinct research angles. If Search Console is connected for the project, first pull
get_search_console_performancewithminPosition: 5, maxPosition: 20, minImpressions: 50(default lookback), and hydrate those queries withget_keyword_metricsto attach KD and intent. That ranked, hydrated list is your fastest opportunity set β work it before broad discovery. - If the request is local SEO, identify the business, location/coordinates or service area, and local categories. Research local volume for that city or county with
research_keywordsandlocationName. Usesearch_local_businessesandget_local_serp_resultsfor the most important location/keyword set instead of relying only on national keyword/SERP data. - Call
research_keywordsfor exploratory seeds. Use bulk calls when possible. - Use
get_keyword_metricsto hydrate a fixed keyword list β or the striking-distance queries from step 1 β with volume, KD, and intent before prioritizing. - Use
get_ranked_keywordswhen the user provides a domain/page and wants opportunities based on current rankings, near-misses, or competitor-owned terms. - Remove irrelevant, duplicate, branded-only, and off-intent terms.
- Prioritize by practical opportunity, not volume alone:
- Strong match to the user's product/page/topic
- Clear search intent
- Reasonable difficulty
- Useful volume/CPC signal
- SERP where the user can plausibly compete
- For local SEO, local-pack/Maps visibility and proximity fit
- Use
get_serp_resultsfor high-potential or ambiguous keywords when SERP intent would change the recommendation; keep the default check small. - Present a shortlist and a longer opportunity table.
- Ask before saving keywords. When saving, suggest concise tags such as
topic:<topic>,intent:<intent>, orpage:<slug>.
Output format
h1: the site or topic.
If a report template applies (see seo-report), its sections and tone replace this list.
Sections in this order:
- The opportunity β one or two opening sentences naming the best theme and why the site can win it now.
- Target these now β a table of keyword, intent, volume, KD, CPC, and the page to make. Add a bar chart comparing the volumes of the shortlist.
- Why these β one finding per keyword that needs justifying: the SERP or metric evidence, then the page to build.
- The longer opportunity list β a second table, same columns.
- Risks and caveats β notes: SERP intent that would change the recommendation, missing metrics written as
unknown, close-variant volumes that are one bucket rather than several. - What to do next β an ordered list, including whether to run keyword clustering, write a content brief, or save the chosen keywords.
- How this report was made β opens with the skill link line from
seo-report, pointing athttps://openseo.so/docs/skills/keyword-research("OpenSEO Keyword Research skill"), then which tools returned what.
Guardrails
- Do not invent metrics. If OpenSEO does not return a value, write
unknown. - Do not call
save_keywordswithout explicit confirmation. - Prefer business-fit and intent-fit over chasing the largest volume term.
More from this repository10
OpenSEO is an open-source tool for improving how your website shows up in search results, as a cheaper option to Semrush or Ahrefs. Your AI agent can use its data to do keyword research, track rankings and check your site.
Studies one competitor's website to see how it gets visitors from search engines. It looks at the search words it ranks for, its topics and links from other sites, then shows gaps you can use, in an OpenSEO report.
Groups search words by what people are looking for and decides which page on your site should target each group. It uses OpenSEO tools and delivers the plan as a report.
A friendly coach for OpenSEO that explains how to get your site found in search engines in plain words. It reads your project details, suggests one clear next step, and points you to a fuller report when you want more depth.
Finds websites, pages and authors that might link to your page or product, then looks up public ways to contact them. It drafts outreach messages and saves the findings as a report in OpenSEO.
Shows who wins the most search traffic in your market, what content works for them, and where openings remain for you. It uses OpenSEO data and delivers the result as a saved report.
Interviews you once about your website's search goals, competitors, key pages and writing preferences, and saves the answers in your OpenSEO project. Other OpenSEO skills then reuse this information in later sessions.
Gets a code branch ready for the project maintainer's final review. It checks for security problems, needless complexity, and ways to get paid features for free, fixes real issues, runs the checks, and opens or updates the pull request without merging it.
Prepares a new release of the OpenSEO project from start to finish. It raises the version number, writes short release notes from the changes since the last release, double-checks them, and opens a pull request.
Skill