Website Health

/website-health — Website Health Audit

Orchestrates a cross-cutting website audit across 7 dimensions. Designed for periodic invocation against live sites.

Architecture — hybrid orchestrator:

• Native checks (new lib scripts): seo, performance, links, privacy, content
• Pure delegation (existing sub-skill owns the logic): a11y → /frontend a11y, security → /security-verify dast

Quick Start

/website-health <url>                      # quick summary, all 7 dimensions (L1)
/website-health full <url>                 # deep audit, all dimensions (L2+)
/website-health seo <url>                  # single dimension
/website-health performance <url>          # single dimension
/website-health links <url>                # single dimension
/website-health privacy <url>              # single dimension
/website-health a11y <url>                 # delegates to /frontend a11y + pa11y
/website-health security <url>             # delegates to /security-verify dast + extras
/website-health content <url>              # single dimension
/website-health report <url>               # full audit + persistent markdown report
/website-health patterns <dimension>       # show fix recipes (seo, performance, links, privacy, a11y, security, content)

Workflow

Step 1: Parse Arguments

Parse $ARGUMENTS for subcommand, URL, and optional flags (--stack <name>).

Stack auto-detection (when no URL is provided, check in order):

# Astro config extraction
if [ -f astro.config.mjs ] || [ -f astro.config.ts ]; then
  ASTRO_SITE=$(grep -E "^\s*site:" astro.config.mjs astro.config.ts 2>/dev/null | head -1 | sed "s/.*site:\s*['\"]//;s/['\"].*//" || echo "")
  STARLIGHT=$(grep -l "@astrojs/starlight" package.json 2>/dev/null)
  STACK="astro"
  [ -n "$STARLIGHT" ] && STACK="astro-starlight"
fi

Stack-specific behavior:

• astro-starlight: activates Starlight-specific content checks (see Dimension: Content — Starlight Mode)

• astro: standard checks + Astro build output validation

• All other stacks: standard 7-dimension audit

• If no URL and no marker: report error "No URL provided and no website project detected. Run: /website-health <url>"

• If no subcommand: read and show templates/overview.md

• If full: run all 7 dimensions at deep depth

• If report: run all 7 dimensions + write report to docs/website-health/report-YYYY-MM-DD.md

Step 2: Check Tool Availability

bash "$HOME/.claude/skills/website-health/lib/tool-check.sh"

Note which tools are available. Each dimension adapts its checks based on available tools. Always report tool availability at the start of output.

Step 3: Connectivity Pre-check

HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 "$URL" 2>/dev/null || true)

If 000: report unreachable and exit. Otherwise proceed.

Step 4: Route to Dimension(s)

Run the requested dimension(s). For summary/full modes, run all 7 sequentially.

Dimension execution order (for full and summary):

1. SEO
2. Performance
3. Links
4. Privacy
5. Accessibility
6. Security
7. Content

Step 5: Produce Report

Use the uniform output format (see below). For report mode, additionally write to disk using templates/report-template.md as scaffold.

Dimension: SEO

Technical on-page SEO audit. Replaces Ahrefs Site Audit for meta analysis.

Run:

bash "$HOME/.claude/skills/website-health/lib/seo-checker.sh" "$URL" [--depth N] [--sample N]

Checks:

Templates:

• L1: Read templates/seo/summary.md
• L2: Read templates/seo/patterns.md (fix examples, Hugo-specific tips)

Dimension: Performance

Core Web Vitals and server-side performance.

Run:

bash "$HOME/.claude/skills/website-health/lib/performance-checker.sh" "$URL"

Primary tool: lighthouse CLI. Fallback: curl-only header checks.

Checks:

Templates:

• L1: Read templates/performance/summary.md
• L2: Read templates/performance/patterns.md

Dimension: Links

Link health audit — broken links, redirect chains, orphan pages.

Run:

python3 "$HOME/.claude/skills/website-health/lib/link-crawler.py" "$URL" --depth 3 --timeout 5 --output json

Checks:

Templates:

• L1: Read templates/links/summary.md
• L2: Read templates/links/patterns.md

Dimension: Privacy

GDPR and privacy compliance audit.

Run:

bash "$HOME/.claude/skills/website-health/lib/privacy-checker.sh" "$URL"

Optional: playwright-cli for cookie consent interaction testing.

Checks:

Templates:

• L1: Read templates/privacy/summary.md
• L2: Read templates/privacy/patterns.md

Dimension: Accessibility (DELEGATES)

Delegates to existing skills. Do NOT reimplement accessibility checks.

Delegation chain:

1. Invoke /frontend a11y with the URL — full WCAG 2.1 AA audit
2. If pa11y is installed: pa11y "$URL" --standard WCAG2AA --reporter json
3. Cross-reference Lighthouse accessibility score if performance was already run

Templates:

• L1: Read templates/a11y/summary.md (documents delegation)
• L2: Read templates/a11y/patterns.md

Dimension: Security (DELEGATES)

Delegates to existing skills plus additional checks.

Delegation:

1. Invoke /security-verify dast "$URL" — OWASP HTTP headers, CORS, TLS, info disclosure
2. Parse dast output and merge into report

Additional checks (not in dast-runner.sh):

Templates:

• L1: Read templates/security/summary.md
• L2: Read templates/security/patterns.md

Dimension: Content

Content quality analysis.

Run:

python3 "$HOME/.claude/skills/website-health/lib/content-analyzer.py" "$URL" --output json

Checks:

Templates:

• L1: Read templates/content/summary.md
• L2: Read templates/content/patterns.md

Dimension: Content — Starlight Mode

Active only when --stack astro-starlight is passed (auto-set by stack detection). Runs IN ADDITION to the standard Content checks.

Starlight-specific checks:

Detection of Starlight structure:

# Verify expected Starlight directories exist
ls src/content/docs/ 2>/dev/null
grep -r "sidebar" astro.config.mjs astro.config.ts 2>/dev/null | head -5
# Check for i18n
grep -E "locales|defaultLocale" astro.config.mjs astro.config.ts 2>/dev/null

Output Format

All dimensions use this uniform structure:

## Website Health — <domain> — <date>

### <Dimension> [PASS|WARN|FAIL]
- ✓ <passing finding>
- ⚠ <warning finding>
- ✗ <failing finding>
- [SKIP] <skipped check> — <tool> not installed

### ...

Overall: [PASS|WARN|FAIL]

Gate logic: FAIL if any dimension FAIL. WARN if any WARN. PASS only if all pass. Skipped checks do not affect the gate.

Post-Audit: Recommendations

After presenting dimension results, ALWAYS generate a Recommendations section by triaging findings.

Triage Rules

Quick Wins (suggest fixing immediately — <5 min each):

• Missing meta tags (title, description, OG) → one-line template edit
• Missing HTTP headers (Cache-Control, ETag, SameSite) → config file edit
• Missing alt text on small number of images → content edit
• HTTPS redirect issues → server/CDN config
• Single broken internal links → content fix
• Missing canonical URLs → template one-liner

Tech Debt (suggest GitHub issue via /health issues):

• Structural SEO gaps (missing JSON-LD, incomplete hreflang across all pages)
• Multiple broken external links (needs manual review of replacements)
• Content quality issues (thin content, stale pages — needs writing)
• Missing cookie consent categories (needs legal review)
• Performance optimization requiring code changes (image format migration, font subsetting)
• Accessibility issues requiring template refactoring

Install to Unlock (informational):

• Any [SKIP] findings from missing tools → show install command

Output Format

After the dimension results and Overall gate, generate:

## Recommendations

### Quick Wins (fix now)
- [Dimension] <what to fix> — <where/how, 1 line>

### Tech Debt (create issues)
- [Dimension] <what to fix> — <why it's bigger>

### Install to Unlock
- `<install command>` — <what it enables>

If no quick wins: "No quick wins — all findings require deeper investigation." If no tech debt: "No tech debt items — all findings are quick wins or informational."

Next Steps

After Recommendations, show actionable next steps:

## Next Steps

- **Quick Wins**: Fix the items listed above — small config/template edits
- **Fix Recipes**: `/website-health patterns <dimension>` for code examples
- **Create Issues**: `/health issues` to open GitHub BACKLOG issues for tech debt
- **Full Project Audit**: `/health full` to add code health dimensions

The "Full Project Audit" line only shows when running standalone /website-health. When invoked from within /health full, omit it (already running everything).

Subcommand: patterns

Show L2 fix recipes for a specific dimension.

/website-health patterns seo
/website-health patterns performance
/website-health patterns links
/website-health patterns privacy
/website-health patterns a11y
/website-health patterns security
/website-health patterns content

Steps:

1. Read templates/<dimension>/patterns.md
2. Present content to user

Use after an audit to get detailed fix examples for a specific dimension.

Graceful Degradation

The lib/tool-check.sh script runs at the start. Each dimension adapts:

Minimum viable: curl + python3 only. All 7 dimensions produce output.

What We Cannot Check (Ahrefs Proprietary)

These require Ahrefs' proprietary crawl index — no free tool replicates them:

• Historical backlink index (third-party links pointing TO you)
• Organic traffic estimates per page
• Domain Rating / URL Rating
• Keyword rankings and search volume

Use Ahrefs CSV exports for baseline comparison when available.

Integration

Two entry points, same outcome (quick wins + tech debt issues):

• /health full (recommended for website projects) — runs all project dimensions including website, then offers /health issues for everything. Context from /website-health is preserved because it runs in the same conversation.
• /website-health standalone — runs 7 website dimensions, shows recommendations, points to /health issues for issue creation. Context is already in the conversation.

Key: /health issues doesn't re-run checks. It reads findings already in the conversation and proposes gh issue create commands. Works after either entry point.

• Skill is stateless — designed for periodic invocation via /loop or future headless cron