--- name: ahrefs-keyword-rankings-report description: "Every Monday: how many tracked keywords rank in the Ahrefs top 10, which climbed or dropped since last week, and the pages behind the biggest moves. Use when the user asks for this, or when it runs on a schedule." --- # Ahrefs keyword rankings report Every Monday: how many tracked keywords rank in the Ahrefs top 10, which climbed or dropped since last week, and the pages behind the biggest moves. Rank Tracker exists so nobody has to search their own keywords by hand, yet the Monday routine is still to open it, sort by change and paste the interesting rows into a message. The report the team wants is short: how many keywords are on page one, which moved, and why. The agent reads the tracked project through the Ahrefs API, counts keywords by position bucket, lists the movers with their ranking URL, and points out when that URL changed, which often explains a sudden drop. It works for one project or several. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - An Ahrefs Rank Tracker project with the keywords you care about, and its project ID. - Ahrefs API v3 access with a key in `AHREFS_API_KEY`, or the official Ahrefs MCP server; Rank Tracker endpoints do not use API units. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Read the tracked keywords** (Ahrefs): Call the Ahrefs API v3 `rank-tracker/overview` for your `project_id`, with `date` set to today, `date_compared` to 7 days ago and `device=desktop` (again with `mobile` if you track both). Ask for each keyword's position on both dates, its search volume and the ranking URL. 2. **Count by position**: Bucket keywords into top 3, 4 to 10, 11 to 20, 21 to 50, 51 to 100 and not ranking. Keywords in the top 10 is the headline; the buckets show where the rest sit. 3. **Pick the movers**: A mover changed by 3 or more positions, or crossed into or out of the top 10. Sort by search volume, so a 5-place drop on a 9,000-volume keyword comes before a 20-place drop on one with 50. 4. **Look for URL swaps**: When the ranking URL differs between the two dates, say so. Google switching to another of your pages is a common cause of a sudden drop, and the fix is internal links or merging the two pages. 5. **Post the tile**: Keywords in the top 10 with 8 weeks of history. The glance shows climbers, drops and average position; the card opens to the buckets and the movers. ## Route B: the browser ### What you need - Signed in to Ahrefs with access to the Rank Tracker project, as owner or a workspace member it is shared with. If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://app.ahrefs.com/rank-tracker. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open the project**: Open `https://app.ahrefs.com/rank-tracker` and click the project for the site. The `Overview` tab opens with the latest update. 2. **Set the comparison**: In the compare picker at the top choose `7 days` (or the previous update, if the project refreshes weekly) and keep the device on `Desktop`. Read Visibility, Average position and the positions chart, which already buckets keywords into 1 to 3, 4 to 10, 11 to 20, 21 to 50 and 51 to 100. 3. **List the movers**: In the keywords table sort by `Change`, largest drops first then largest gains. For keywords that moved 3 or more positions, or crossed the top 10, note position, change, volume and the ranking URL. 4. **Spot URL swaps**: Where the URL column shows a different page than before (the previous URL appears on hover), say so: a swapped page explains most sudden drops. 5. **Repeat for mobile**: Switch the device to `Mobile` and repeat if the project tracks it. Keep the two separate in the report. Note: Positions update on the project's schedule, so the comparison is between two updates, not two calendar days. The keywords table pages at 100 rows; for projects with thousands of keywords, export the table and read the CSV. ## The report - **Keywords in the top 10** this week and the change, with an 8-week trend. - **Position buckets** for all tracked keywords. - **Climbers and drops**: keyword, position now and before, volume and the ranking URL. - **URL swaps**: keywords where Google now ranks a different page of yours. - The drop to look into first. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "ahrefs-keyword-rankings-report/", "item_key": "ahrefs-keyword-rankings-report", "project": "example.com", "source": "Ahrefs keyword rankings report skill", "kind": "metric", "title": "64 tracked keywords in the top 10, 3 more than last week", "metric": { "label": "Keywords in top 10", "value": 64, "better": "higher", "period_start": "", "period_end": "" }, "glance": { "type": "Grid", "props": { "columns": 3 }, "children": [ { "type": "Stat", "props": { "label": "Climbed", "value": 33, "tone": "ok" } }, { "type": "Stat", "props": { "label": "Dropped", "value": 19, "tone": "bad" } }, { "type": "Stat", "props": { "label": "Avg position", "value": 18.7, "delta": -4, "better": "lower" } } ] }, "widget": [ { "type": "Bars", "props": { "items": [ { "label": "Top 3", "value": 21 }, { "label": "4 to 10", "value": 43 }, { "label": "11 to 20", "value": 38 }, { "label": "21 to 50", "value": 41 }, { "label": "51 to 100", "value": 19 }, { "label": "Not ranking", "value": 18 } ] } }, { "type": "Table", "props": { "columns": [ "Keyword", "Now", "Before", "Volume", "Ranking URL" ], "align": [ "left", "right", "right", "right", "left" ], "rows": [ [ "invoice template", 3, 5, 9800, "/templates/invoice-pdf" ], [ "invoice software", 12, 7, 6100, "/blog/best-invoicing-software" ], [ "estimate template", 9, 4, 3600, "/templates/estimate" ], [ "invoicing software for small business", 8, 13, 2400, "/" ], [ "recurring invoices", 6, 11, 1300, "/features/recurring-invoices" ] ] } }, { "type": "Callout", "props": { "text": "\"invoice software\" fell from 7 to 12 after Google swapped the home page for /blog/best-invoicing-software. Link the post to the home page with that phrase.", "tone": "warn" } } ], "size": "md" } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters). ## Run it on a schedule Suggested: Mondays at 7:30 (`30 7 * * 1`). From cron, with the agent signed in on that machine: ```bash 30 7 * * 1 claude -p "Run the ahrefs-keyword-rankings-report skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/ahrefs-keyword-rankings-report#schedule Source: https://briefkin.dev/skills/ahrefs-keyword-rankings-report