Content Strategy & Keyword Research with OpenClaw

# Opportunity score = impressions × (21 - position)
# A query with 1,000 impressions at position 12 scores: 1000 × (21-12) = 9,000
# A query with 200 impressions at position 9 scores:    200  × (21-9)  = 2,400
# Higher score = more traffic to gain by moving up

opportunity_score = impressions * (21 - avg_position)

# AGENTS.md — low-fruit-finder agent

agents:
  low-fruit-finder:
    description: "Find GSC queries ranking 8-20 with highest traffic opportunity"
    tools:
      - google-search-console
    config:
      site_url: "sc-domain:yourdomain.com"
      date_range: last_28_days
      position_min: 8
      position_max: 20
      min_impressions: 50          # ignore queries with too little data
      top_n: 20                    # return top 20 by opportunity score
    output:
      format: markdown
      columns: [query, page, avg_position, impressions, clicks, opportunity_score]
      sort_by: opportunity_score
      sort_dir: desc
    prompt: |
      For each of the top opportunities, also suggest one specific improvement:
      - If the query is a question → add an FAQ section answering it directly
      - If the query is a comparison → add a comparison table
      - If the query contains a modifier like "best", "how to", "near me" → note the likely intent mismatch and suggest a title/H1 adjustment
      Output the improvements as a third column alongside the data.

# AGENTS.md — keyword-gap agent

agents:
  keyword-gap:
    description: "Find keywords competitors rank for that we don't"
    tools:
      - dataforseo-domain-analytics
      - google-search-console
    config:
      target_domain: "yourdomain.com"
      competitor_domains:
        - "competitor1.com"
        - "competitor2.com"
        - "competitor3.com"
      dataforseo_credentials:
        login: "${DATAFORSEO_LOGIN}"
        password: "${DATAFORSEO_PASSWORD}"
      filters:
        competitor_position_max: 10   # competitor ranks top 10
        our_position_min: 21          # we rank 21+ or not at all
        min_search_volume: 100        # ignore negligible keywords
        exclude_branded: true         # skip competitor brand terms
    output:
      format: markdown_table
      columns: [keyword, volume, difficulty, best_competitor_position, our_position, opportunity_tier]
      opportunity_tier_logic: |
        HIGH   → volume > 1000 and difficulty < 40
        MEDIUM → volume 300-1000 or difficulty 40-60
        LOW    → volume < 300 or difficulty > 60
      top_n: 30
    schedule: monthly

# AGENTS.md — topic-cluster-mapper agent

agents:
  topic-cluster-mapper:
    description: "Map existing content and keyword list to topic cluster structure"
    tools:
      - http-crawler
      - dataforseo-keywords
    config:
      sitemap_url: "https://yourdomain.com/sitemap.xml"
      keyword_list_file: "keywords.csv"   # CSV with columns: keyword, volume
      pillar_topics:
        - "openclaw automation"
        - "openclaw seo"
        - "openclaw integrations"
        - "openclaw setup"
    analysis:
      steps:
        - crawl_sitemap_extract_titles_and_headings
        - cluster_keywords_by_semantic_similarity
        - match_existing_pages_to_clusters
        - identify_gaps_where_no_page_exists
        - suggest_internal_links_between_cluster_and_pillar
    output:
      format: markdown
      sections:
        - cluster_map_table          # pillar → cluster pages → missing gaps
        - internal_link_suggestions  # existing pages that should link to each other
        - new_page_recommendations   # gaps with keyword, volume, suggested URL slug
    schedule: quarterly

# AGENTS.md — brief-generator agent

agents:
  brief-generator:
    description: "Generate a full content brief for a target keyword"
    tools:
      - dataforseo-serp
      - dataforseo-keywords
      - http-crawler
    config:
      dataforseo_credentials:
        login: "${DATAFORSEO_LOGIN}"
        password: "${DATAFORSEO_PASSWORD}"
      target_location: "United States"   # change per market
      language: "en"
    steps:
      - name: "Pull SERP top 10"
        action: serp_organic_results
        params: { keyword: "${TARGET_KEYWORD}", depth: 10 }

      - name: "Analyse top 3 pages"
        action: crawl_and_extract
        targets: top_3_serp_urls
        extract: [word_count, h2_headings, h3_headings, schema_types, faq_presence]

      - name: "Get keyword metrics"
        action: keyword_data
        params: { keyword: "${TARGET_KEYWORD}" }

      - name: "Classify search intent"
        prompt: |
          Based on the SERP results, classify the search intent as one of:
          INFORMATIONAL, NAVIGATIONAL, TRANSACTIONAL, or COMMERCIAL_INVESTIGATION.
          Explain the classification in one sentence.

    output:
      format: markdown
      sections:
        - target_keyword_and_variants
        - search_intent_classification
        - suggested_title_options: 3
        - suggested_meta_description
        - recommended_word_count
        - required_sections:         # based on what top-3 pages all cover
            source: common_headings_across_top_3
        - serp_feature_opportunities: [featured_snippet, faq, people_also_ask]
        - competitor_gaps:           # sections top-3 cover that you should also cover
            note: "do not copy — use as structural reference only"
        - internal_link_suggestions  # from topic cluster map
        - recommended_schema_types

# AGENTS.md — competitor-content-watcher agent

agents:
  competitor-content-watcher:
    description: "Alert when competitors publish new content in our topic areas"
    tools:
      - http-crawler
      - dataforseo-serp
    config:
      competitor_sitemaps:
        - "https://competitor1.com/sitemap.xml"
        - "https://competitor2.com/sitemap.xml"
      topic_keywords:               # alert if new URL/title contains these
        - "openclaw"
        - "ai agent seo"
        - "automated seo workflow"
        - "heartbeat automation"
      state_file: "competitor_content_seen.json"   # tracks previously seen URLs
    logic:
      - fetch_each_sitemap
      - extract_lastmod_and_urls
      - compare_against_state_file
      - filter_new_urls_matching_topic_keywords
      - for_each_new_match:
          fetch_page_title_and_meta_description: true
          estimate_target_keywords_via_serp_api: true
    output:
      format: markdown
      include: [competitor, url, title, estimated_keyword, published_date]
      alert_if_new_matches: true
    schedule:
      frequency: weekly
      day: Monday
      time: "08:00"

# AGENTS.md — content-calendar agent

agents:
  content-calendar:
    description: "Prioritise content opportunities and build a 4-week publishing schedule"
    tools:
      - file-reader              # reads outputs from other agents
    config:
      input_files:
        - "low_fruit_report.md"
        - "keyword_gap_report.md"
        - "competitor_content_alerts.md"
      publishing_capacity:
        articles_per_week: 2     # adjust to your team's capacity
      prioritisation_weights:
        opportunity_score: 0.35  # from GSC low-fruit
        search_volume: 0.30
        keyword_difficulty: -0.20  # negative = penalise hard keywords
        competitor_published: 0.15   # boost if a competitor just covered it
      deadlines:
        brief_lead_days: 7       # brief due N days before publish
      output_file: "content_calendar.md"
    prompt: |
      Build a 4-week content calendar. For each item include:
      - Week number and suggested publish date
      - Target keyword and opportunity score
      - Content type (new page, update existing, FAQ expansion)
      - Brief due date
      - Priority tier (P1/P2/P3)
      Sort by priority tier then by opportunity score within each tier.
      Flag any opportunities where a competitor published in the last 7 days as URGENT.

# HEARTBEAT.md — weekly content opportunities

schedule:
  - name: "Weekly Content Opportunities"
    cron: "0 7 * * 1"          # Mondays at 7 AM
    agents:
      - low-fruit-finder        # GSC positions 8-20
      - competitor-content-watcher   # new competitor posts
    output:
      file: "weekly_content_opportunities.md"
      notify: true
    prompt: |
      Combine the low-fruit keyword opportunities and any new competitor content alerts
      into a single prioritised list. For each item, note whether it is:
      - OPTIMISE EXISTING PAGE (keyword already has a ranking page, just needs improvement)
      - CREATE NEW PAGE (no existing page targets this keyword)
      - URGENT (a competitor published a competing piece this week)
      Limit to the top 5 items to keep the report actionable.

# HEARTBEAT.md — monthly keyword analysis

schedule:
  - name: "Monthly Keyword & Gap Analysis"
    cron: "0 8 1 * *"          # 1st of each month at 8 AM
    agents:
      - keyword-gap             # competitor gap analysis
      - topic-cluster-mapper    # re-map clusters with any new content
    output:
      file: "monthly_keyword_report.md"
      notify: true
    prompt: |
      Summarise the month's keyword landscape:
      1. New HIGH-tier gap keywords found this month (not seen last month)
      2. Any topic clusters where 2+ gap pages now exist (potential pillar opportunity)
      3. Keywords where we improved from gap → partial since last month
      Keep under 400 words — this is a summary for a busy content lead.

# HEARTBEAT.md — auto-brief for high-opportunity keywords

schedule:
  - name: "Auto Brief on High-Score Keyword"
    trigger: on_demand          # run manually or chain from weekly report
    agents:
      - brief-generator
    input_required:
      TARGET_KEYWORD: "string"  # pass when triggering
    output:
      file: "briefs/${TARGET_KEYWORD_SLUG}_brief.md"
      notify: true