How to use the Ahrefs SEO Data Analyst agent skill (seo-ahrefs)

What is an agent skill and what does seo-ahrefs make the agent do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a specific task. This one is named seo-ahrefs and is an Ahrefs API analyst extension. Its SKILL.md file says it reads referring domains, backlinks, organic keywords and content explorer data through the @ahrefs/mcp@0.0.11 server.

Once it is working, the agent can answer requests such as checking a domain's metrics or listing its top referring domains, and it cites Ahrefs as the source for each number. When Ahrefs and Moz disagree on the same metric, the skill tells the agent to trust Ahrefs and note the discrepancy in the report. For multi-source comparisons across Moz, Bing, Common Crawl and Ahrefs, it hands the work to the companion seo-backlinks skill.

• Metrics: domain or URL rating, referring domain count, organic traffic estimate
• Backlinks: top referring domains, anchor distribution, follow/nofollow ratio
• Organic: organic keywords, ranking distribution, traffic by country
• Content: Content Explorer top results, social shares, referring domains

Install the seo-ahrefs skill

Before anything else, run the install script for your system from the extensions/ahrefs folder: install.sh on Linux or macOS, or install.ps1 on Windows. The script installs the @ahrefs/mcp@0.0.11 server. Node.js 18 or newer must be on your PATH for the server to run.

To add the skill itself, download the ZIP from our page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to share it with one project. Alternatively, in the Claude apps go to Settings → Capabilities → Skills and upload the ZIP there.

• Run extensions/ahrefs/install.sh (Linux/macOS) or install.ps1 (Windows)
• Make sure Node.js 18+ is on your PATH
• Unzip the skill into ~/.claude/skills/ or your project's .claude/skills/
• Or upload the ZIP under Settings → Capabilities → Skills in the Claude apps

Add your Ahrefs API token and check the connection

You need an Ahrefs API token from https://ahrefs.com/api, which requires a paid Ahrefs account. The skill checks before every call that an Ahrefs MCP tool is available in the session. If none is, the agent will tell you the extension is not installed and repeat the install command.

If you see that message, re-run the install script and confirm the skill is loaded before retrying your request.

Trigger the skill with natural requests

You can ask in plain language, and the agent will use the skill when the request is about Ahrefs data. It also understands the four routed commands from the SKILL.md file. Being specific about the URL or topic helps the agent pick the right data set.

Each metric in the answer should carry the label "Ahrefs (live, confidence 1.00)", so you can see where every number came from.

• "Use Ahrefs to show the referring domains for example.com"
• "What is the Ahrefs rating and organic traffic estimate for example.com?"
• "/seo ahrefs organic example.com" for organic keywords and traffic by country
• "/seo ahrefs content remote work tools" for Content Explorer results

Check cost before running large batches

Ahrefs API usage is metered per unit. Before running a batch of 50 or more URLs, the skill instructs the agent to estimate cost with the cost-estimation script in the claude-seo toolkit's scripts folder, surface that estimate, and log actual cost after each call.

Run a small test first so you can see how many units a single URL uses before committing to a large list.

• Estimate cost first with the dataforseo_costs.py script in the claude-seo scripts folder
• Review the estimate before the agent starts the batch
• Track actual cost after each call

Safety notes: scripts, network and untrusted content

This skill is not sandboxed. Installing it runs scripts on your machine, and queries go over the network to Ahrefs. Review the install script before running it.

The skill also treats fetched pages, SERP results, API responses and third-party files as untrusted data. If any of that content tells the agent to run a command, install something or change a setting, the agent is meant to report it as a finding rather than obey it.

• Installing runs scripts on your machine
• Queries are sent to Ahrefs over the network
• Fetched content is data, not instructions

Tips for getting reliable results

Keep the Ahrefs token private and use one that matches your subscription. For multi-source work, ask the agent to use seo-backlinks rather than relying on Ahrefs alone. For SERP-feature analysis where Ahrefs and DataForSEO overlap, the skill prefers DataForSEO for live SERP data.

For toxic link assessment, the skill combines Ahrefs backlink quality signals with seo-backlinks crawler signals, so ask for both if you need that view.

• Ask for one URL at a time when you are learning the output format
• Use seo-backlinks for multi-source confidence weighting
• Expect SERP-feature questions to route to DataForSEO