SkillAgentSearch skills...

dataforseo-serp

Pulls live Google SERPs, keyword volume and CPC, AI Overview references, and LLM answer citations from DataForSEO (MCP or REST v3) and ships keyword-clusters.json, a content map, tool build specs with a scaffolded route, citation-gap actions, and per-page intent locks

Install / Use

npx skills add Illyism/seo-skills --skill dataforseo-serp

Installs into whichever agent you are using.

About this skill
πŸ“„

SKILL.md

Installable skill definition

Quality Score

90/100

Supported Platforms

Universal

Our assessment of dataforseo-serp

dataforseo-serp scores 90/100 on our quality scale, 383rd of 950 AI & Machine Learning skills we index (top 41%).

Its SKILL.md is 16 KB long, well organised into 14 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.

It has 531 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
18/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 38 days ago, so dataforseo-serp is actively maintained.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit β€” read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.

Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk β€” read a skill before letting an agent act on it.

dataforseo-serp compared with similar skills

All 4 of these similar skills score higher than dataforseo-serp; compare them before choosing.

SkillScoreStarsUpdatedFormat
dataforseo-serp (this skill)by Illyism9053138d agoSKILL.md
claude-memby thedotmack100119.0ktodayCLAUDE.md
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
Understand-Anythingby Egonex-AI10093.7ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md

Frequently asked questions

How do I install dataforseo-serp?
Run npx skills add Illyism/seo-skills --skill dataforseo-serp. The install tabs above show the steps for each supported agent.
Which AI agents does dataforseo-serp work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is dataforseo-serp safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is dataforseo-serp still maintained?
The repository was last updated 38 days ago, so dataforseo-serp is actively maintained.

name: dataforseo-serp description: Pulls live Google SERPs, keyword volume and CPC, AI Overview references, and LLM answer citations from DataForSEO (MCP or REST v3) and ships keyword-clusters.json, a content map, tool build specs with a scaffolded route, citation-gap actions, and per-page intent locks. Use when the user asks to cluster keywords, check what ranks, avoid cannibalization, pick a free tool to build, find who AI Overviews or ChatGPT cite, or decide what format a page must take before writing it. metadata: author: illyism source: https://il.ly/skills/dataforseo-serp version: 1.0.0

DataForSEO SERP Workflows

The live SERP is the only ground truth for what Google wants on a query. Embeddings, keyword tools, and gut feel guess at intent. The Top-10 URLs show it. Every workflow below reads the SERP first and ends in a file or a route in the user's repo.

When invoking: On first use, state the connection path and the workflow, then run it. On repeat use, go straight to the output.

Step 0: Pick the Connection Path

Are DataForSEO tools in your tool list (serp, keywords_data, ai_optimization)?
β”œβ”€β”€ Yes β†’ use the MCP tools with the same payloads as the REST calls below.
└── No β†’ are $DATAFORSEO_LOGIN and $DATAFORSEO_PASSWORD set?
    β”œβ”€β”€ Yes β†’ use the `dfs` shell helper below (REST v3, Basic Auth).
    └── No β†’ how many queries?
        β”œβ”€β”€ < 10 β†’ live web search fallback. Record the Top-10 URLs per query by hand,
        β”‚          tag every row source=websearch, and skip CPC-based filters.
        └── >= 10 β†’ stop and ask for DataForSEO credentials.

Why the 10-query cap: web search results are personalized and unstable, which is fine for a spot check and wrong for clustering a keyword list where one bad SERP merges two clusters.

REST helper

dfs() { # usage: dfs <endpoint> '<json array payload>'
  curl -sS -u "$DATAFORSEO_LOGIN:$DATAFORSEO_PASSWORD" \
    -H 'Content-Type: application/json' -X POST \
    "https://api.dataforseo.com/v3/$1" -d "$2"
}
mkdir -p seo/data/serp

Rules for every call

  • Check both .status_code == 20000 and .tasks[0].status_code == 20000. Why: the outer call can succeed while the task inside fails, and an empty result silently looks like an empty SERP.
  • Guard against Google Poisoned SERPs (post-Sept 2026 anti-scraper defense): Flagged datacenter routes can still return HTTP 200 / status_code == 20000 with ~95 organic rows while completely suppressing exact brand/entity domains, scrambling website_name across unrelated sites, or returning 0/10 domain overlap against the true Page 1 (and wrapping outbound URLs in google.com/goto). On brand or navigational queries, verify the expected canonical domain appears in the Top 10; on commercial queries, spot-check that at least 2 of the Top-3 titles/URLs match the query intent and unwrap any google.com/goto hrefs before clustering. If a DataForSEO Live SERP fails that sanity check, retry once or fall back to linkdr_get_keyword_serp (https://linkdr.com/mcp) or live web search before locking page intent.
  • Send one task per Live call and loop over keywords with 5-10 parallel requests. Why: Live endpoints return the result in the same response, so batching gains nothing and one bad keyword fails the batch.
  • Default location_code: 2840 (United States), language_code: "en", device: "desktop", depth: 10. Change location only when the user sells into another market.
  • Save every raw response to seo/data/serp/<slug>.json. Read .tasks[0].cost and keep a running total. Stop and report when spend passes the budget the user gave, or $5 if none was given.

Workflow A: SERP URL-Overlap Keyword Clustering (Anti-Cannibalization)

Output: seo/keyword-clusters.json + seo/content-map.md.

Why semantic clustering cannibalizes

An LLM or embedding model groups keywords by shared words. Google groups them by shared intent. "invoice template" and "invoice generator" share a word and get merged by an LLM, but Google serves downloadable templates for one and interactive tools for the other, so a merged page fights two intents and wins neither. The reverse also happens: "invoicing software for freelancers" and "freelance billing app" share no words, get split into two pages, then compete for the same Top-10 because Google treats them as one intent. Shared ranking URLs are the only signal that matches how Google groups queries.

Procedure

  1. Fetch the Top-10 for each seed keyword:

    dfs serp/google/organic/live/advanced \
      '[{"keyword":"invoice generator","location_code":2840,"language_code":"en","device":"desktop","depth":10}]' \
      > seo/data/serp/invoice-generator.json
    
    jq -r '.tasks[0].result[0].items[] | select(.type=="organic") | .url' seo/data/serp/invoice-generator.json
    
  2. Normalize URLs: lowercase host, drop www., drop query strings and # fragments, drop trailing /. Why: https://www.invoicekit.io/x/ and https://invoicekit.io/x are the same result and must count as a shared URL.

  3. Sort keywords by search volume desc (pull volume from Workflow B's call if not supplied).

  4. Greedy cluster against the cluster head, never against any member:

    for each keyword K (highest volume first):
      compare K's Top-10 to the head keyword of every existing cluster
      β”œβ”€β”€ shared URLs >= 3 β†’ add K to that cluster. One single page targets both.
      β”œβ”€β”€ shared URLs == 2 β†’ inspect dominant page type of both SERPs:
      β”‚   β”œβ”€β”€ same dominant type (tool/tool, listicle/listicle, docs/docs) β†’ add to cluster
      β”‚   └── different dominant type β†’ new cluster, separate page
      └── shared URLs 0-1 β†’ new cluster with K as head. Build a separate page.
    

    Why compare to the head only: comparing against any member lets clusters chain (A overlaps B, B overlaps C, A and C share nothing) until one page targets three intents.

  5. Classify page type per URL for the 2-URL tiebreak:

    • tool: URL or title has generator|calculator|checker|converter|maker|tool|free online
    • listicle: title starts with a number, or has best|top|alternatives
    • docs: path has /docs/|/help/|/support/|/api/
    • forum: domain is reddit.com, quora.com, stackoverflow.com
    • product: path is / or /pricing or /features/...
    • blog: everything else
  6. Write seo/keyword-clusters.json:

    [
      {
        "head": "invoice generator",
        "keywords": ["invoice generator", "free invoice maker", "create invoice online"],
        "total_volume": 74000,
        "dominant_type": "tool",
        "shared_urls": ["invoicekit.io/tools/invoice-generator", "billstack.io/invoice-generator"],
        "target_url": "/tools/invoice-generator",
        "existing_page": null
      }
    ]
    
  7. Map clusters to existing pages. Grep the repo routes and sitemap. If two existing pages target keywords from one cluster, flag a merge with a 301 from the weaker page. If one existing page targets keywords from two clusters, flag a split.

  8. Write seo/content-map.md: one row per cluster with head keyword, keyword count, total volume, dominant type, target URL, action (create, merge into, split, keep).

Pass/fail: Every seed keyword sits in exactly one cluster. No two clusters point at the same target_url. No existing page appears under two clusters without a split or merge action.

Workflow B: Traffic-Value Free-Tool Filter

Output: seo/tool-specs.md + the top tool route scaffolded.

Why volume alone lies

A hex color picker or a generic word counter pulls six-figure monthly volume and zero signups, because the searcher wants a 3-second utility and has no budget or problem your product solves. CPC is advertisers voting with money on which queries convert. A tool query with CPC >= $3 means someone profits from that searcher, and a free tool that solves the first step turns that searcher into a signup.

Procedure

  1. Pull volume and CPC:

    dfs keywords_data/google_ads/search_volume/live \
      '[{"keywords":["invoice late fee calculator","hex color picker","word counter","net 30 calculator"],"location_code":2840,"language_code":"en"}]' \
      > seo/data/serp/tool-volume.json
    
    jq -r '.tasks[0].result[] | [.keyword, .search_volume, .cpc] | @tsv' seo/data/serp/tool-volume.json
    
  2. Compute traffic_value = cpc Γ— search_volume per keyword.

  3. Filter:

    tool keyword
    β”œβ”€β”€ cpc >= 3 and volume >= 300 β†’ BUILD candidate
    β”œβ”€β”€ cpc < 0.5 β†’ REJECT regardless of volume. Vanity traffic.
    β”œβ”€β”€ 0.5 <= cpc < 3
    β”‚   β”œβ”€β”€ the tool's output feeds the product's core action (calculator result β†’ invoice) β†’ BUILD candidate
    β”‚   └── otherwise β†’ REJECT
    └── volume < 300 β†’ REJECT unless cpc >= 15 (high-ticket B2B)
    
  4. Confirm the SERP wants a tool: run Workflow D on each BUILD candidate. If fewer than 3 of the Top-5 are interactive tools, downgrade it to a guide. Why: building a tool for a SERP full of articles wastes a sprint on a format Google does not rank there.

  5. Rank by traffic_value desc and write seo/tool-specs.md, one block per tool:

    ## Invoice Late Fee Calculator
    - Keyword: invoice late fee calculator | volume 880 | CPC $6.10 | value $5,368/mo
    - Route: /tools/late-fee-calculator
    - Inputs: invoice amount, days overdue, annual rate or flat fee
    - Output: fee owed, total due, copy-ready reminder text
    - Conversion hook: "Add this fee to an invoice" button β†’ signup with amount prefilled
    - SERP format: 4 of Top-5 are calculators, median 350 words below the tool
    
  6. Scaffold the #1 tool route in the user's framework:

    • Server-rendered H1, intro, and explainer text so crawlers see content without running JS.
    • Interactive part as a client component that computes in the browser with no login.
    • CTA carries the result into signup (query param or local storage) so the user lands with their work saved.
    • Add to sitemap, link from homepage footer or /tools hub and 2 related pages.

Pass/fail: seo/tool-specs.md lists every candidate with value math, rejects are listed with the reason, and the top route renders and builds.

Workflow C: AI Overview and LLM Citation Source Extraction

Output: seo/citation-gaps.md with one immediate action per cited source.

AI answers quote a small set of third-party pages. If the user is not on those pages, the AI answer never names them. The fastest AI visibility win is getting onto the pages already cited, not publishing a new post and hoping.

  1. Pull Google AI Overview references (load_async_ai_overview costs extra and catches overviews that load after the page):

    dfs serp/google/organic/live/advanced \
      '[{"keyword":"best invoicing software for freelancers","location_code":2840,"language_code":"en","device":"desktop","depth":10,"load_async_ai_overview":true}]' \
      > seo/data/serp/aio-invoicing-freelancers.json
    
    jq -r '.tasks[0].result[0].items[] | select(.type=="ai_overview")
      | [.references[]?, (.items[]?.references[]?)] | .[]
      | [.domain, .url, .title] | @tsv' seo/data/serp/aio-invoicing-freelancers.json | sort -u
    

    No ai_overview item means Google showed no overview for that query in that location. Record none and move on.

  2. Pull LLM answer citations with web search on:

    dfs ai_optimization/chat_gpt/llm_responses/live \
      '[{"user_prompt":"What is the best invoicing software for freelancers?","model_name":"gpt-4.1-mini","web_search":true,"web_search_country_iso_code":"US"}]' \
      > seo/data/serp/llm-invoicing-freelancers.json
    
    jq -r '.tasks[0].result[0] | [(.items[]? | select(.type=="message") | .sections[]?.annotations[]?), .search_results[]?] | .[] | select(.url != null) | [.title, .url] | @tsv' \
      seo/data/serp/llm-invoicing-freelancers.json | sort -u
    

    A 10-prompt batch

Truncated for display β€” read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars531
CategoryAI
Updated1mo ago
Forks56

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit β€” see the Safety scan above for what the skill file itself contains.

1 medium
dataforseo-serp β€” Universal Skill: Install & Safety Check | SkillAgent