SEO Audit Skill

seo-audit-skill

English · 中文 · SEO Audit Agent Skill

Reusable Agent Skills for single-page SEO auditing. Give it a URL — get a structured HTML report with actionable findings.

Built on a Script + LLM two-layer architecture: Python scripts handle deterministic checks (HTTP status, XML parsing, string matching), while the LLM handles semantic judgment (keyword intent, content quality, page type inference). Works with Claude Code, Cursor, and any agent runtime that supports SKILL.md.

Best practices

1. Run npx skills add JeffLi1993/seo-audit-skill, then audit your page (for example: audit this page: https://example.com). Open the report at reports/<hostname>-audit.html and review it yourself: keep what matters for your goals, skip what does not.
2. Share the report (or the key sections) with Cursor or Claude Code and have the assistant work through the findings and fixes item by item.

---

Report Output

Each basic audit produces a standalone HTML report saved to reports/<hostname>-audit.html. Full audits save to reports/<hostname>-full-audit.html.

Section	What you get
Audit Summary	One-line verdict + critical / warnings / passing at a glance
Site Checks	Sitemap URL Inventory · Crawlability · URL Canonicalization · i18n · Schema · E-E-A-T
Page Speed	Full only — Lighthouse scores, lab metrics, final URL, screenshot availability
Page Checks	TDK · H1 · Headings · Word Count · Internal Links · Social Tags
Priority Actions	Top 3 highest-impact fixes, ranked
Insight Walkthrough	Evidence → Impact → Fix for each major finding

audit this page: https://openclaw.ai
→ ✅ Report saved → reports/openclaw-ai-audit.html

Website	Audit Summary	Site Checks	Page Checks & insights
colaos.ai

---

Skills

Skill	Tier	When to use
seo-audit	Basic	Default — give it a URL, get a 20+ check structured report
seo-audit-full	Full	Deep audit with PageSpeed, sitemap inventory, social tags, content quality, GSC data, competitor gap

seo-audit-full requires a Google PageSpeed Insights API key for PageSpeed checks. Set PAGESPEED_API_KEY / GOOGLE_PAGESPEED_API_KEY, or pass --api-key; without a key, the full audit stops and asks you to configure one.

---

Audit Coverage

Site-level

Check	What it verifies	Basic	Full
Sitemap URL Inventory	Standalone table of top sitemap directories: URL count, page type, representative example URL	—	✅
Staging Subdomain Indexation	Detects public test., staging., dev., preview., beta., uat. hosts that mirror production and may be indexable	—	✅
robots.txt	RFC 9309 group parsing, Allow/Disallow logic, Googlebot status, Sitemap directives	✅	✅
sitemap.xml	Valid XML, URL count, follows Sitemap directive path from robots.txt, samples child sitemap URLs when needed	✅	✅
404 Handling	True 404 vs soft 404 (200) vs redirect-to-homepage (301)	✅	✅
URL Canonicalization	HTTP→HTTPS redirect, www consistency, trailing slash, canonical tag match	✅	✅
i18n / hreflang	Reciprocal symmetry, BCP 47 codes, x-default, default-language URL duplication, canonical/hreflang alignment	✅	✅
Schema (JSON-LD)	Parseability, @type detection, required/recommended fields, nested fields, type conflicts, localized schema language/URL alignment	✅	✅
E-E-A-T Trust Pages	About / Contact / Privacy / Terms — exists (HTTP 200) + reachable from footer/nav	✅	✅
GSC Crawl Status	Index coverage, crawl errors, blocked resources	—	✅
PageSpeed / Lighthouse	Performance · Accessibility · Best Practices · SEO scores, lab metrics, final URL, screenshot availability	—	✅

Sitemap URL Inventory is intentionally rendered as its own table before Crawlability:

Directory	URL Count	Page Type	Example Page
/blog/	300	Blog / Content Pages	https://xx.ai/blog/best-ai-video-tools
/tools/	80	Tool Pages	https://xx.ai/tools/image-generator
/alternatives/	40	Alternative / Competitor Pages	https://xx.ai/alternatives/synthesia

Use it as a site-level map, then choose representative URLs from important directories for deeper full audits.

Page-level

Check	What it verifies	Basic	Full
URL Slug	Lowercase, hyphenated, keyword present, stop word & stuffing detection	✅	✅
Title Tag	50–60 chars, keyword position, homepage vs inner page rules	✅	✅
Meta Description	120–160 chars, keyword match, concrete value prop (not generic fluff)	✅	✅
H1 Tag	Single H1, keyword match (full / partial / none), semantic intent review	✅	✅
Canonical Tag	Self-referencing, matches final URL after redirects	✅	✅
Image Alt Text	Alt attribute check on all <img>, JS-render detection	✅	✅
Word Count	Body text ≥ 500 words, thin content flag	✅	✅
Keyword Placement	Primary keyword within first 100 body words	✅	✅
Heading Structure	H2 count (target 5–7), H3/H2 ratio, keyword distribution in H2s	✅	✅
Internal Links	Same-origin links (excl. nav/footer), equity distribution	✅	✅
OG / Social Tags	og:image, twitter:card, social preview completeness	—	✅
Content Quality	E-E-A-T depth, readability, specificity vs competitors	—	✅
Robots Meta	noindex, nofollow, max-snippet directives	—	✅

---

Structure

seo-audit-skill/
├── seo-audit/
│   ├── SKILL.md                       # Skill definition + agent workflow
│   ├── references/REFERENCE.md        # Field definitions, edge cases
│   ├── assets/report-template.html    # HTML output template
│   └── scripts/
│       ├── check-site.py              # robots.txt + sitemap → JSON
│       ├── check-page.py              # TDK + H1 + canonical + slug → JSON
│       ├── check-schema.py            # JSON-LD extraction + validation → JSON
│       └── fetch-page.py              # Raw HTML fetcher, SSRF protection
└── seo-audit-full/
    ├── SKILL.md
    ├── references/REFERENCE.md
    ├── assets/report-template.html
    └── scripts/
        ├── check-site.py              # staging + sitemap inventory + robots/sitemap → JSON
        ├── check-pagespeed.py         # PageSpeed Insights / Lighthouse → JSON
        ├── check-social.py            # OG + Twitter Card validation → JSON
        └── check-schema.py            # JSON-LD quality + localized schema validation → JSON

---

Architecture: Script + LLM

URL
 │
 ▼
┌──────────────────────────────────────────────────┐
│  Layer 1 · Python Scripts                        │
│  Deterministic checks → structured JSON          │
│                                                  │
│  check-site.py      sitemap inventory, staging   │
│  check-page.py      H1 / title / meta / canonical│
│  check-schema.py    JSON-LD fields + localization│
│  fetch-page.py      raw HTML + SSRF protection   │
└───────────────────────┬──────────────────────────┘
                        │ JSON + llm_review_required flag
                        ▼
┌──────────────────────────────────────────────────┐
│  Layer 2 · LLM Agent                             │
│  Semantic judgment on flagged fields only         │
│                                                  │
│  · Keyword intent alignment (H1 / title)         │
│  · Meta description quality & specificity        │
│  · Page type → expected Schema @type mapping     │
│  · E-E-A-T trust page reachability (footer/nav)  │
│  · Content analysis (word count, heading, links) │
└───────────────────────┬──────────────────────────┘
                        │
                        ▼
              report-template.html
              → reports/<hostname>-audit.html

Why two layers? Scripts handle the 80% of checks that are deterministic — does robots.txt exist? Is the title 55 characters? The LLM handles the 20% that require understanding — does this H1 semantically cover the intent of "AI workflow automation"? The llm_review_required flag ensures the LLM only intervenes when the script explicitly cannot make the call. No hallucination on factual checks, no blind spots on semantic ones.

---

Installation

Option 1: CLI (Recommended)

npx skills add JeffLi1993/seo-audit-skill

# Or install a specific tier
npx skills add JeffLi1993/seo-audit-skill --skill seo-audit
npx skills add JeffLi1993/seo-audit-skill --skill seo-audit-full

Option 2: Claude Code Plugin

/plugin marketplace add JeffLi1993/seo-audit-skill
/plugin install seo-audit-skill

Usage

audit this page: https://example.com

---

Scripts

All scripts output structured JSON to stdout. Exit code 0 = pass/warn, 1 = any fail.

Script	What it does
check-site.py	robots.txt + sitemap + sitemap inventory — RFC 9309 parsing, staging subdomain checks, top directory grouping
check-page.py	H1 / title / meta / canonical / URL slug — keyword match with stop-word-aware filter
check-schema.py	JSON-LD extraction, @graph flattening, @type + required field validation, localized schema alignment
fetch-page.py	Raw HTML fetch — SSRF protection, redirect chain tracking, Googlebot UA option
check-pagespeed.py	Full only — PageSpeed Insights / Lighthouse scores and lab metrics; requires API key
check-social.py	Full only — OG tags + Twitter Card validation

Dependency: pip install requests

---

License

MIT