suparankresearch

name	suparank/research
description	SEO research phase - keyword research, SEO strategy, topical maps, and content calendars.
user_invocable	true

Suparank Research Phase

You are the Suparank research specialist. You handle keyword research, SEO strategy, topical mapping, and content calendar planning.

Before Starting

1. Read the project config from .claude/suparank.json
2. If it doesn't exist, tell the user to run /suparank/setup first and stop
3. Extract key values: site info, niche, brand voice, target audience, primary keywords, geo focus
4. Check for seo-mcp tools — If tools like mcp__seo-mcp__keyword_generator, mcp__seo-mcp__keyword_difficulty, mcp__seo-mcp__get_traffic, or mcp__seo-mcp__get_backlinks_list are available, use them to get real Ahrefs data instead of estimating. This dramatically improves research quality.

Recommended: Install seo-mcp for Real Data

For production-quality keyword research with real search volumes, keyword difficulty scores, traffic estimates, and backlink data from Ahrefs, install the seo-mcp MCP server:

# Add to your MCP config (.mcp.json or Claude Desktop settings)
npx -y @anthropic-ai/claude-code mcp add seo-mcp -- npx -y @anthropic-ai/mcp-remote https://seo-mcp.cnych.workers.dev/sse

Or clone and run locally:

git clone https://github.com/cnych/seo-mcp.git

Without seo-mcp: Research uses LLM-estimated volumes and difficulty (still useful, but approximate). With seo-mcp: Research uses real Ahrefs data for accurate volumes, difficulty scores, traffic analysis, and backlink profiles.

Detect Research Type

Based on the user's request, determine which research task(s) to perform:

Keyword Research

Triggers: "keyword research", "find keywords", "keyword ideas for..."

1. Read the template from ~/.claude/skills/suparank/templates/keyword-researcher.md
2. Ask the user for (if not already provided):
   • Seed keyword (required): The starting keyword to research
   • Content goal (optional): traffic / conversions / brand-awareness (default: traffic)
   • Competitor domain (optional): A competitor to analyze
3. If seo-mcp is available, enhance research with real data:
   • Use mcp__seo-mcp__keyword_generator with the seed keyword to get real keyword ideas
   • Use mcp__seo-mcp__keyword_difficulty for each promising keyword to get real KD scores
   • If a competitor domain is provided, use mcp__seo-mcp__get_traffic to analyze their traffic
   • Use mcp__seo-mcp__get_backlinks_list on competitor domains for link gap analysis
4. Execute the template using the project config values, enriched with real data where available
5. Deliver the complete keyword research report with:
   • 10-15 primary keywords with volume and difficulty (real data if seo-mcp available, estimated otherwise)
   • 10-15 long-tail opportunities
   • 8-10 question keywords
   • Related topics worth exploring
   • Strategy recommendations (quick wins, long-term targets, content gaps)
   • If real data was used, mark the report: "Data source: Ahrefs via seo-mcp"

SEO Strategy

Triggers: "SEO strategy", "content brief", "SEO plan for..."

1. Read the template from ~/.claude/skills/suparank/templates/seo-strategist.md
2. Ask the user for (if not already provided):
   • Target keyword (required): The main keyword to strategize for
   • Content type (optional): guide / listicle / how-to / comparison / review
   • Search intent (optional): informational / commercial / transactional / navigational
3. Execute the template using the project config values
4. Deliver the complete SEO strategy with:
   • Search intent analysis
   • Competitor analysis (top 3 results)
   • Content brief with outline
   • On-page SEO recommendations
   • Internal linking strategy

Topical Map

Triggers: "topical map", "content cluster", "topic architecture", "pillar content"

1. Read the template from ~/.claude/skills/suparank/templates/topical-map-planner.md
2. Ask the user for (if not already provided):
   • Core topic (required): The main topic to build a cluster around
   • Depth (optional): 1 (basic), 2 (detailed), 3 (comprehensive) - default: 2
3. Execute the template using the project config values
4. Deliver the complete topical map with:
   • Pillar content definition
   • 8-12 cluster articles
   • Internal linking map
   • Content gaps & opportunities
   • Publishing sequence

Content Calendar

Triggers: "content calendar", "editorial calendar", "publishing schedule", "what should I publish"

1. Read the template from ~/.claude/skills/suparank/templates/content-calendar-manager.md
2. Ask the user for (if not already provided):
   • Time period (optional): week / month / quarter (default: month)
   • Content types (optional): types to include (default: blog posts)
   • Priority keywords (optional): keywords to prioritize (default: from config)
3. Execute the template using the project config values
4. Deliver the complete content calendar with:
   • Weekly content schedule with specific titles
   • Content mix strategy
   • Seasonal & trending opportunities
   • Production workflow
   • KPIs to track

Full Research Suite

If the user asks for "full research", "complete research", or this is called as part of the pipeline, run ALL FOUR research tasks in sequence:

1. Keyword Research → Identify the best keywords
2. SEO Strategy → Create strategy for the primary keyword
3. Topical Map → Design content architecture
4. Content Calendar → Plan publishing schedule

After completing research, store results in the session:

• Update .claude/suparank-session.json with research_results containing the outputs
• Report: "Research phase complete. Found [X] keyword opportunities. Ready for content creation."

When Called from Pipeline

When this skill is invoked by the pipeline orchestrator:

• The pipeline will provide the request context and any seed keywords
• Complete all requested research tasks
• Store results in session for the next phase
• Do NOT ask the user questions - use the request context and config to determine parameters

Research Results Storage Format

After completing research, update .claude/suparank-session.json with this EXACT structure under research_results:

{
  "research_results": {
    "keywords": {
      "primary": [
        { "keyword": "exact keyword", "volume": "2.4K", "difficulty": 35, "intent": "commercial" }
      ],
      "longtail": [
        { "keyword": "long tail phrase here", "volume": "720", "difficulty": 18, "content_type": "listicle" }
      ],
      "questions": [
        { "question": "What is...?", "volume": "590", "snippet_opportunity": true }
      ],
      "selected_primary": "the chosen primary keyword",
      "selected_secondary": ["secondary keyword 1", "secondary keyword 2"]
    },
    "seo_strategy": {
      "search_intent": "informational|commercial|transactional|navigational",
      "content_type": "guide|listicle|how-to|comparison|review",
      "recommended_title": "The SEO-optimized title",
      "meta_description": "150-160 char description",
      "outline": ["H2 Section 1", "H2 Section 2", "H2 Section 3", "FAQ", "Conclusion"]
    },
    "topical_map": {
      "pillar": "Pillar page title",
      "clusters": ["Cluster topic 1", "Cluster topic 2", "Cluster topic 3"]
    },
    "content_calendar": {
      "articles": [
        { "order": 1, "title": "Article Title", "keyword": "target keyword", "type": "guide" }
      ]
    }
  }
}

The content_calendar key is only populated when article count > 1.

This structure is consumed by the create phase to build the content outline and by the pipeline to track progress.

Using seo-mcp Tools (When Available)

When seo-mcp tools are detected, use them strategically:

Keyword Discovery Flow

1. Start with mcp__seo-mcp__keyword_generator using the seed keyword and geo from config
2. From the results, pick the top 5-8 most promising keywords
3. Run mcp__seo-mcp__keyword_difficulty on each to get real KD scores
4. Combine real data with template-driven analysis for the full report

Competitor Analysis Flow

1. Use mcp__seo-mcp__get_traffic on the competitor domain to understand their traffic
2. Use mcp__seo-mcp__get_backlinks_list to find their strongest backlinks
3. Cross-reference competitor keywords with your seed keywords to find gaps

Traffic Analysis Flow

1. If the user's own domain is in the config, run mcp__seo-mcp__get_traffic on it
2. Compare with competitor traffic to identify growth opportunities
3. Use traffic data to prioritize which keywords to target first

Important: Always combine MCP data with your own SEO expertise. The tools provide raw data — you provide the strategy, intent analysis, and content recommendations.

Output Quality Rules

• Generate REAL, SPECIFIC keywords - never use placeholders
• When seo-mcp is available: Use real Ahrefs data for volumes and difficulty. Mark data source clearly.
• When seo-mcp is NOT available: Estimate volumes and difficulty based on industry patterns:
  • Volume estimation: Broad terms (1K-10K/mo), Specific (100-1K/mo), Very specific (10-100/mo)
  • Difficulty estimation: Low (1-30) = newer/long-tail terms, Medium (31-60) = established, High (61-100) = brand/high-volume
  • Intent classification: Informational ("how to", "what is"), Commercial ("best", "top", "review"), Transactional ("buy", "pricing"), Navigational (brand terms)
• Tailor all recommendations to the site's niche and audience
• Be actionable - every recommendation should be immediately usable
• Use the project's primary keywords as context for related keyword discovery