🔍 website-seo-audit

Crawl any website and get a graded SEO report — in seconds, with zero setup.

English · 简体中文

PyPI Python License: MIT Zero dependencies Agent Skill PRs welcome

A dependency-free SEO auditor you can run as a command-line tool or install as a skill for your AI coding agent (Claude Code, Codex, opencode, …). It crawls a site, checks dozens of on-page, technical, and structured-data signals, and hands you a scored report with a concrete fix for every issue.

No API keys. No sign-up. No pip install. Just Python 3.8+ and the standard library.

python3 -m seo_audit https://example.com

✨ See it in action

# 🔍 SEO Audit — https://example.com
Score: 72/100 (C)  ·  🔴 2 critical · 🟡 8 warnings · 🟢 15 notices
Crawled 23 pages · 45 internal links checked

## 🔴 Critical (2)
### Broken internal links (3×)
Internal link returns HTTP 404: https://example.com/old-page
- Fix: Fix or remove the link, or restore the target page (add a redirect if it moved).

### Site not on HTTPS
- Fix: Install a TLS certificate and redirect all HTTP traffic to HTTPS.

## 🟡 Warnings (8)
### Missing meta description (6×)
### Duplicate titles
### Structured data missing fields — Article missing image, datePublished
...

👉 Full example: examples/sample-report.md

🚀 Quick start

git clone https://github.com/zxhydfzr/website-seo-audit.git
cd website-seo-audit
python3 -m seo_audit https://yoursite.com

That's it. No virtualenv, no packages to install.

Prefer a global command? It's on PyPI:

pip install website-seo-audit
seo-audit https://yoursite.com

(Or with pipx: pipx install website-seo-audit.)

🤖 Use it inside your AI agent

This repo ships a SKILL.md, so any agent that supports the open Agent Skills format can pick it up. Then just say: "audit the SEO of https://example.com" and your agent runs the tool and explains the results.

Agent Install
Claude Code git clone https://github.com/zxhydfzr/website-seo-audit ~/.claude/skills/website-seo-audit
Codex Clone into your project — the bundled AGENTS.md tells it how to run
opencode / others Clone anywhere the agent can read files and point it at SKILL.md

🔬 What it checks

On-page

  • <title> — present / length / duplicate
  • Meta description — present / length
  • <h1> & heading hierarchy
  • Canonical tag
  • Mobile viewport
  • <html lang>
  • Image alt text
  • Thin content (CJK-aware)
  • Open Graph tags
  • Mixed content on HTTPS

Technical

  • HTTPS
  • robots.txt
  • sitemap.xml
  • Broken internal links (4xx/5xx)
  • Duplicate titles / meta
  • Near-orphan pages
  • Redirect handling

Structured data ⭐

  • Valid JSON-LD syntax
  • @type present
  • Required Schema.org fields (Article, Product, Organization, BreadcrumbList, FAQ, Recipe, Event, …)
  • ISO-8601 dates

⭐ Why it's different

  • Structured-data aware. Most quick SEO checkers stop at titles and headings. This one validates your JSON-LD / Schema.org markup — the signal search engines and AI answer engines use to understand and cite your pages.
  • Zero dependencies. Only the Python standard library, so it runs anywhere Python does — laptops, CI, containers, a locked-down server.
  • Agent-native. Ships as a portable skill, so your AI assistant can run a full audit and walk you through the fixes conversationally.
  • Polite & safe. Respects robots.txt, sends a real User-Agent, rate-limits itself, and only crawls the site you point it at.

⚙️ Options

Option Default Meaning
-1, --single off Audit only the given URL (no crawl)
--max-pages N 50 Max pages to crawl
--max-depth N 3 Max crawl depth
--json off Machine-readable JSON output
-o, --output FILE — Write the report to a file
--ignore-robots off Crawl even if robots.txt disallows (your own sites)
--no-link-check off Skip broken-link detection (faster)
-q, --quiet off Suppress crawl progress

The command exits non-zero when any critical issue is found, so you can gate CI:

seo-audit https://yoursite.com --json -o seo.json || echo "SEO regressions!"

📊 How the score works

Starts at 100 and deducts, with per-severity caps so a big site can't collapse on notices alone: 🔴 −15 each · 🟡 −3 each · 🟢 −1 each. Grades: A ≥90 · B ≥80 · C ≥70 · D ≥55 · F below.

🗺️ Roadmap

  • Page-speed / Core Web Vitals signals
  • hreflang & internationalization checks
  • HTML report export
  • Optional sitemap-seeded crawl (audit every listed URL)

Ideas and PRs welcome — see below.

🤝 Contributing

Issues and pull requests are very welcome. The codebase is small, typed, and dependency-free by design; please keep it that way. Run the tests with:

python -m unittest discover -s tests

🧭 Prior art & credits

website-seo-audit is written from scratch, with no third-party code — that's the whole point of "zero dependencies." Its checks follow widely-published SEO guidance (Google Search documentation and the best practices you'll find echoed across the industry). If you're weighing options, two well-known open-source tools cover nearby ground and are worth a look: python-seo-analyzer and seonaut.

Where this project puts its emphasis: zero dependencies, install-as-an- agent-skill packaging, and structured-data (JSON-LD / Schema.org) validation.

📄 License

MIT — free for personal and commercial use.

If this saved you time, a ⭐ helps others find it.

Made for everyone who wants clean SEO without a dashboard login.