On Activation

1. Check if brand/ directory exists in the project root.
2. If it does, read available files: voice-profile.md, positioning.md, audience.md, creative-kit.md, stack.md, learnings.md.
3. Apply any loaded brand context to enhance output quality.
4. If brand/ does not exist, proceed without it — this skill works standalone.

Note: Examples below use fictional brands (Acme, Lumi, Helm). Replace with your own brand context.

/keyword-research -- Data-Backed Keyword Strategy

Most keyword research is backwards. People start with tools, get overwhelmed by data, and end up with a spreadsheet they never use.

This skill starts with strategy. What does your business need? Who are you trying to reach? What would make them find you? Then it validates with live search data and builds a content plan that actually makes sense.

No expensive tools required. Systematic thinking plus web search.

Reads: positioning.md, audience.md, competitors.md, learnings.md Writes: brand/keyword-plan.md, campaigns/content-plan/*.md

Iteration Detection

Before starting, check whether ./brand/keyword-plan.md already exists.

If keyword-plan.md EXISTS --> Refresh Mode

Do not start from scratch. Instead:

1. Read the existing plan.

2. Present a summary of the current keyword strategy:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
     EXISTING KEYWORD PLAN
     Last updated {date} by /keyword-research
   
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
     Pillars:
     ├── {Pillar 1}    {N} clusters    Priority: {level}
     ├── {Pillar 2}    {N} clusters    Priority: {level}
     └── {Pillar 3}    {N} clusters    Priority: {level}
   
     Top keywords:
     ├── {keyword 1}   {priority}
     ├── {keyword 2}   {priority}
     └── {keyword 3}   {priority}
   
     Content briefs: {N} created, {N} published
   
     ──────────────────────────────────────────────
   
     What would you like to do?
   
     ① Refresh with new SERP data
     ② Add a new topic area
     ③ Re-prioritize existing clusters
     ④ Full rebuild from scratch
     ⑤ Generate briefs for top keywords
   

3. Process the user's choice:

   • Option ① --> Re-run web search for existing keywords, update priorities based on fresh data
   • Option ② --> Gather new seed keywords, run full expansion, merge into existing plan
   • Option ③ --> Re-score all clusters with updated business context
   • Option ④ --> Full process from scratch
   • Option ⑤ --> Skip to content brief generation for highest-priority unfilled clusters

4. Before overwriting, show a diff of what changed:

   Changes to keyword plan:
   
   New clusters added:
   ├── "AI email marketing" (Pillar: AI Marketing)
   └── "automated content creation" (Pillar: AI Marketing)
   
   Priority changes:
   ├── "marketing automation" High → Critical
   └── "fractional CMO" Medium → Low
   
   Removed:
   └── "our methodology" (failed validation)
   
   Save these changes? (y/n)
   

5. Only overwrite after explicit confirmation.

If keyword-plan.md DOES NOT EXIST --> Full Research Mode

Proceed to the full process below.

The Core Job

Transform a business context into a prioritized content plan with:

• Keyword clusters organized by topic
• Priority ranking based on opportunity and live SERP data
• Content type recommendations
• Individual content briefs for top keywords
• A clear "start here" action

Output format: Clustered keywords mapped to content pieces, prioritized by business value, competitive opportunity, and search demand. Saved to disk as a keyword plan and individual content briefs.

The Process

SEED --> EXPAND --> SEARCH --> CLUSTER --> VALIDATE --> PRIORITIZE --> MAP --> BRIEF

1. Seed -- Generate initial keywords from business context and brand memory
2. Expand -- Use the 6 Circles Method to build the full list
3. Search -- Pull live SERP data: autocomplete, People Also Ask, competitor rankings
4. Cluster -- Group related keywords into content pillars
5. Validate -- Run 4-check pillar validation with live competitive data
6. Prioritize -- Score by opportunity, business value, and search evidence
7. Map -- Assign clusters to specific content pieces
8. Brief -- Generate individual content briefs for top priorities

Before Starting: Gather Context

Get these inputs before generating anything. If brand memory files exist, pre-fill what you can and confirm with the user.

1. What do you sell/offer? (1-2 sentences)
   • Pre-fill from: ./brand/positioning.md
2. Who are you trying to reach? (Be specific)
   • Pre-fill from: ./brand/audience.md
3. What is your website? (To understand current content)
4. Who are 2-3 competitors? (Or help identify them)
   • Pre-fill from: ./brand/competitors.md
5. What is the goal? (Traffic? Leads? Sales? Authority?)
6. Timeline? (Quick wins or long-term plays?)

If brand memory supplies 3+ of these, present what you found and ask for confirmation rather than re-asking:

  From your brand profile:

  ├── Offer       "{from positioning.md}"
  ├── Audience    "{from audience.md}"
  ├── Competitors {list from competitors.md}
  └── Positioning "{angle from positioning.md}"

  Does this still look right? And two more
  questions:

  1. What is the goal -- traffic, leads, sales,
     or authority?
  2. Timeline -- quick wins or long-term plays?

Phase 1: Seed Generation

From the business context (and brand memory if loaded), generate 20-30 seed keywords covering:

Direct terms -- What you actually sell

"AI marketing automation", "fractional CMO", "marketing workflows"

Problem terms -- What pain you solve

"can't keep up with content", "marketing team too small", "don't understand AI"

Outcome terms -- What results you deliver

"faster campaign execution", "10x content production", "marketing ROI"

Category terms -- Broader industry terms

"marketing automation", "AI marketing", "growth marketing"

Brand-aligned terms -- From positioning if loaded

If positioning is "The Anti-Agency" → seed "agency alternatives", "in-house marketing", "DIY marketing strategy" If positioning is "AI-First Marketing" → seed "AI marketing tools", "automated campaigns", "machine learning marketing"

Phase 2: Expand (The 6 Circles Method)

See references/keyword-examples.md for detailed expansion techniques.

1. What You Sell -- Direct product/service terms
2. Problems You Solve -- Pain points and challenges
3. Outcomes You Deliver -- Results and benefits
4. Your Unique Positioning -- Differentiators
5. Adjacent Topics -- Related audience interests
6. Entities to Associate With -- People, brands, tools

Phase 3: Web Search Validation (Exa-stack canonical)

Data-backed research layer for each pillar keyword + top 30-50 expansions. Canonical stack (mktg-native, no Ahrefs): Exa MCP (web_search_advanced_exa, deep_search_exa, company_research_exa) + Firecrawl (autocomplete + SERP scrape) + /last30days (Reddit/X/HN aggregation) + gh CLI (OSS GitHub-stars). For Ahrefs precision see appendix in seo-machine/references/exa-recipes.md.

If Web Search Is Unavailable

Proceed with Phase 1 (seed generation) and Phase 2 (6 Circles expansion) using brand context only. Skip Phase 3 entirely but note the limitation to the user: 'Keyword clusters are based on strategic assessment, not live SERP data. Validate against actual search results before committing to content production.' Cluster and prioritize based on brand alignment and audience pain points rather than search volume.

Step 1: Google Autocomplete Mining

For each seed and pillar keyword, search for autocomplete suggestions:

Search: "[keyword] a", "[keyword] b", ... "[keyword] z"
Search: "how to [keyword]"
Search: "best [keyword]"
Search: "why [keyword]"
Search: "[keyword] vs"
Search: "[keyword] for"

Capture ever