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.

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

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

Skills

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

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

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

Page-level

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.

Dependency: pip install requests

License

MIT