SEO Audit Skill

A portable SEO audit skill for AI coding agents — Claude Code, Claude Desktop, Cursor, and OpenAI/Codex. Give it a live homepage URL or a codebase and it checks search-engine readiness from basic on-page hygiene to advanced technical, structured-data, social, and performance signals, then produces a prioritized Markdown report plus machine-readable JSON.

• ✅ No API keys required. Runs on the Python standard library; uses requests +

BeautifulSoup automatically when installed for more robust parsing.

• ✅ Two modes: audit a live URL, or audit project source code (framework-aware).
• ✅ Six scored categories rolled into an overall grade, with a **bot-block / low-confidence

detector** so cloaked or JS-rendered pages aren't taken at face value.

See examples/sample-report.md for what a report looks like.

What it checks

Full checklist and exact thresholds: checklist.md and thresholds.md.

Install

Prerequisite (all systems): Python 3.8+ on the machine. The engine runs on the standard library alone; pip install -r skills/seo-audit/requirements.txt is optional but improves parsing. Most setups below start from a local clone:

git clone https://github.com/Maks417/seo-audit.git
cd seo-audit

1. Claude Code

Option A — plugin (one command, recommended). No clone needed:

/plugin marketplace add Maks417/seo-audit
/plugin install seo-audit

Then just ask "audit the SEO of https://example.com", or run the slash command /seo-audit https://example.com (it also audits the current project: /seo-audit this codebase).

Option B — personal or project skill (no plugin). Copy the self-contained skill folder:

cp -r skills/seo-audit ~/.claude/skills/seo-audit      # personal: all projects
# or
cp -r skills/seo-audit .claude/skills/seo-audit        # this project only

It auto-triggers on SEO requests — no command required.

2. Claude Desktop

Desktop installs a skill from a .zip whose SKILL.md sits at the archive root.

Easiest — download the prebuilt bundle: grab seo-audit.zip from the Releases page (no clone or Python needed).

Or build it yourself — exactly what package.py produces:

python package.py            # writes dist/seo-audit.zip

Either way, in Claude Desktop: Settings → Capabilities → Skills → Upload skill, and choose the seo-audit.zip. Use it by asking naturally, e.g. "audit the SEO of https://example.com".

Desktop sandbox notes: skills run in a Linux code-execution container. URL mode needs outbound network — it works only if the container allows it; code mode works offline. The container is stdlib-only unless deps are pip-installed in-session, but the engine's standard-library fallback means it runs either way.

3. Cursor

Cursor uses rule files under .cursor/rules/:

cp adapters/cursor/seo-audit.mdc your-project/.cursor/rules/seo-audit.mdc
cp -r skills/seo-audit your-project/skills/seo-audit     # the rule points at these scripts/refs

Then ask Cursor's agent to "run an SEO audit on https://example.com" — it reads the rule and runs the engine.

4. Codex (OpenAI)

Codex reads an AGENTS.md at the repo root:

cp adapters/openai/AGENTS.md your-project/AGENTS.md      # or paste into an existing AGENTS.md
cp -r skills/seo-audit your-project/skills/seo-audit     # keep the scripts/refs reachable

Then ask Codex to "audit this site's SEO: https://example.com" or "audit this codebase for SEO" — it follows AGENTS.md and runs the engine. The same file also works as a custom-GPT system prompt.

Install matrix

Standalone CLI

pip install -r skills/seo-audit/requirements.txt        # optional but recommended
python skills/seo-audit/scripts/seo_audit.py https://example.com --crawl 8 --out ./seo-report
python skills/seo-audit/scripts/seo_audit.py --self-check   # show active backend

Writes seo-report/report.md and seo-report/report.json.

Requires Python 3.8+. Optional deps: requests, beautifulsoup4, lxml, brotli.

Repository layout

seo-audit/
├── .claude-plugin/             # plugin.json + marketplace.json (Claude Code plugin install)
├── commands/seo-audit.md       # /seo-audit slash command
├── skills/seo-audit/           # the self-contained skill (copy this for personal/Desktop use)
│   ├── SKILL.md                #   portable core: workflow + triggering
│   ├── requirements.txt
│   ├── scripts/                #   audit engine
│   │   ├── seo_audit.py        #     CLI orchestrator
│   │   ├── fetch.py            #     HTTP + polite crawler (stdlib fallback)
│   │   ├── dom.py              #     HTML parsing (BeautifulSoup or stdlib)
│   │   ├── rules.py            #     finding model + scoring
│   │   ├── report.py           #     Markdown + JSON output
│   │   ├── confidence.py       #     bot-block / low-confidence detector
│   │   └── checks/             #     one module per category
│   ├── references/             #   checklist, thresholds, code-audit guide
│   └── assets/                 #   report template
├── adapters/                   # Cursor (.mdc) + OpenAI (AGENTS.md) entry points
├── examples/sample-report.md   # example output
├── package.py                  # builds dist/seo-audit.zip for Claude Desktop
├── .gitignore
├── LICENSE                     # MIT
└── README.md

How it works

The engine fetches the homepage, crawls a few same-origin pages (respecting robots.txt), runs every check module, scores the findings (weighted by impact), assesses confidence, and renders the report.

Limits

• Bot-blocking / cloaking aware. Sites that serve a stripped page or a challenge to

non-browser clients (e.g. Amazon, aggressive WAFs) are detected and the report is marked low confidence with reasons — so a degraded score isn't taken at face value.

• Static analysis of server-rendered HTML — JS-heavy SPAs may under-count content/links

(also flagged as low confidence); verify in a browser when accuracy matters.

• Core Web Vitals are not measured. Use PageSpeed Insights or

Lighthouse for real LCP/INP/CLS. The PageSpeed Insights API can be wired in as an optional extension (see thresholds.md).

• The crawler is intentionally small and polite; raise --crawl deliberately for larger sites.

License

MIT.