seo-site-audit-pro

Site Audit Pro — Sequential Wave Multi-MCP Audit

Flagship audit combining Ahrefs and GSC data across 3 sequential waves with checkpoint saves to disk. Designed to be resilient to rate-limit errors — each tool call is independent, skipped tools are logged, and the audit always completes.

LOCKED DECISION (GitHub Issue #6594): Sequential wave execution only. Do NOT parallelize tool calls. Do NOT spawn subagents. All tool calls are inline.

References

@skills/seo/references/mcp-degradation.md @skills/seo/references/ahrefs-api-reference.md @skills/seo/references/gsc-api-reference.md

Inputs

• domain: Bare domain to audit (required). Example: example.com. Strip https://, http://, and trailing slashes before use.
• site (optional): GSC property URL to include GSC data in the audit. Example: https://example.com or sc-domain:example.com. If not provided, audit runs Ahrefs-only.

Important: API Usage Warning

Before starting execution, display this notice to the user:

API Usage Notice: This command calls approximately 10–12 Ahrefs API tools

sequentially. Each call consumes API units from your Ahrefs account. You can

stop after any wave if budget is a concern. Estimated time: 3 waves × 1–2

minutes each = 3–6 minutes total. Wave breakdown:

- Wave 1: Domain Authority and Backlink Health (4 tool calls)

- Wave 2: Keyword and Competitive Position (3–4 tool calls)

- Wave 3: Content and Technical Insights (3–4 tool calls)

MCP Check

Before proceeding, verify MCP availability:

Ahrefs (required):

1. Use ToolSearch with query +ahrefs
2. If tools returned → Ahrefs MCP available, proceed
3. If no tools returned → display the Ahrefs error template (see Error section below) and stop

GSC (optional — only relevant if site param was provided):

1. Use ToolSearch with query +google-search-console
2. If tools returned → note "GSC MCP available — will include GSC overlay in Waves 2 and 3"
3. If no tools returned AND site param was provided → note "GSC MCP unavailable — audit will use Ahrefs data only, GSC overlay skipped" and continue
4. If site param was NOT provided → skip GSC check entirely

Architecture

This command uses SEQUENTIAL wave execution with checkpoint saves between waves.

Critical design rules:

• Each tool call runs ONE AT A TIME — never in parallel
• Results from each tool are stored before proceeding to the next
• After each wave completes, all results are written to a checkpoint file on disk
• If a tool returns a rate-limit error or any error: log as SKIPPED: {tool-name} — {reason} and continue to the next tool immediately
• A failed tool call NEVER stops the wave or the audit
• The final report lists all skipped data sources so the user knows what's missing

This pattern prevents cascade failures from shared AbortController state (GitHub Issue #6594).

Execution

Step 0 — Initialize Checkpoint File

Use Bash to resolve the absolute path for the checkpoint file:

echo "$(pwd)/seo-audit-pro-checkpoint-{domain}.md"

Use the Write tool to create the initial checkpoint file at that path:

# Site Audit Pro: {domain}
**Started:** {current date and time}
**Status:** In progress
**Waves:** 0 of 3 complete

---

Tell the user: "Checkpoint file created. Starting Wave 1..."

Wave 1 — Domain Authority and Backlink Health

Run each tool call sequentially. For each: if success → store result. If error of any kind → log SKIPPED: {tool-name} — {error reason} and immediately move to the next tool. NEVER stop the wave because one tool failed.

Tool call 1a — Site Metrics: Call mcp__claude_ai_ahrefs__site-explorer-metrics with:

• target: {domain}

Returns: organic_traffic, traffic_cost (CENTS — divide by 100 for USD), organic_keywords, backlinks, referring_domains

Store result as Wave1_Metrics. If error: log SKIPPED: site-explorer-metrics — {reason}

Tool call 1b — Domain Rating: Call mcp__claude_ai_ahrefs__site-explorer-domain-rating with:

• target: {domain}

Returns: domain_rating (0–100), ahrefs_rank

Store result as Wave1_DR. If error: log SKIPPED: site-explorer-domain-rating — {reason}

Tool call 1c — All Backlinks (top 20): Call mcp__claude_ai_ahrefs__site-explorer-all-backlinks with:

• target: {domain}
• Limit/top results to 20

Returns: list of backlinks with source domain, anchor text, DR, link type

Store result as Wave1_Backlinks. If error: log SKIPPED: site-explorer-all-backlinks — {reason}

Tool call 1d — Broken Backlinks: Call mcp__claude_ai_ahrefs__site-explorer-broken-backlinks with:

• target: {domain}

Returns: backlinks pointing to 404/broken pages on the domain

Store result as Wave1_BrokenLinks. If error: log SKIPPED: site-explorer-broken-backlinks — {reason}

Wave 1 Checkpoint Save: Use the Write tool to APPEND Wave 1 results to the checkpoint file:

## Wave 1 Results — Domain Authority and Backlink Health
**Completed:** {timestamp}

### Metrics
{Wave1_Metrics data or "SKIPPED: {reason}"}

### Domain Rating
{Wave1_DR data or "SKIPPED: {reason}"}

### Top Backlinks (up to 20)
{Wave1_Backlinks data or "SKIPPED: {reason}"}

### Broken Backlinks
{Wave1_BrokenLinks data or "SKIPPED: {reason}"}

---

Tell the user: "Wave 1 complete (Domain Authority & Backlinks). Checkpoint saved. Starting Wave 2..."

Wave 2 — Keyword and Competitive Position

Tool call 2a — Organic Keywords (top 20): Call mcp__claude_ai_ahrefs__site-explorer-organic-keywords with:

• target: {domain}
• Limit to top 20 results

Returns: list of keywords with position, volume, traffic, difficulty

Store result as Wave2_Keywords. If error: log SKIPPED: site-explorer-organic-keywords — {reason}

Tool call 2b — Organic Competitors: Call mcp__claude_ai_ahrefs__site-explorer-organic-competitors with:

• target: {domain}

Returns: list of competing domains with overlap score, common keywords, their traffic

Store result as Wave2_Competitors. If error: log SKIPPED: site-explorer-organic-competitors — {reason}

Tool call 2c — Content Gap via Keywords Explorer: Using the top competitor identified from Wave2_Competitors (or skip if Wave2_Competitors was skipped):

First, use ToolSearch with query keywords-explorer-matching-terms to discover the exact parameter schema for this tool. Do NOT assume parameter names.

Then call mcp__claude_ai_ahrefs__keywords-explorer-matching-terms using the competitor domain as the seed to find content gap keywords.

Store result as Wave2_ContentGap. If error: log SKIPPED: keywords-explorer-matching-terms — {reason}

Tool call 2d — GSC Query Analytics (only if site param provided AND GSC MCP available): If GSC is available and site param was given: Call the GSC query_search_analytics tool (use ToolSearch "+google-search-console" to find the exact tool name first) with:

• Site/property: {site}
• Row limit: 20
• Dimensions: query
• Sort by: clicks descending

Returns: top queries by clicks with impressions, CTR, average position

Note: CTR is returned as a decimal (e.g., 0.0523). Multiply by 100 for display (5.23%).

Store result as Wave2_GSC. If error or GSC unavailable: log SKIPPED: GSC query_search_analytics — {reason}

Wave 2 Checkpoint Save: Use the Write tool to APPEND Wave 2 results to the checkpoint file:

## Wave 2 Results — Keyword and Competitive Position
**Completed:** {timestamp}

### Organic Keywords (top 20)
{Wave2_Keywords data or "SKIPPED: {reason}"}

### Organic Competitors
{Wave2_Competitors data or "SKIPPED: {reason}"}

### Content Gap (keywords competitor ranks for, you don't)
{Wave2_ContentGap data or "SKIPPED: {reason}"}

### GSC Query Analytics (top queries by clicks)
{Wave2_GSC data or "SKIPPED: not requested or GSC unavailable"}

---

Tell the user: "Wave 2 complete (Keywords & Competition). Checkpoint saved. Starting Wave 3..."

Wave 3 — Content and Technical Insights

**Tool call 3a — GSC