research-keywords
Finds high-value SEO and GEO keywords using web search, AI analysis, and optionally paid tools like Ahrefs or Semrush. Produces a validated keywords.csv file with a fixed schema for downstream pipeline consumption.
Install
npx skills add https://github.com/tonydzi/second-brain-starter-kit/tree/master/skills/research-keywords
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tonydzi-second-brain-starter-kit@llmmart
git clone https://github.com/tonydzi/second-brain-starter-kit.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tonydzi/second-brain-starter-kit collection as a plugin from our marketplace. Git is the plain clone.
README
Research SEO/GEO Keywords
An agent skill that researches and delivers a prioritized keyword list for SEO and GEO — using web search and AI analysis instead of paid tools like Ahrefs or Semrush.
No Ahrefs. No Semrush required.
Uses web search, website crawling, and LLM analysis to find, cluster, and prioritize keywords — including a GEO dimension that traditional tools don't offer. Optionally supercharge research with SERP API scripts for real autocomplete, PAA, and SERP feature data.
Install
Clone the repo, then symlink or copy research-keywords/ into either ~/.codex/skills/ or ~/.claude/skills/. See the root README for installation examples.
Usage
/research-keywords
Or:
"Research keywords for my product" "Find SEO and GEO keywords for [brand/URL]" "Run keyword research for my [product category]"
The skill is interactive — it asks you questions, researches, and delivers a structured keyword file.
The 4-Phase Process
Phase 1: Brand Intelligence
The skill asks about your product, audience, and competitors. It visits your website and competitor sites to extract language, positioning, and content gaps.
Phase 2: Keyword Discovery
Researches keywords across 6 methods — no paid tools needed:
| Method | What It Finds |
|---|---|
| Google Autocomplete Mining | Real search suggestions and long-tail variants |
| People Also Ask (PAA) | Question-format keywords AI engines love to answer |
| Reddit & Community Mining | Real user language, pain points, and slang |
| Competitor Content Analysis | Topics competitors cover that you don't |
| Question & Problem Keywords | Problem-aware searches that lead to your product |
| AI Citation Keywords (GEO) | Queries where AI generates answers and cites sources |
Phase 3: Keyword Analysis & Clustering
Groups keywords into topic clusters, scores each on 3 dimensions:
- Relevance to your product (1-5)
- GEO Opportunity — will AI answer this and cite sources? (1-5)
- Business Value — how close to conversion? (1-5)
Flags quick wins: existing pages to optimize, weak competitor content, AI citation gaps.
Phase 4: Deliverable
Outputs a structured Markdown file with:
- Prioritized topic clusters with pillar + supporting keywords
- GEO-specific keyword table (highest AI citation potential)
- Quick wins and competitor gaps
- Full raw keyword list for reference
- Content recommendations per cluster
What Makes This Different
| Traditional Keyword Research | This Skill |
|---|---|
| Requires Ahrefs/Semrush ($99-449/mo) | Free — uses web search |
| Focuses on search volume + difficulty | Adds GEO opportunity scoring |
| Outputs a spreadsheet of keywords | Outputs clustered, actionable content plan |
| Ignores AI citation potential | GEO is a first-class dimension |
| Marketer language | Real user language from Reddit/communities |
Works With Other Skills
The keyword deliverable feeds directly into:
- write-seo-geo-content — write pages for top keyword and prompt clusters
- geo-content-research — build full AI-ready content for high-GEO keywords
- create-geo-charts — create data visualizations for data-driven keywords
SERP Scripts (Optional Power Tools)
The scripts/ directory contains Node.js tools that pull real Google data to supercharge keyword research. These are optional — the skill works without them using Claude's web search, but they provide higher-volume, more precise data.
keyword-explorer.mjs — Keyword Discovery
Pulls real Google autocomplete suggestions, People Also Ask questions, related searches, and detects SERP features (AI Overviews, Featured Snippets).
# Free mode — no API key, autocomplete only
node scripts/keyword-explorer.mjs --seeds "physical AI, DePAI" --free
# Full mode with SerpAPI (free tier: 100 searches/month at serpapi.com)
SERPAPI_KEY=xxx node scripts/keyword-explorer.mjs \
--seeds "physical AI, DePAI, decentralized robotics" \
--depth deep \
--out keywords.json
# Quick scan for a single seed
node scripts/keyword-explorer.mjs -s "machine economy" --free -d quick
Options:
| Flag | Description | Default |
|---|---|---|
--seeds, -s |
Comma-separated seed keywords (required) | — |
--free |
Free mode: Google suggestions, no API key | auto if no key |
--depth, -d |
quick / normal / deep |
normal |
--out, -o |
Output JSON file path | auto-generated |
--gl |
Country code | us |
--hl |
Language code | en |
What it outputs:
- All discovered keywords with source tags (autocomplete, PAA, related_search)
- People Also Ask questions with snippets and sources
- SERP feature detection per query (AI Overview, Featured Snippet, etc.)
- Queries where AI Overviews appear (= high GEO opportunity)
serp-analyzer.mjs — SERP Competition Analysis
Takes a keyword list and checks who currently ranks, what SERP features appear, and where content gaps exist.
# Analyze keywords from explorer output
SERPAPI_KEY=xxx node scripts/serp-analyzer.mjs \
--input keywords.json \
--top 20 \
--track "axisrobotics.ai,[человек].com"
# Analyze specific keywords
SERPAPI_KEY=xxx node scripts/serp-analyzer.mjs \
--keywords "what is DePAI, physical AI companies, best AI robotics crypto" \
--track "axisrobotics.ai"
Options:
| Flag | Description | Default |
|---|---|---|
--input, -i |
Path to keyword-explorer JSON output | — |
--keywords, -k |
Comma-separated keywords to analyze | — |
--top, -t |
How many keywords from input file | 10 |
--track |
Comma-separated domains to track | — |
--out, -o |
Output JSON file path | auto-generated |
What it outputs:
- Difficulty estimate per keyword (easy / medium / hard)
- SERP features present (AI Overview, Featured Snippet, PAA, Knowledge Graph, etc.)
- Which sources AI Overviews currently cite
- Tracked domain presence/absence (find your content gaps)
- Most frequent ranking domains (identify real competitors)
- All PAA questions (content ideas)
Recommended Workflow
1. Run keyword-explorer with your seed keywords
→ Get raw keyword list + PAA questions
2. Feed output into serp-analyzer for top priority keywords
→ Get competition data + SERP feature opportunities
3. Run the /research-keywords skill with both outputs
→ Get clustered, scored, actionable keyword plan
Setup
# No dependencies needed — pure Node.js (v18+), zero npm install
# Just need a SerpAPI key for full features (free at serpapi.com)
export SERPAPI_KEY=your_key_here
Example Output
## Priority Keyword Clusters
### Cluster 1: Best AI Writing Tools — Priority: 14/15
Pillar Keyword: best AI writing tools 2026
Intent: Commercial Investigation
GEO Opportunity: 5/5 — AI Overviews appear, comparison format
Business Value: 5/5 — direct purchase intent
Relevance: 4/5
| Keyword | Intent | GEO Opp | Notes |
|---|---|---|---|
| best AI writing tools 2026 | Commercial | High | Pillar |
| AI writing tool comparison | Commercial | High | Comparison table content |
| is [человек] AI worth it | Trust | High | PAA — address in FAQ |
| AI content writer for blogs | Commercial | Medium | Use-case variant |
Skill manifest
Research SEO/GEO Keywords
You are an expert keyword researcher who finds high-value keywords for both traditional SEO and Generative Engine Optimization (GEO). You use web search and AI analysis — and optionally integrate paid tool data (Ahrefs, Semrush) when the user has it.
Your job: take a brand's product, website, and competitive context, then research and deliver a prioritized keyword list as a strict CSV artifact ready for the content pipeline.
Output contract: Your final response text IS the deliverable. It MUST be raw CSV matching
keywords.csv.schema.mdexactly. No prose, no code fences, no explanation around the CSV. The harness captures your final output verbatim, validates it against the schema, and fails the artifact if the shape is wrong. See Phase 5 for the exact format.
Critical rule: SEO target keywords must be 1-3 words. Longer phrases (4+ words) go in the Blog Topics section. Keywords longer than 3 words almost never have search volume in tools like Ahrefs — they waste space on the list and won't rank.
How This Skill Works
You will walk through 5 phases:
- Brand Intelligence — Understand the product, audience, and positioning
- Keyword Discovery — Cast a wide net using multiple research methods
- Validation & Pruning — Kill dead keywords, integrate paid tool data if available
- Analysis & Clustering — Group, evaluate, and prioritize
- Deliverable — Output the final keyword list as a structured file
At each phase, you will:
- Ask the user specific questions (Phases 1, 3)
- Do research using web search (Phases 2-4)
- Present findings and get confirmation
- Then move to the next phase
Phase 1: Brand Intelligence
Start here every time. Ask the user for:
Required
- Product/brand name and website URL
- What it does — one-sentence description
- Target customer — who buys this and what problem it solves
- Top 2-3 competitors — brands or products users compare against
Optional (ask, but proceed without)
- Existing keywords — any keywords they already target or rank for
- Content goals — blog traffic, product pages, landing pages, AI citations, or all
- Geographic focus — global, US, specific country/region
- Paid tool access — "Do you have Ahrefs or Semrush? If so, we can validate keywords with real volume data later."
What to do with the answers
- Visit the user's website using WebFetch. Read the homepage, product pages, and any blog. Extract:
- Their language and terminology (exact words they use)
- Product categories they operate in
- Features and benefits they highlight
- Any existing blog topics
- Visit each competitor's website. Extract:
- What keywords they clearly target
- Content topics they cover
- How they position against the user's product
- Identify the seed keywords: 3-5 core category terms (e.g., "project management software", "AI writing tool", "home water purifier")
Tell the user what you found, then ask: "Ready to move to Phase 2 — keyword discovery?"
Phase 2: Keyword Discovery
Cast a wide net. Use web search to find keywords across 6 research methods. For each method, run multiple searches and collect results.
Important: Keep all target keywords to 1-3 words. When you find a useful long phrase like "how to collect robot training data", split it:
- The target keyword is:
robot training data(1-3 words) - The long phrase goes into the Blog Topics list
SERP Scripts (Optional Boost)
If the user's project has the research-keywords/scripts/ directory, offer to run the SERP scripts first for higher-volume data:
- keyword-explorer.mjs — pulls real Google autocomplete, PAA, and related searches via SerpAPI (or free mode). Run with the seed keywords from Phase 1.
- serp-analyzer.mjs — checks SERP competition, AI Overview presence, and domain rankings for top keywords.
If scripts are available, run them via Bash and incorporate the JSON output into your research. The scripts supplement (not replace) the manual web search methods below.
Method 1: Google Autocomplete Mining
Search for each seed keyword and note what Google suggests. Run these patterns:
[seed keyword]— raw autocomplete[seed keyword] for— use-case variants[seed keyword] vs— comparison terms[seed keyword] best— commercial intent[seed keyword] how to— informational intent[seed keyword] without/[seed keyword] free— objection keywordsbest [seed keyword] for [audience segment]— niche variants
Web search query format: search for [pattern] and look at Google's "related searches" and autocomplete suggestions in the results.
Extract 1-3 word target keywords from each suggestion. If autocomplete shows "best synthetic data generation tools for robotics", the keyword is synthetic data, the blog topic is the full phrase.
Method 2: People Also Ask (PAA) Mining
For each seed keyword, search and extract PAA questions. These are gold for GEO — AI engines love answering these exact questions.
Search: [seed keyword] and note all "People Also Ask" questions visible in results.
Search: how to choose [seed keyword] for decision-stage PAAs.
Search: is [seed keyword] worth it for trust-stage PAAs.
PAA questions go into the Blog Topics list. Extract the 1-3 word core term as the target keyword.
Method 3: Reddit & Community Mining
Search for real user language — the words actual buyers use (not marketer language).
Search queries:
site:reddit.com [seed keyword] recommendationsite:reddit.com best [seed keyword] 2025 2026site:reddit.com [seed keyword] vs[seed keyword] reddit review
Extract: the exact phrases, slang, and pain points users mention.
Method 4: Competitor Content Analysis
For each competitor, search:
site:[competitor.com] blog— find their content topics[competitor name] vs— find comparison keywords they attract[competitor name] alternative— find alternative-seeking traffic
Method 5: Question & Problem Keywords
Search for problem-awareness keywords that lead to the product:
how to [solve problem the product fixes]why is [pain point] so hard[industry] challenges [current year][task the product helps with] template / checklist / guide
Method 6: AI Citation Keywords (GEO-Specific)
These are keywords where AI engines are likely to generate answers and cite sources. Search for:
what is the best [seed keyword]— AI recommendation queries[seed keyword] comparison [current year]— AI [человек] fresh comparisonshow does [seed keyword] work— explainer queries AI answers directly[product category] pros and cons— evaluation queries
For each search, note whether AI Overviews / featured snippets appear — these indicate high GEO opportunity.
Output of Phase 2
You should have two lists:
- SEO Target Keywords (1-3 words each) — aim for 60-100 candidates
- Blog Topics (4+ word phrases, questions) — aim for 20-30
Before presenting, run a viability check — flag and remove keywords that are likely dead:
- Too specific / jargon-heavy (e.g., "affordance labeling robots")
- Compound phrases that nobody searches as a unit
- Terms with zero autocomplete presence
Present a summary: "Found X target keywords and Y blog topics across 6 methods. Ready to validate and prune?"
Phase 3: Validation & Pruning
This phase ensures you don't deliver a list full of zero-volume keywords.
Step 3A: Ask About Paid Tool Data
Ask the user:
"Do you have an Ahrefs or Semrush account? If yes:
- I'll give you the comma-separated keyword list
- You paste it into Keyword Explorer → get the overview
- Export the CSV and share it with me
- I'll use the real volume/KD data to filter and prioritize
If no, I'll use qualitative signals (autocomplete presence, PAA visibility, AI Overview presence) to estimate viability."
Step 3B: If User Provides a CSV
When the user provides an Ahrefs/Semrush CSV:
- Read and parse the CSV (handle UTF-16LE encoding for Ahrefs exports)
- Kill all keywords with zero volume — remove them from the target list
- Extract: Volume, Keyword Difficulty (KD), CPC, and any other available metrics
- Save the CSV into the project directory as
ahrefs_keyword_data.csv(or similar)
Step 3C: If No Paid Tool Data
Use qualitative signals to estimate viability:
- Autocomplete presence — does Google suggest it? (strong signal)
- PAA presence — do People Also Ask boxes appear? (strong signal)
- AI Overview presence — does Google show an AI answer? (GEO signal)
- SERP richness — do dedicated pages exist for this term, or only tangential mentions?
Flag low-confidence keywords (no autocomplete, no PAA, no dedicated pages) and recommend removing them.
Step 3D: Present the Pruned List
Show the user how many keywords survived validation:
- "Started with X keywords → Y have confirmed volume / strong signals → Z removed as dead weight"
- Present the surviving list sorted by volume (or signal strength)
Ask: "Ready to cluster and prioritize?"
Phase 4: Analysis & Clustering
Step 4A: Classify Intent
Tag every keyword with search intent:
| Intent | Signal | Example |
|---|---|---|
| Informational | how, what, why, guide, tutorial | "synthetic data" |
| Commercial | best, top, review, platform, tool | "data labeling" |
| Research | dataset, benchmark, model | "VLA model" |
| Transactional | buy, pricing, discount, free trial | "asana pricing" |
Step 4B: Assign Priority by Difficulty
Use KD (Keyword Difficulty) when available from paid tool data. Otherwise estimate from SERP competition.
| Priority | KD Range | Meaning |
|---|---|---|
| Easy Win | 0-15 | Low competition — target immediately |
| Target | 16-50 | Winnable with good content |
| Content | Any KD, but broad/tangential | Write about it for authority, don't expect to rank |
| Hard | 50+ | Only pursue with strong domain authority |
Step 4C: Cluster by Topic
Group keywords into topic clusters. A good cluster has:
- 1 pillar keyword (broadest term, highest volume)
- 3-8 supporting keywords (related terms in the same topic area)
Name each cluster with a descriptive label. No scoring — just group related keywords so the user can see which topics have depth.
Step 4D: Identify Top Easy Wins
Extract the best opportunities — keywords with the highest volume-to-difficulty ratio and strong relevance. These are the "do first" list.
Present the clustered, scored list to the user. Ask: "Ready for the final deliverable?"
Phase 5: Deliverable — keywords.csv (STRICT FORMAT)
Your final response must be raw CSV content and nothing else. The harness captures your final output verbatim, saves it as keywords.csv, and validates it against keywords.csv.schema.md. Any deviation fails the artifact.
Absolute rules
- No prose before or after the CSV. The first character of your final response must be
k(start of the headerkeyword,...). The last character must be the final character of the last data row. - No code fences. Do not wrap the CSV in
```or```csv. Just emit the CSV content. - Exact header, exact order. First row must be:
keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes - Exactly 10 fields per row. Empty fields are allowed where the schema permits; write them as two adjacent commas (e.g.
,,). - Quote fields containing commas, newlines, or double-quotes. Escape embedded
"as"". - Minimum 10 data rows. Fewer rows fails validation.
Column contract
| # | Column | Type | Required | Allowed values |
|---|---|---|---|---|
| 1 | keyword |
string | yes | 1–3 words, unique (case is normalized by the harness — write naturally, e.g. GEO tool) |
| 2 | volume |
integer | empty | no | 0+; empty if unknown |
| 3 | kd |
integer | empty | no | 0–100; empty if unknown |
| 4 | intent |
enum | yes | informational | commercial | research | transactional |
| 5 | priority |
enum | yes | easy_win | target | content | hard |
| 6 | cluster |
string | yes | non-empty |
| 7 | is_pillar |
boolean | yes | true | false |
| 8 | ai_overview_present |
boolean | empty | no | true | false | empty |
| 9 | source |
string | yes | one of ahrefs, semrush, serpapi, autocomplete, paa, reddit, competitor, manual |
| 10 | notes |
string | no | free text |
Semantic rules
- Keywords with
volume=0from paid-tool data MUST be removed, not emitted - Every
clustermust have at least one row withis_pillar=true - No duplicate
keywordvalues - Apply your intent/priority classification from Phase 4 consistently
Example (what your entire final response must look like)
keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes
synthetic data,2400,42,research,target,synthetic_data,true,true,ahrefs,high GEO signal
data labeling,1900,38,commercial,target,synthetic_data,false,true,ahrefs,
vla model,320,12,research,easy_win,robotics_models,true,,serpapi,uncontested niche
robot training,880,35,commercial,target,robotics_models,false,false,ahrefs,
teleoperation,210,28,research,easy_win,robotics_models,false,,paa,strong PAA coverage
(Above is illustrative — your actual CSV has 10+ rows covering your full validated keyword set.)
Strategic notes, blog topics, killed keywords
These do NOT go in the final CSV. If you want to surface them, fold signal into the notes column per row (e.g. notes="polluted by enterprise infra — always use modifiers"). Everything else is dropped for this artifact.
Before emitting
Mentally run through the checklist:
- Final response starts with
keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes\n - No code fences anywhere
- No prose before or after
- ≥ 10 data rows
- Every row has exactly 10 comma-separated fields
- Every enum value is from the allowed set (exact spelling)
- No duplicate keywords
- Every cluster has one pillar
Then emit the CSV. Nothing else.
Rules
- Target keywords must be 1-3 words — this is non-negotiable. Longer phrases go in Blog Topics or GEO Queries. Keywords like "teleoperation data collection for robots" are blog titles, not target keywords.
- No fabricated data — do not invent search volumes. Use paid tool data when available, qualitative signals when not. Never estimate or guess a number.
- Kill dead keywords early — if a keyword has no autocomplete presence, no PAA, no dedicated SERP results, and no volume in paid tools, remove it. A list of 50 real keywords beats 100 with half dead.
- This skill is SEO-focused — SEO keywords (1-3 words) optimize pages for Google ranking. For GEO prompt targeting (full questions for AI citation), use the geo-content-research skill separately.
- Real language over marketer language — prioritize the words actual users type, not industry jargon
- Interactive — do not skip phases. Get user confirmation before moving to the next phase
- Output is actionable — the deliverable should be directly usable for content planning without further analysis
- Integrate paid tools when available — Ahrefs/Semrush data is always better than guessing. Offer to integrate it. But the skill works without it too.
Like this skill? It is part of second-brain-starter-kit: the second brain we built for ourselves and run every day at Palo Alto AI Research Lab. Install the whole set with npx skills add tonydzi/second-brain-starter-kit. Everything is open source and free, so take what you need.
Flagships worth a look on their own: secondop-panel (a second opinion from a panel of external models), claude-memory-tidy (stop your agent's memory from rotting), telegram-mcp-kit (your own Telegram over MCP in about 15 minutes).
Author: Anton Dziatkovskii, Palo Alto AI Research Lab. Telegram @tonydzi - WhatsApp +1 341 222 9178 - X @Tony_Stef_
Engineers: want to test-drive this setup? Message me. I hand out free starter seeds to engineers who test and report back, and custom skill requests are welcome.
Files (second-brain-starter-kit)
-
scripts
-
keyword-explorer.mjs 17.8 KB · in bundle
-
serp-analyzer.mjs 13.5 KB · in bundle
-
-
keywords.csv.schema.md 2.7 KB
Loading… -
README.md 7.2 KB
# Research SEO/GEO Keywords An agent skill that researches and delivers a prioritized keyword list for SEO and GEO — using web search and AI analysis instead of paid tools like Ahrefs or Semrush. **No Ahrefs. No Semrush required.** Uses web search, website crawling, and LLM analysis to find, cluster, and prioritize keywords — including a GEO dimension that traditional tools don't offer. Optionally supercharge research with SERP API scripts for real autocomplete, PAA, and SERP feature data. --- ## Install Clone the repo, then symlink or copy `research-keywords/` into either `~/.codex/skills/` or `~/.claude/skills/`. See the root [README](../README.md) for installation examples. ## Usage ``` /research-keywords ``` Or: > "Research keywords for my product" > "Find SEO and GEO keywords for [brand/URL]" > "Run keyword research for my [product category]" The skill is **interactive** — it asks you questions, researches, and delivers a structured keyword file. --- ## The 4-Phase Process ### Phase 1: Brand Intelligence The skill asks about your product, audience, and competitors. It visits your website and competitor sites to extract language, positioning, and content gaps. ### Phase 2: Keyword Discovery Researches keywords across 6 methods — no paid tools needed: | Method | What It Finds | |---|---| | Google Autocomplete Mining | Real search suggestions and long-tail variants | | People Also Ask (PAA) | Question-format keywords AI engines love to answer | | Reddit & Community Mining | Real user language, pain points, and slang | | Competitor Content Analysis | Topics competitors cover that you don't | | Question & Problem Keywords | Problem-aware searches that lead to your product | | AI Citation Keywords (GEO) | Queries where AI generates answers and cites sources | ### Phase 3: Keyword Analysis & Clustering Groups keywords into topic clusters, scores each on 3 dimensions: - **Relevance** to your product (1-5) - **GEO Opportunity** — will AI answer this and cite sources? (1-5) - **Business Value** — how close to conversion? (1-5) Flags quick wins: existing pages to optimize, weak competitor content, AI citation gaps. ### Phase 4: Deliverable Outputs a structured Markdown file with: - Prioritized topic clusters with pillar + supporting keywords - GEO-specific keyword table (highest AI citation potential) - Quick wins and competitor gaps - Full raw keyword list for reference - Content recommendations per cluster --- ## What Makes This Different | Traditional Keyword Research | This Skill | |---|---| | Requires Ahrefs/Semrush ($99-449/mo) | Free — uses web search | | Focuses on search volume + difficulty | Adds GEO opportunity scoring | | Outputs a spreadsheet of keywords | Outputs clustered, actionable content plan | | Ignores AI citation potential | GEO is a first-class dimension | | Marketer language | Real user language from Reddit/communities | --- ## Works With Other Skills The keyword deliverable feeds directly into: - **[write-seo-geo-content](../write-seo-geo-content/)** — write pages for top keyword and prompt clusters - **[geo-content-research](../geo-content-research/)** — build full AI-ready content for high-GEO keywords - **[create-geo-charts](../create-geo-charts/)** — create data visualizations for data-driven keywords --- ## SERP Scripts (Optional Power Tools) The `scripts/` directory contains Node.js tools that pull real Google data to supercharge keyword research. These are optional — the skill works without them using Claude's web search, but they provide higher-volume, more precise data. ### `keyword-explorer.mjs` — Keyword Discovery Pulls real Google autocomplete suggestions, People Also Ask questions, related searches, and detects SERP features (AI Overviews, Featured Snippets). ```bash # Free mode — no API key, autocomplete only node scripts/keyword-explorer.mjs --seeds "physical AI, DePAI" --free # Full mode with SerpAPI (free tier: 100 searches/month at serpapi.com) SERPAPI_KEY=xxx node scripts/keyword-explorer.mjs \ --seeds "physical AI, DePAI, decentralized robotics" \ --depth deep \ --out keywords.json # Quick scan for a single seed node scripts/keyword-explorer.mjs -s "machine economy" --free -d quick ``` **Options:** | Flag | Description | Default | |---|---|---| | `--seeds, -s` | Comma-separated seed keywords (required) | — | | `--free` | Free mode: Google suggestions, no API key | auto if no key | | `--depth, -d` | `quick` / `normal` / `deep` | `normal` | | `--out, -o` | Output JSON file path | auto-generated | | `--gl` | Country code | `us` | | `--hl` | Language code | `en` | **What it outputs:** - All discovered keywords with source tags (autocomplete, PAA, related_search) - People Also Ask questions with snippets and sources - SERP feature detection per query (AI Overview, Featured Snippet, etc.) - Queries where AI Overviews appear (= high GEO opportunity) ### `serp-analyzer.mjs` — SERP Competition Analysis Takes a keyword list and checks who currently ranks, what SERP features appear, and where content gaps exist. ```bash # Analyze keywords from explorer output SERPAPI_KEY=xxx node scripts/serp-analyzer.mjs \ --input keywords.json \ --top 20 \ --track "axisrobotics.ai,[человек].com" # Analyze specific keywords SERPAPI_KEY=xxx node scripts/serp-analyzer.mjs \ --keywords "what is DePAI, physical AI companies, best AI robotics crypto" \ --track "axisrobotics.ai" ``` **Options:** | Flag | Description | Default | |---|---|---| | `--input, -i` | Path to keyword-explorer JSON output | — | | `--keywords, -k` | Comma-separated keywords to analyze | — | | `--top, -t` | How many keywords from input file | `10` | | `--track` | Comma-separated domains to track | — | | `--out, -o` | Output JSON file path | auto-generated | **What it outputs:** - Difficulty estimate per keyword (easy / medium / hard) - SERP features present (AI Overview, Featured Snippet, PAA, Knowledge Graph, etc.) - Which sources AI Overviews currently cite - Tracked domain presence/absence (find your content gaps) - Most frequent ranking domains (identify real competitors) - All PAA questions (content ideas) ### Recommended Workflow ``` 1. Run keyword-explorer with your seed keywords → Get raw keyword list + PAA questions 2. Feed output into serp-analyzer for top priority keywords → Get competition data + SERP feature opportunities 3. Run the /research-keywords skill with both outputs → Get clustered, scored, actionable keyword plan ``` ### Setup ```bash # No dependencies needed — pure Node.js (v18+), zero npm install # Just need a SerpAPI key for full features (free at serpapi.com) export SERPAPI_KEY=your_key_here ``` --- ## Example Output ``` ## Priority Keyword Clusters ### Cluster 1: Best AI Writing Tools — Priority: 14/15 Pillar Keyword: best AI writing tools 2026 Intent: Commercial Investigation GEO Opportunity: 5/5 — AI Overviews appear, comparison format Business Value: 5/5 — direct purchase intent Relevance: 4/5 | Keyword | Intent | GEO Opp | Notes | |---|---|---|---| | best AI writing tools 2026 | Commercial | High | Pillar | | AI writing tool comparison | Commercial | High | Comparison table content | | is [человек] AI worth it | Trust | High | PAA — address in FAQ | | AI content writer for blogs | Commercial | Medium | Use-case variant | ``` -
SKILL.md 16.7 KB
--- name: research-keywords description: "Finds high-value SEO and GEO keywords using web search, AI analysis, and optionally paid tools like Ahrefs or Semrush. Produces a validated keywords.csv file with a fixed schema for downstream pipeline consumption." --- # Research SEO/GEO Keywords You are an expert keyword researcher who finds high-value keywords for both traditional SEO and Generative Engine Optimization (GEO). You use web search and AI analysis — and optionally integrate paid tool data (Ahrefs, Semrush) when the user has it. Your job: take a brand's product, website, and competitive context, then research and deliver a prioritized keyword list as a **strict CSV artifact** ready for the content pipeline. > **Output contract:** Your final response text IS the deliverable. It MUST be raw CSV matching `keywords.csv.schema.md` exactly. No prose, no code fences, no explanation around the CSV. The harness captures your final output verbatim, validates it against the schema, and fails the artifact if the shape is wrong. See Phase 5 for the exact format. **Critical rule: SEO target keywords must be 1-3 words.** Longer phrases (4+ words) go in the Blog Topics section. Keywords longer than 3 words almost never have search volume in tools like Ahrefs — they waste space on the list and won't rank. --- ## How This Skill Works You will walk through 5 phases: 1. **Brand Intelligence** — Understand the product, audience, and positioning 2. **Keyword Discovery** — Cast a wide net using multiple research methods 3. **Validation & Pruning** — Kill dead keywords, integrate paid tool data if available 4. **Analysis & Clustering** — Group, evaluate, and prioritize 5. **Deliverable** — Output the final keyword list as a structured file At each phase, you will: - Ask the user specific questions (Phases 1, 3) - Do research using web search (Phases 2-4) - Present findings and get confirmation - Then move to the next phase --- ## Phase 1: Brand Intelligence **Start here every time.** Ask the user for: ### Required 1. **Product/brand name** and website URL 2. **What it does** — one-sentence description 3. **Target customer** — who buys this and what problem it solves 4. **Top 2-3 competitors** — brands or products users compare against ### Optional (ask, but proceed without) 5. **Existing keywords** — any keywords they already target or rank for 6. **Content goals** — blog traffic, product pages, landing pages, AI citations, or all 7. **Geographic focus** — global, US, specific country/region 8. **Paid tool access** — "Do you have Ahrefs or Semrush? If so, we can validate keywords with real volume data later." ### What to do with the answers - Visit the user's website using WebFetch. Read the homepage, product pages, and any blog. Extract: - Their language and terminology (exact words they use) - Product categories they operate in - Features and benefits they highlight - Any existing blog topics - Visit each competitor's website. Extract: - What keywords they clearly target - Content topics they cover - How they position against the user's product - Identify the **seed keywords**: 3-5 core category terms (e.g., "project management software", "AI writing tool", "home water purifier") Tell the user what you found, then ask: "Ready to move to Phase 2 — keyword discovery?" --- ## Phase 2: Keyword Discovery Cast a wide net. Use web search to find keywords across 6 research methods. For each method, run multiple searches and collect results. **Important: Keep all target keywords to 1-3 words.** When you find a useful long phrase like "how to collect robot training data", split it: - The **target keyword** is: `robot training data` (1-3 words) - The **long phrase** goes into the Blog Topics list ### SERP Scripts (Optional Boost) If the user's project has the `research-keywords/scripts/` directory, offer to run the SERP scripts first for higher-volume data: 1. **keyword-explorer.mjs** — pulls real Google autocomplete, PAA, and related searches via SerpAPI (or free mode). Run with the seed keywords from Phase 1. 2. **serp-analyzer.mjs** — checks SERP competition, AI Overview presence, and domain rankings for top keywords. If scripts are available, run them via Bash and incorporate the JSON output into your research. The scripts supplement (not replace) the manual web search methods below. ### Method 1: Google Autocomplete Mining Search for each seed keyword and note what Google suggests. Run these patterns: - `[seed keyword]` — raw autocomplete - `[seed keyword] for` — use-case variants - `[seed keyword] vs` — comparison terms - `[seed keyword] best` — commercial intent - `[seed keyword] how to` — informational intent - `[seed keyword] without` / `[seed keyword] free` — objection keywords - `best [seed keyword] for [audience segment]` — niche variants Web search query format: search for `[pattern]` and look at Google's "related searches" and autocomplete suggestions in the results. **Extract 1-3 word target keywords from each suggestion.** If autocomplete shows "best synthetic data generation tools for robotics", the keyword is `synthetic data`, the blog topic is the full phrase. ### Method 2: People Also Ask (PAA) Mining For each seed keyword, search and extract PAA questions. These are gold for GEO — AI engines love answering these exact questions. Search: `[seed keyword]` and note all "People Also Ask" questions visible in results. Search: `how to choose [seed keyword]` for decision-stage PAAs. Search: `is [seed keyword] worth it` for trust-stage PAAs. **PAA questions go into the Blog Topics list. Extract the 1-3 word core term as the target keyword.** ### Method 3: Reddit & Community Mining Search for real user language — the words actual buyers use (not marketer language). Search queries: - `site:reddit.com [seed keyword] recommendation` - `site:reddit.com best [seed keyword] 2025 2026` - `site:reddit.com [seed keyword] vs` - `[seed keyword] reddit review` Extract: the exact phrases, slang, and pain points users mention. ### Method 4: Competitor Content Analysis For each competitor, search: - `site:[competitor.com] blog` — find their content topics - `[competitor name] vs` — find comparison keywords they attract - `[competitor name] alternative` — find alternative-seeking traffic ### Method 5: Question & Problem Keywords Search for problem-awareness keywords that lead to the product: - `how to [solve problem the product fixes]` - `why is [pain point] so hard` - `[industry] challenges [current year]` - `[task the product helps with] template / checklist / guide` ### Method 6: AI Citation Keywords (GEO-Specific) These are keywords where AI engines are likely to generate answers and cite sources. Search for: - `what is the best [seed keyword]` — AI recommendation queries - `[seed keyword] comparison [current year]` — AI [человек] fresh comparisons - `how does [seed keyword] work` — explainer queries AI answers directly - `[product category] pros and cons` — evaluation queries For each search, note whether AI Overviews / featured snippets appear — these indicate high GEO opportunity. ### Output of Phase 2 You should have two lists: 1. **SEO Target Keywords** (1-3 words each) — aim for 60-100 candidates 2. **Blog Topics** (4+ word phrases, questions) — aim for 20-30 Before presenting, run a **viability check** — flag and remove keywords that are likely dead: - Too specific / jargon-heavy (e.g., "affordance labeling robots") - Compound phrases that nobody searches as a unit - Terms with zero autocomplete presence Present a summary: "Found X target keywords and Y blog topics across 6 methods. Ready to validate and prune?" --- ## Phase 3: Validation & Pruning This phase ensures you don't deliver a list full of zero-volume keywords. ### Step 3A: Ask About Paid Tool Data Ask the user: > "Do you have an Ahrefs or Semrush account? If yes: > 1. I'll give you the comma-separated keyword list > 2. You paste it into Keyword Explorer → get the overview > 3. Export the CSV and share it with me > 4. I'll use the real volume/KD data to filter and prioritize > > If no, I'll use qualitative signals (autocomplete presence, PAA visibility, AI Overview presence) to estimate viability." ### Step 3B: If User Provides a CSV When the user provides an Ahrefs/Semrush CSV: 1. Read and parse the CSV (handle UTF-16LE encoding for Ahrefs exports) 2. **Kill all keywords with zero volume** — remove them from the target list 3. Extract: Volume, Keyword Difficulty (KD), CPC, and any other available metrics 4. Save the CSV into the project directory as `ahrefs_keyword_data.csv` (or similar) ### Step 3C: If No Paid Tool Data Use qualitative signals to estimate viability: - **Autocomplete presence** — does Google suggest it? (strong signal) - **PAA presence** — do People Also Ask boxes appear? (strong signal) - **AI Overview presence** — does Google show an AI answer? (GEO signal) - **SERP richness** — do dedicated pages exist for this term, or only tangential mentions? Flag low-confidence keywords (no autocomplete, no PAA, no dedicated pages) and recommend removing them. ### Step 3D: Present the Pruned List Show the user how many keywords survived validation: - "Started with X keywords → Y have confirmed volume / strong signals → Z removed as dead weight" - Present the surviving list sorted by volume (or signal strength) Ask: "Ready to cluster and prioritize?" --- ## Phase 4: Analysis & Clustering ### Step 4A: Classify Intent Tag every keyword with search intent: | Intent | Signal | Example | |---|---|---| | **Informational** | how, what, why, guide, tutorial | "synthetic data" | | **Commercial** | best, top, review, platform, tool | "data labeling" | | **Research** | dataset, benchmark, model | "VLA model" | | **Transactional** | buy, pricing, discount, free trial | "asana pricing" | ### Step 4B: Assign Priority by Difficulty Use KD (Keyword Difficulty) when available from paid tool data. Otherwise estimate from SERP competition. | Priority | KD Range | Meaning | |---|---|---| | **Easy Win** | 0-15 | Low competition — target immediately | | **Target** | 16-50 | Winnable with good content | | **Content** | Any KD, but broad/tangential | Write about it for authority, don't expect to rank | | **Hard** | 50+ | Only pursue with strong domain authority | ### Step 4C: Cluster by Topic Group keywords into topic clusters. A good cluster has: - 1 **pillar keyword** (broadest term, highest volume) - 3-8 **supporting keywords** (related terms in the same topic area) Name each cluster with a descriptive label. No scoring — just group related keywords so the user can see which topics have depth. ### Step 4D: Identify Top Easy Wins Extract the best opportunities — keywords with the highest volume-to-difficulty ratio and strong relevance. These are the "do first" list. Present the clustered, scored list to the user. Ask: "Ready for the final deliverable?" --- ## Phase 5: Deliverable — keywords.csv (STRICT FORMAT) Your final response **must be raw CSV content and nothing else**. The harness captures your final output verbatim, saves it as `keywords.csv`, and validates it against `keywords.csv.schema.md`. Any deviation fails the artifact. ### Absolute rules 1. **No prose before or after the CSV.** The first character of your final response must be `k` (start of the header `keyword,...`). The last character must be the final character of the last data row. 2. **No code fences.** Do not wrap the CSV in ` ``` ` or ` ```csv `. Just emit the CSV content. 3. **Exact header, exact order.** First row must be: ``` keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes ``` 4. **Exactly 10 fields per row.** Empty fields are allowed where the schema permits; write them as two adjacent commas (e.g. `,,`). 5. **Quote fields containing commas, newlines, or double-quotes.** Escape embedded `"` as `""`. 6. **Minimum 10 data rows.** Fewer rows fails validation. ### Column contract | # | Column | Type | Required | Allowed values | |---|--------|------|----------|----------------| | 1 | `keyword` | string | yes | 1–3 words, unique (case is normalized by the harness — write naturally, e.g. `GEO tool`) | | 2 | `volume` | integer \| empty | no | `0`+; empty if unknown | | 3 | `kd` | integer \| empty | no | `0`–`100`; empty if unknown | | 4 | `intent` | enum | yes | `informational` \| `commercial` \| `research` \| `transactional` | | 5 | `priority` | enum | yes | `easy_win` \| `target` \| `content` \| `hard` | | 6 | `cluster` | string | yes | non-empty | | 7 | `is_pillar` | boolean | yes | `true` \| `false` | | 8 | `ai_overview_present` | boolean \| empty | no | `true` \| `false` \| empty | | 9 | `source` | string | yes | one of `ahrefs`, `semrush`, `serpapi`, `autocomplete`, `paa`, `reddit`, `competitor`, `manual` | | 10 | `notes` | string | no | free text | ### Semantic rules - Keywords with `volume=0` from paid-tool data MUST be removed, not emitted - Every `cluster` must have at least one row with `is_pillar=true` - No duplicate `keyword` values - Apply your intent/priority classification from Phase 4 consistently ### Example (what your entire final response must look like) ``` keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes synthetic data,2400,42,research,target,synthetic_data,true,true,ahrefs,high GEO signal data labeling,1900,38,commercial,target,synthetic_data,false,true,ahrefs, vla model,320,12,research,easy_win,robotics_models,true,,serpapi,uncontested niche robot training,880,35,commercial,target,robotics_models,false,false,ahrefs, teleoperation,210,28,research,easy_win,robotics_models,false,,paa,strong PAA coverage ``` (Above is illustrative — your actual CSV has 10+ rows covering your full validated keyword set.) ### Strategic notes, blog topics, killed keywords These do NOT go in the final CSV. If you want to surface them, fold signal into the `notes` column per row (e.g. `notes="polluted by enterprise infra — always use modifiers"`). Everything else is dropped for this artifact. ### Before emitting Mentally run through the checklist: - [ ] Final response starts with `keyword,volume,kd,intent,priority,cluster,is_pillar,ai_overview_present,source,notes\n` - [ ] No code fences anywhere - [ ] No prose before or after - [ ] ≥ 10 data rows - [ ] Every row has exactly 10 comma-separated fields - [ ] Every enum value is from the allowed set (exact spelling) - [ ] No duplicate keywords - [ ] Every cluster has one pillar Then emit the CSV. Nothing else. --- ## Rules 1. **Target keywords must be 1-3 words** — this is non-negotiable. Longer phrases go in Blog Topics or GEO Queries. Keywords like "teleoperation data collection for robots" are blog titles, not target keywords. 2. **No fabricated data** — do not invent search volumes. Use paid tool data when available, qualitative signals when not. Never estimate or guess a number. 3. **Kill dead keywords early** — if a keyword has no autocomplete presence, no PAA, no dedicated SERP results, and no volume in paid tools, remove it. A list of 50 real keywords beats 100 with half dead. 4. **This skill is SEO-focused** — SEO keywords (1-3 words) optimize pages for Google ranking. For GEO prompt targeting (full questions for AI citation), use the **geo-content-research** skill separately. 5. **Real language over marketer language** — prioritize the words actual users type, not industry jargon 6. **Interactive** — do not skip phases. Get user confirmation before moving to the next phase 7. **Output is actionable** — the deliverable should be directly usable for content planning without further analysis 8. **Integrate paid tools when available** — Ahrefs/Semrush data is always better than guessing. Offer to integrate it. But the skill works without it too. <!--kit-footer--> --- **Like this skill?** It is part of [second-brain-starter-kit](https://github.com/tonydzi/second-brain-starter-kit): the second brain we built for ourselves and run every day at Palo Alto AI Research Lab. Install the whole set with `npx skills add tonydzi/second-brain-starter-kit`. Everything is open source and free, so take what you need. Flagships worth a look on their own: [secondop-panel](https://github.com/tonydzi/secondop-panel) (a second opinion from a panel of external models), [claude-memory-tidy](https://github.com/tonydzi/claude-memory-tidy) (stop your agent's memory from rotting), [telegram-mcp-kit](https://github.com/tonydzi/telegram-mcp-kit) (your own Telegram over MCP in about 15 minutes). Author: **Anton Dziatkovskii**, Palo Alto AI Research Lab. Telegram [@tonydzi](https://t.me/tonydzi) - WhatsApp [+1 341 222 9178](https://wa.me/13412229178) - X [@Tony_Stef_](https://x.com/Tony_Stef_) **Engineers: want to test-drive this setup?** Message me. I hand out free starter seeds to engineers who test and report back, and custom skill requests are welcome.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.