Site Health Audit Skill

Crawl any website via its sitemap and produce a comprehensive technical SEO audit with an Ahrefs-style health score.

When to Use

• User asks for a "site audit", "health check", or "technical SEO audit"
• User wants to find broken links on their website
• User asks about duplicate titles, missing meta descriptions, or other on-page SEO issues
• After a major site launch, redesign, or migration
• As a scheduled monthly audit to track site health over time

How to Run

The script auto-discovers the sitemap and requires zero npm dependencies.

Quick sample (50 pages)

bun .claude/skills/site-audit/scripts/site-audit.ts --url https://example.com --fix

Full crawl with report file

bun .claude/skills/site-audit/scripts/site-audit.ts --url https://example.com --full --fix --output docs/seo/site-audit-$(date +%Y-%m-%d).md

Custom sitemap URL

bun .claude/skills/site-audit/scripts/site-audit.ts --url https://example.com --sitemap https://example.com/custom-sitemap.xml --full

Options

Flag	Description
--url <url>	Base URL of the site to audit (required)
--sitemap <url>	Direct sitemap URL (skips auto-discovery)
--sample N	Randomly sample N URLs (default: 50)
--full	Crawl every URL in the sitemap
--fix	Show actionable fix suggestions per issue
--verbose	Print per-URL details
--json	Output results as JSON (for programmatic use)
--output <path>	Write structured markdown report to file

What It Checks (16 categories)

1. HTTP Status — 4xx/5xx errors
2. Title — missing, too short (<10), too long (>60)
3. Meta Description — missing, too short (<50), too long (>160)
4. H1 — missing or multiple H1 tags
5. Canonical — missing or non-self-referencing
6. Indexing — noindex directives
7. Open Graph — missing og:title, og:description, og:image
8. Twitter Card — missing twitter:card
9. Hreflang — missing x-default, missing self-reference
10. Images — missing alt attributes
11. Content — thin content (<100 words)
12. Performance — slow responses (>1.5s), large pages (>500KB)
13. Broken Links — internal links pointing to 404s
14. Duplicate Titles — multiple pages sharing the same title (errors)
15. Duplicate Descriptions — multiple pages with same meta description
16. Duplicate H1 — multiple pages sharing the same H1

Health Score Formula

Uses the Ahrefs formula:

score = (total_pages - pages_with_errors) / total_pages * 100

Only errors affect the score — warnings and notices are informational.

Where to Save Reports

Write audit reports to the Space filesystem so they persist and can be compared over time:

docs/seo/site-audit-YYYY-MM-DD.md

When running a follow-up audit, compare with the previous report to highlight improvements and regressions.