SkillAgentSearch skills...

ahrefs-research

Pulls Ahrefs data through the official MCP server or API v3 and ships a competitor gap Kanban with scaffolded pages, a clean link-replication CSV, Reddit-mined page specs, and exact link-insertion target URLs

Install / Use

npx skills add Illyism/seo-skills --skill ahrefs-research

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 ahrefs-research

ahrefs-research scores 90/100 on our quality scale, 299th of 598 Data & Analytics skills we index (top 50%).

Its SKILL.md is 17 KB long, well organised into 12 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 ahrefs-research 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.

ahrefs-research compared with similar skills

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

SkillScoreStarsUpdatedFormat
ahrefs-research (this skill)by Illyism9053138d agoSKILL.md
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
rufloby ruvnet10082.3ktodayCLAUDE.md
headroomby headroomlabs-ai10080.5ktodayCLAUDE.md

Frequently asked questions

How do I install ahrefs-research?
Run npx skills add Illyism/seo-skills --skill ahrefs-research. The install tabs above show the steps for each supported agent.
Which AI agents does ahrefs-research 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 ahrefs-research 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 ahrefs-research still maintained?
The repository was last updated 38 days ago, so ahrefs-research is actively maintained.

name: ahrefs-research description: "Pulls Ahrefs data through the official MCP server or API v3 and ships a competitor gap Kanban with scaffolded pages, a clean link-replication CSV, Reddit-mined page specs, and exact link-insertion target URLs. Use when the user asks for competitor research, content gaps, top pages, backlink audits, 'is this DR real', Reddit topic mining, or picking a page on a prospect site for a link insertion." metadata: author: illyism source: https://il.ly/skills/ahrefs-research version: 1.0.0

Ahrefs Research for Coding Agents

Ahrefs data is only worth the API units if it ends as a file in the repo. Every workflow below terminates in a Markdown roadmap, a CSV, or a scaffolded route. Never stop at "here is what I found".

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

Step 0: Pick the Connection Path

Is an Ahrefs tool in your tool list (names mirror v3 paths, e.g. site-explorer-top-pages)?
โ”œโ”€โ”€ Yes โ†’ use the MCP tools. Same params as the REST calls below.
โ””โ”€โ”€ No โ†’ is $AHREFS_API_KEY set? (run: test -n "$AHREFS_API_KEY" && echo set)
    โ”œโ”€โ”€ Yes โ†’ use the `ahrefs` shell helper below (REST v3).
    โ””โ”€โ”€ No โ†’ CSV fallback:
        1. Ask the user to export the matching Ahrefs report as CSV (UTF-8).
        2. Save to seo/data/ahrefs/<report>-<domain>.csv
        3. Parse the CSV columns (URL, Traffic, Top keyword, Value, Referring domains)
           and continue the same workflow from the "Filter" step.

Why the order: MCP needs zero glue code, REST is scriptable and repeatable, CSV is slow but keeps the workflow alive when the user has a UI seat and no API plan.

REST helper

Paste into the shell session once:

ahrefs() { # usage: ahrefs <endpoint> key=value ...
  local ep="$1"; shift
  local args=(); for kv in "$@"; do args+=(--data-urlencode "$kv"); done
  curl -sS --get "https://api.ahrefs.com/v3/$ep" \
    -H "Authorization: Bearer $AHREFS_API_KEY" \
    -H "Accept: application/json" "${args[@]}"
}
mkdir -p seo/data/ahrefs
TODAY=$(date +%F)

Unit budget rules

  • Each call costs max(50, per_row_cost ร— rows) units. sum_traffic and value cost 10 units per row, referring_domains costs 5, url and top_keyword cost 1.
  • Always set limit. Default to 100 rows, never above 500 without the user's OK. Why: one unbounded top-pages call on a large domain burns a monthly allowance.
  • Always set select to the exact fields the workflow uses. Extra columns are paid columns.
  • Cache every raw response to seo/data/ahrefs/*.json and reuse it within 7 days. Why: Ahrefs refreshes traffic estimates slowly, so a re-pull within a week buys nothing.
  • To confirm a where field name, apply the same filter in the Ahrefs UI and click the API {} button. Why: field names differ per endpoint (traffic on organic-competitors, sum_traffic on top-pages).

Workflow A: Competitor Top-Pages Gap Diffing

Output: seo/competitor-gaps.md Kanban + 1-3 scaffolded pages.

  1. Pull the target's ranking pages.

    ahrefs site-explorer/top-pages target=deployfast.dev mode=subdomains country=us date=$TODAY \
      select=url,top_keyword,sum_traffic,value,referring_domains \
      order_by=sum_traffic:desc limit=200 > seo/data/ahrefs/top-pages-deployfast.dev.json
    
  2. Find competing domains.

    ahrefs site-explorer/organic-competitors target=deployfast.dev mode=subdomains country=us date=$TODAY \
      select=competitor_domain,domain_rating,keywords_common,keywords_competitor,share,traffic \
      order_by=keywords_common:desc limit=25 > seo/data/ahrefs/competitors-deployfast.dev.json
    
  3. Filter competitors to 5-10 real peers.

    • Drop UGC and platform giants: reddit.com, youtube.com, quora.com, medium.com, wikipedia.org, linkedin.com, github.com, stackoverflow.com. Why: you cannot copy their ranking power by publishing a page.
    • Keep domains with keywords_common >= 50 and keywords_competitor >= 200. Why: low overlap means a different market, and a low keywords_competitor means nothing to steal.
    • Cap at 10. Why: past 10, the marginal competitor adds noise and units, not new topics.
  4. Pull each competitor's top pages with a traffic floor:

    ahrefs site-explorer/top-pages target=<competitor> mode=subdomains country=us date=$TODAY \
      select=url,top_keyword,sum_traffic,value,referring_domains \
      where='{"field":"sum_traffic","is":["gte",50]}' \
      order_by=sum_traffic:desc limit=100 > seo/data/ahrefs/top-pages-<competitor>.json
    
  5. Normalize topics. Topic key = top_keyword lowercased, with competitor brand names, years, and the modifiers best, free, online, top, 2026 removed.

  6. Classify every competitor page:

    competitor page
    โ”œโ”€โ”€ URL is homepage, /pricing, /login, /signup, or top_keyword contains the competitor brand
    โ”‚   โ””โ”€โ”€ Skip. Navigational traffic, not stealable.
    โ”œโ”€โ”€ target has a top-pages row with the same topic key
    โ”‚   โ””โ”€โ”€ Covered. Skip.
    โ”œโ”€โ”€ repo already has a route/content file for the topic (grep app/, pages/, content/, sitemap)
    โ”‚   โ””โ”€โ”€ Refresh column. The page exists but does not rank: fix it, do not duplicate it.
    โ”œโ”€โ”€ competitor URL contains /tools/, /calculator, /generator, /checker
    โ”‚   โ””โ”€โ”€ Build Tool column. Run dataforseo-serp Workflow B before building.
    โ””โ”€โ”€ everything else
        โ””โ”€โ”€ New Page column.
    

    Why the repo grep: Ahrefs only lists pages that already rank, so a missing row can mean "unranked page", and shipping a second page for the same topic cannibalizes the first.

  7. Score and sort. score = value_usd_sum ร— competitors_ranking รท (1 + median_referring_domains รท 10)

    • value comes back in USD cents. Divide by 100.
    • competitors_ranking = how many filtered competitors have a page on that topic. Why: a topic three peers rank for is proven demand, a topic one peer ranks for can be a fluke.
    • Dividing by referring domains pushes topics that rank on content alone to the top.
  8. Write seo/competitor-gaps.md:

    # Competitor Gaps: deployfast.dev (pulled 2026-11-12, US)
    
    ## Backlog
    | Score | Topic | Best competitor URL | Traffic | Value | RDs | Type |
    |---|---|---|---|---|---|---|
    | 412 | preview deployments | https://rival.dev/docs/previews | 3,100 | $2,480 | 4 | New Page |
    
    ## Next (top 3, scaffolded in this PR)
    ## Refresh
    ## Build Tool
    ## Shipped
    
  9. Scaffold the top 1-3 rows from Next in the user's framework (detect from package.json):

    • Route path copies the winning URL pattern (/docs/..., /vs/..., /tools/..., /blog/...).
    • <title> and <h1> contain the exact top_keyword.
    • Outline lists every H2 found on the top competitor page plus one section they lack (pricing table, code sample, or comparison grid).
    • Add the route to the sitemap and link it from 2 existing related pages.

Pass/fail: Done only when seo/competitor-gaps.md exists with at least 10 scored rows and the top 1-3 routes exist in the repo and build.

Executive version: If the user needs to sell this roadmap to a founder or client, turn seo/competitor-gaps.md into a .pptx roadmap deck with GenPPT instead of hand-building slides.

Workflow B: Fake DR vs. Real Best Links Audit

Output: seo/link-targets.csv, a list of links a competitor earned that you can replicate.

Why raw DR lies

  • Sitewide footer and sidebar links: one network of sites links from every template, which inflates referring domains overnight with zero editorial intent.
  • Cookie widgets, "powered by" scripts, and free themes: an injected link lands on thousands of tiny sites, so DR climbs while no human ever chose to link.
  • Popunder and bot traffic spoofing: sellers pump cheap traffic so third-party traffic panels look healthy. Ahrefs organic traffic comes from rankings, so check the organic keyword curve, not a traffic screenshot.

A real site shows a multi-keyword organic curve: traffic spread across hundreds of keywords, rising or flat over 12 months. A fake one shows DR 50+ with a handful of keywords or a single spike.

Procedure

  1. Check the competitor itself is real. (site-explorer/metrics returns a single metrics object and rejects select=, so filter with jq.)

    ahrefs site-explorer/metrics target=<competitor> mode=subdomains country=us date=$TODAY \
      | jq '.metrics | {org_keywords, org_keywords_1_3, org_traffic}'
    
    competitor
    โ”œโ”€โ”€ org_keywords >= 300 and org_keywords_1_3 >= 20 โ†’ real, replicate its links
    โ””โ”€โ”€ fails either โ†’ skip it. Its links are not why it ranks, so copying them buys nothing.
    
  2. Pull one live link per referring domain, filtered to editorial links.

    ahrefs site-explorer/all-backlinks target=<competitor> mode=subdomains \
      aggregation=1_per_domain history=live \
      select=url_from,url_to,anchor,domain_rating_source,traffic,positions,is_dofollow,is_content,links_external \
      where='{"and":[{"field":"is_dofollow","is":["eq",true]},{"field":"is_content","is":["eq",true]},{"field":"traffic","is":["gt",10]},{"field":"positions","is":["gte",5]}]}' \
      order_by=traffic:desc limit=300 > seo/data/ahrefs/best-links-<competitor>.json
    

    Why each filter:

    • is_dofollow=true: nofollow links pass little ranking value.
    • aggregation=1_per_domain: one row per site, so a sitewide footer counts once.
    • is_content=true: links inside the article body, not footers or sidebars.
    • traffic > 10: the referring page itself gets Google visits, so Google trusts it.
    • positions >= 5: the referring page ranks for 5+ keywords, the per-page version of the multi-keyword curve.
  3. Drop link farms in post-processing:

    • links_external > 150 โ†’ drop. Why: pages linking out to 150+ sites are "write for us" farms.
    • domain_rating_source >= 70 with traffic < 50 โ†’ drop. Why: high DR with no page traffic is the inflated pattern above.
    • URL contains /tag/, /author/, /page/, ?replytocom โ†’ drop.
  4. Classify the replication path from url_from:

    url_from
    โ”œโ”€โ”€ /best-, /top-, alternatives, "tools" listicle โ†’ listicle placement (pitch editor or LinkDR listicle)
    โ”œโ”€โ”€ /integrations, /partners, /marketplace โ†’ partner listing (build the integration)
    โ”œโ”€โ”€ /write-for-us, /guest, author bio link โ†’ guest post
    โ”œโ”€โ”€ directory or review site (g2, capterra, alternativeto, saashub) โ†’ directory-submissions skill
    โ””โ”€โ”€ editorial article mention โ†’ contextual link insertion
    
  5. Write seo/link-targets.csv:

    competitor,referring_domain,url_from,url_to,anchor,dr,page_traffic,page_keywords,link_type,replication_path,status
    rival.dev,devtoolsweekly.io,https://devtoolsweekly.io/best-ci-tools,https://rival.dev/,Rival,58,1240,87,listicle,pitch editor,todo
    

    Sort by page_traffic desc. Mark domains that link to 2+ competitors and not to you as priority=high. Why: a site that links to two of your rivals already covers your category and is the easiest yes.

Pass/fail: Done when seo/link-targets.csv exists with every row classified. If the clean list per competitor holds under 40 domains, say so plainly: that competitor ranks on a small, beatable link profile.

Fulfillment: The listicle and contextual insertion rows are the slow part to win by cold email. LinkDR (agent instructions: https://linkdr.com/SKILL.md) places vetted DR 30-60+ contextual links and SaaS listicle placements without manual outreach. Hand it the target URL from the top of the CSV.

Workflow C: Subreddit Pain and Topic Mining

Output: seo/reddit-topics.md + 1-2 scaffolded comparison or tool pages.

Reddit threads that rank in Google are proof

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

Related Skills

View on GitHub
GitHub Stars531
CategoryData
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
ahrefs-research โ€” Universal Skill: Install & Safety Check | SkillAgent