# SEO Audit

> Diagnoses why a page underperforms in traditional Google and Bing results. TRIGGER WHEN: the user asks for a technical SEO audit, Core Web Vitals check, sitemap, redirect, or crawlability review, structured data or meta tags, mobile usability, or SERP ranking analysis. DO NOT TRIGGER WHEN: the goal is being cited by AI answer engines (use /digital-marketing:llm-seo-audit), conversion, CTA, or copy quality (use /digital-marketing:content-strategy), or GA4 tracking (use ga4-implementation-expert).

- Skill: `acaprino/seo-audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/seo-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/seo-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/seo-audit

---


> Arguments: `<url or local path> [--focus <comma-separated category names>] [--local] [--strict-mode]`. Wherever `<arguments>` appears below, substitute the text the user typed after the skill name.

<!-- Generated by the Daodan compiler for codex. Edit the kernel, never this file. -->

# SEO Audit

## CRITICAL RULES

1. **Execute phases in order.** Discovery → Audit → Score → (Approval) → Fix → Report.
2. **Write output files.** Each phase writes to `.seo-audit/` for persistence.
3. **Stop at checkpoint.** Get user approval before applying any fixes (Phase 4).
4. **Use Playwright for live sites.** Browser tools for DOM, console, network, responsive testing.
5. **Never enter plan mode.** Execute immediately.

## Pre-flight

### Dependency check (live sites only)

For live URL targets (not `--local`), this command uses Playwright MCP tools for browser-based analysis. If Playwright MCP tools (`browser_navigate`, `browser_snapshot`, etc.) are not available, warn the user:

```
Missing required plugin: playwright-skill

Live site analysis needs Playwright MCP tools for DOM inspection,
responsive testing, and network analysis. Without it, analysis will be
limited to what can be fetched via WebFetch/curl.

playwright-skill is a declared dependency of digital-marketing, distributed
by its own upstream marketplace. Install it with:
  claude plugin marketplace add lackeyjb/playwright-skill
  claude plugin install playwright-skill@playwright-skill
```

If Playwright tools are unavailable, fall back to WebFetch for fetching pages and analyze the raw HTML instead. Skip browser-specific checks (console messages, network requests, responsive resize).

### Initialize

Create `.seo-audit/` directory. If it exists with a previous audit, ask to archive or overwrite.

Use the `seo-specialist` agent for all analysis.

## Phase 1: Discovery

Gather baseline information before auditing.

1. **Fetch target** -- navigate to URL with Playwright, or read local files
2. **Robots.txt** -- fetch `/robots.txt`, check rules, crawl-delay, and extract the explicitly declared Sitemap URL(s)
3. **Sitemap** -- fetch the sitemap found in robots.txt (fallback to `/sitemap.xml` if not declared), count URLs, check lastmod dates
4. **Tech detection** -- identify CMS/framework from headers, meta generators, DOM patterns
5. **Site structure** -- map primary navigation, identify page types
6. **Search intent** -- for each audited page, classify the target query intent (informational / transactional / navigational / commercial investigation) and check via `WebSearch` whether the top 3-5 ranking results use the same content type. Intent mismatches feed the Core SEO and Content Quality findings in Phase 2

**Output file:** `.seo-audit/01-discovery.md`

Present discovery summary and confirm scope before proceeding.

---

## Phase 2: Technical Audit

Run every check below. If `--focus` was passed, run only the categories it names (comma-separated, matching the bold category names below) and mark every other category `not audited` in the Phase 3 scorecard.

Use Playwright `browser_snapshot` for DOM, `browser_evaluate` for JS checks, `browser_network_requests` for resources, `browser_console_messages` for errors, `browser_resize` for responsive testing.

**Core SEO** -- Meta title (50-60 chars), meta description (120-160 chars), canonical URL, Open Graph tags, Twitter Cards

**Headings** -- Exactly 1 H1, proper hierarchy, keywords in H1

**Links** -- Internal link depth, check HTTP status for a small sample (max 3-5 pages) of internal/external links to save time, redirect chains, orphan pages

**Images** -- Alt text, descriptive filenames, lazy loading, WebP/AVIF, dimensions

**Performance** -- Core Web Vitals from CrUX field data (PageSpeed Insights API `loadingExperience.metrics`, thresholds LCP < 2.5s, CLS < 0.1, INP < 200ms), lab data for diagnostics only, transfer size, request count, caching, compression

**Security** -- HTTPS enforced, security headers (CSP, HSTS, X-Frame-Options), no mixed content

**Structured Data** -- JSON-LD present, valid schema, Rich Results eligibility

**Mobile** -- Viewport meta, responsive (375px/768px/1280px), touch targets 44px+, no horizontal scroll

**Crawlability** -- robots.txt not blocking important pages, valid sitemap, noindex only on intended pages

**Content Quality** -- Word count (flag <300), duplicate titles/descriptions, keyword density

**URL Structure** -- Clean slugs, under 75 chars, keywords in path

**Accessibility** -- Alt text on every meaningful image, heading order with no skipped levels, WCAG AA contrast on body text and buttons, descriptive link text (no "click here"), ARIA landmarks (header/nav/main/footer), visible keyboard focus indicators, a label on every form field, skip-nav link, touch targets 44px+

**E-E-A-T Signals** -- Experience, Expertise, Authoritativeness, Trustworthiness: run the `seo-specialist` agent's E-E-A-T checklist

**Local SEO** (if applicable) -- NAP consistency, LocalBusiness schema, geo tags

**Internationalization** (if applicable) -- hreflang tags, lang attribute

**Output file:** `.seo-audit/02-technical-audit.md`

---

## Phase 3: Score & Prioritize

Calculate scores from Phase 2 findings.

1. **Health score**: 0-100 with letter grade (A: 90+, B: 80+, C: 70+, D: 60+, F: <60)
2. **Category breakdown**: score each section
3. **Issue severity**:
   - **Error** (red): broken functionality, missing critical elements, security issues
   - **Warning** (yellow): suboptimal but functional, missed opportunities
   - **Notice** (blue): nice-to-have, best practices
4. **Prioritized fix list**: rank by impact x effort, group into quick wins / medium effort / major projects

**Output file:** `.seo-audit/03-scorecard.md`

```markdown
# SEO Scorecard

## Overall: [X]/100 -- Grade [A-F]

| Category | Score | Errors | Warnings | Notices |
|----------|-------|--------|----------|---------|
| Core SEO | X/100 | X | X | X |
| Headings | X/100 | X | X | X |
| Links | X/100 | X | X | X |
| Images | X/100 | X | X | X |
| Performance | X/100 | X | X | X |
| Security | X/100 | X | X | X |
| Structured Data | X/100 | X | X | X |
| Mobile | X/100 | X | X | X |
| Crawlability | X/100 | X | X | X |
| Content | X/100 | X | X | X |
| URLs | X/100 | X | X | X |
| Accessibility | X/100 | X | X | X |
| E-E-A-T | X/100 | X | X | X |

## Quick Wins
[High impact, low effort fixes]

## Medium Effort
[Moderate impact improvements]

## Major Projects
[Significant changes requiring design/content decisions]
```

---

## PHASE CHECKPOINT -- User Approval Required

Present the scorecard and ask:

```
SEO Audit scored: [X]/100 (Grade [letter])

Errors: [count] | Warnings: [count] | Notices: [count]
Quick wins available: [count]

Please review:
- .seo-audit/02-technical-audit.md
- .seo-audit/03-scorecard.md

1. Fix quick wins -- apply high-impact, low-effort fixes
2. Fix all -- apply all fixable issues
3. Choose specific fixes -- I'll tell you which ones
4. Report only -- skip fixes, generate final report
```

Do NOT proceed to Phase 4 until the user approves. You MUST stop generating text completely at this point -- do NOT simulate the user's response or continue autonomously. Wait for explicit user input before starting Phase 4. If `--strict-mode` and Errors exist, recommend fixing all errors.

---

## Phase 4: Fix & Iterate

Apply approved fixes based on the target type:
- **If `--local` target**: use file editing tools to modify the local source code directly (HTML, React, Next.js, etc.)
- **If live remote URL**: do NOT attempt to modify files. Generate actionable copy-paste code snippets, patch files, or commands the user can run to apply fixes on their server/repo.

1. **Batch fixes**: group related changes, apply in logical order
2. **Re-audit changed elements**: verify fixes resolved the issues
3. **Log changes**: before/after for each fix

**Output file:** `.seo-audit/04-fixes.md`

```markdown
# Fixes Applied

## Fix 1: [description]
- Category: [category]
- Before: [state]
- After: [state]
- Impact: [score change]

## Fix 2: ...
```

---

## Phase 5: Final Report

Read all `.seo-audit/*.md` files and generate the consolidated report.

**Output file:** `.seo-audit/05-report.md`

```markdown
# SEO Audit Report

## Target: [URL or path]
## Date: [timestamp]

## Executive Summary
[2-3 sentences on overall SEO health]

## Score Summary
| | Before | After | Change |
|---|--------|-------|--------|
| Overall | X/100 | Y/100 | +Z |
| Grade | [letter] | [letter] | |

## Category Scores
[Table from Phase 3, updated with post-fix scores]

## Issues Fixed
[Summary from Phase 4]

## Remaining Issues
[Items requiring manual intervention: content rewrites, design decisions, server config]

## Recommendations
1. [Prioritized next steps]
2. [Monitoring recommendations: tools, frequency, key metrics]

## Audit Metadata
- Tool: Playwright + seo-specialist agent
- Categories audited: [count]
- Total checks: [count]
- Fixes applied: [count]
```

---

## Completion

```
SEO audit complete for: <arguments>

Output Files:
- Discovery: .seo-audit/01-discovery.md
- Technical Audit: .seo-audit/02-technical-audit.md
- Scorecard: .seo-audit/03-scorecard.md
- Fixes: .seo-audit/04-fixes.md
- Report: .seo-audit/05-report.md

Score: [X]/100 (Grade [letter]) → [Y]/100 (Grade [letter])
Fixes applied: [count]
Remaining issues: [count]
```

## Quick Examples

- `/seo-audit https://example.com` -- Full technical SEO audit
- `/seo-audit https://example.com/products` -- Audit specific section
- `/seo-audit src/pages --local` -- Audit local HTML/template files
- `/seo-audit https://example.com --focus security,performance` -- Focused audit