Chase down new Semrush Site Audit errors after every crawl

SKILL.md---
name: semrush-site-audit-errors
description: "After each weekly Semrush crawl, the errors that are new since the last one, the pages affected, and a question: send them to the developers?. Use when the user asks for this, or when it runs on a schedule."
---

# Semrush site audit errors

After each weekly Semrush crawl, the errors that are new since the last one, the pages affected, and a question: send them to the developers?

A Site Audit report with 140 errors is not a to-do list; most of them were there last month and the month before. What matters after a crawl is the difference: the broken links a content update just introduced, the pages that started returning 5xx, the duplicate titles from a new template.

The agent reads the latest snapshot and the one before through the Semrush API, keeps only errors that are new or growing, and asks whether to hand them to the developers with example URLs attached. Warnings and notices stay out unless one of them jumps.

## 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

- A Semrush Site Audit project for the site, crawling on a weekly schedule, and its project ID.
- Semrush API access with the key in `SEMRUSH_API_KEY`; the Projects API needs a Business subscription and API units. The official Semrush MCP server does not list Site Audit, so use the API unless yours exposes it.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **Find the last two crawls** (Semrush): Call the Site Audit API `GET /reports/v1/projects/{project_id}/siteaudit/snapshots` and take the two most recent snapshot IDs. `siteaudit/info` gives the Site Health score and error counts for the latest crawl.
2. **Compare the issues** (Semrush): Read each snapshot with `siteaudit/snapshot?snapshot_id=<id>` and match issues by ID, with titles from `siteaudit/meta/issues`. An error is new when its count went from zero to anything, and growing when it rose by 20% or more.
3. **Get example pages** (Semrush): For each new or growing error, request its pages from the snapshot's issue report (`siteaudit/snapshot/{snapshot_id}/issue/{issue_id}`) and keep up to 5 URLs with the detail, such as the broken link target or the status code.
4. **Sort by who fixes it**: Server errors, redirect chains, broken internal links and blocked resources go to developers; duplicate titles, missing descriptions and thin pages go to content. Developer issues come first, since one template bug can touch hundreds of pages.
5. **Ask what to do**: Post an action card with the new errors, their counts and example URLs, and ask whether to draft a ticket. A warning or notice only appears if its count doubled.

## Route B: the browser

### What you need

- Signed in to Semrush with access to the Site Audit project; a shared project with view rights is enough.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://www.semrush.com/siteaudit/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Open the latest crawl**: Open `https://www.semrush.com/siteaudit/` and click the project for `example.com`. On the `Overview` tab read `Site Health`, the error count and the number of crawled pages, with the crawl date.
2. **Compare with the crawl before**: Open the `Compare Crawls` tab, set the latest crawl against the previous one, and read the Site Health and error counts for both plus the new and fixed issue counts.
3. **List new and growing errors**: On the `Issues` tab filter to `Errors`. Issues marked new since the last crawl, and those whose count rose by 20% or more, are the list; ignore warnings and notices unless one doubled.
4. **Collect example URLs**: Click the page count next to each issue to open its pages and copy up to 5 URLs with the detail (status code, broken link target). `Why and how to fix it` gives the one-line explanation.
5. **Sort by owner and ask**: Put server errors, redirect chains, broken internal links and blocked resources under developers, and titles, descriptions and thin pages under content. Then ask whether to draft a ticket.

Note: Compare Crawls needs at least two crawls in the project, and Semrush keeps a limited number of past crawls. Issue page lists paginate; use the Export button on an issue when it touches hundreds of URLs.

## The report

- **Site Health** score now and after the previous crawl.
- **New and growing errors**: issue, pages affected, change since the last crawl.
- **Example URLs** for each, with the detail (status code, broken link target).
- **Who fixes what**: developer issues first, then content issues.
- The ask: draft a ticket, fix it yourself, recrawl, or leave it.

## 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": "semrush-site-audit-errors/<date of this run, e.g. 2026-10-16>",
  "item_key": "semrush-site-audit-errors",
  "project": "example.com",
  "source": "Semrush site audit errors skill",
  "kind": "action",
  "title": "12 new crawl errors since last week",
  "summary": "Tuesday's crawl found **12 new errors** across 3 issues, and Site Health fell from 91% to 87%. All three 5xx pages sit under /integrations/, so one template is the likely cause.",
  "action": {
    "request": "7 broken internal links, 3 pages returning 5xx and 2 duplicate title tags are new since last week. Shall I draft a ticket for the developers with the example URLs?",
    "options": [
      "Draft the ticket",
      "I'll fix them",
      "Recrawl first",
      "Leave them"
    ]
  },
  "widget": [
    {
      "type": "Table",
      "props": {
        "columns": [
          "Issue",
          "Pages",
          "Example"
        ],
        "align": [
          "left",
          "right",
          "left"
        ],
        "rows": [
          [
            "Broken internal links",
            7,
            "/blog/invoice-vs-bill → /guides/old-vat-rules (404)"
          ],
          [
            "5xx errors",
            3,
            "/integrations/xero (502)"
          ],
          [
            "Duplicate title tags",
            2,
            "/templates/estimate, /templates/quote"
          ]
        ]
      }
    },
    {
      "type": "Badges",
      "props": {
        "items": [
          {
            "label": "Site Health 87%",
            "tone": "warn"
          },
          {
            "label": "For developers: 10",
            "tone": "bad"
          },
          {
            "label": "For content: 2",
            "tone": "info"
          }
        ]
      }
    }
  ]
}
JSON
```

Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.

## Run it on a schedule

Suggested: Wednesdays at 8:00 (`0 8 * * 3`). From cron, with the agent signed in on that machine:

```bash
0 8 * * 3 claude -p "Run the semrush-site-audit-errors 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/semrush-site-audit-errors#schedule

Source: https://briefkin.dev/skills/semrush-site-audit-errors