seo-audit-full

What this skill does

# seo-audit-full — Advanced Full SEO Audit

This skill runs a full single-page SEO audit from the `seo-audit-full` directory.
It does not route to `seo-audit` when only a URL is provided.

---

## When to Use This Skill

Use `seo-audit-full` when the user asks for:

- "seo-audit-full"
- "full SEO audit"
- "advanced SEO audit"
- "technical SEO audit"
- "deep audit"
- "comprehensive SEO review"
- "audit everything"

URL-only requests are valid. When external datasets are not supplied, run the
full public-signal workflow and clearly note missing data sources in the report.

---

## Input Expected

| Input | Required | Notes |
|-------|----------|-------|
| Page URL | Yes | The primary page to audit |
| Primary keyword | Recommended | Improves content relevance scoring |
| PageSpeed API key | Yes | Ask the user for it at the start; run without it if unavailable |
| Raw HTML or page content | Optional | Enables more accurate content checks when supplied |
| GSC / crawl / analytics data | Optional | Include when supplied, otherwise mark unavailable |
| Competitor benchmark data | Optional | Include when supplied |

At the start of a full audit, ask the user for a PageSpeed Insights API key:

```
For PageSpeed checks, please provide a Google PageSpeed Insights API key.
Get one here: https://developers.google.com/speed/docs/insights/v5/get-started
Open "Acquiring and using an API key" → "Get a Key".
If you do not provide one, I will still run the audit and mark the PageSpeed
module with instructions for getting a key if the API is quota-limited.
```

---

## Architecture: Full = Core + Performance + Advanced

```
┌─────────────────────────────────────────────────────────────┐
│  seo-audit-full Workflow                                    │
│                                                             │
│  Phase 1: Run core scripts (./scripts/)                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  check-site.py      → robots.txt, sitemap, 404, URL  │   │
│  │  check-page.py      → title, H1, meta desc, slug     │   │
│  │  check-schema.py    → JSON-LD validation              │   │
│  │  fetch-page.py      → raw HTML for analysis           │   │
│  └──────────────────────────────────────────────────────┘   │
│                          ↓                                  │
│  Phase 2: Run performance + full-only scripts (./scripts/)  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  check-pagespeed.py → Lighthouse scores + metrics     │   │
│  │  check-social.py    → OG Tags + Twitter Card          │   │
│  │  (more scripts added here as modules grow)            │   │
│  └──────────────────────────────────────────────────────┘   │
│                          ↓                                  │
│  Phase 3: LLM-only advanced checks                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  E-E-A-T content quality scoring                      │   │
│  │  Duplicate content signals                            │   │
│  │  Anchor text quality assessment                       │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## Output

Produce an **Advanced Full SEO Audit Report** by filling the template at
[assets/report-template.html](assets/report-template.html),
then **save it to a file — never print raw HTML to the terminal**.

**File naming:** `reports/<hostname>-<slug>-full-audit.html`
```
https://example.com/blog/best-tools → reports/example-com-blog-best-tools-full-audit.html
https://example.com/                → reports/example-com-full-audit.html
```

**After saving, tell the user:**
```
✅ Full Report saved → reports/example-com-full-audit.html
   Open it now? (yes / no)
```
If yes → run: `open reports/example-com-full-audit.html`

**Template placeholders** — fill each independently:

| Placeholder | Content |
|---|---|
| `{{summary_verdict}}` | One sentence: total checks run, how many failed/warned/passed |
| `{{summary_critical_html}}` | `<li>` per critical item, or `<li class="summary-empty">None</li>` |
| `{{summary_warnings_html}}` | `<li>` per warning item, or `<li class="summary-empty">None</li>` |
| `{{summary_passing_html}}` | `<li>` per passing check, or `<li class="summary-empty">None</li>` |
| `{{pagespeed_checks_html}}` | Full PageSpeed module using `check-pagespeed.py` output |
| `{{site_checks_html}}` | Site-level check tables |
| `{{eeat_checks_html}}` | E-E-A-T trust page table |
| `{{page_checks_html}}` | Page-level check tables, including full-only additions |
| `{{priority_actions_html}}` | Ordered priority action list |
| `{{insights_html}}` | Optional finding walkthrough cards |

---

## Scripts

Run full scripts from this directory. All output is structured JSON — use it
directly as evidence.

**Dependencies:** `pip install requests`

### Phase 1: Core scripts

```bash
# 1. site-level checks (robots.txt + sitemap.xml + 404 + URL canonicalization)
python scripts/check-site.py https://example.com

# 2. page-level checks (H1, title, meta description, canonical, URL slug)
python scripts/check-page.py https://example.com --keyword "primary keyword"

# 3. fetch raw HTML for downstream scripts
python scripts/fetch-page.py https://example.com --output /tmp/page.html

# 4. JSON-LD schema validation
python scripts/check-schema.py --file /tmp/page.html
```

### Phase 2: Full-only scripts

```bash
# 5. PageSpeed / Lighthouse checks
python scripts/check-pagespeed.py https://example.com --strategy mobile --timeout 180 --api-key "USER_PROVIDED_KEY"
# If no key was provided, run without --api-key and report any quota/API-key error.

# 6. Social tags: OG + Twitter Card validation
python scripts/check-social.py --file /tmp/page.html
# Or directly from URL:
python scripts/check-social.py https://example.com
```

Each script exits with code `0` (all pass/warn) or `1` (any fail/error).

PageSpeed can take 200 seconds. Use a 180-second timeout by default. If it
still times out, mark the Page Speed module as `error` and state that the
PageSpeed API timed out; do not treat that as confirmed page performance failure.
If PageSpeed fails because no API key was provided or Google returns a quota/API
key error, keep the audit running and render the PageSpeed module as `error` with
this instruction:
`Get a PageSpeed API key at https://developers.google.com/speed/docs/insights/v5/get-started → "Acquiring and using an API key" → "Get a Key".`

---

## Scope — Full Audit Check Whitelist

Full runs its own core checks plus the full-only items marked ★ below.

### Site-Level Checks (in `{{site_checks_html}}`)

Core checks:
- robots.txt · sitemap.xml · 404 Handling · URL Canonicalization · i18n / hreflang

### Page Speed Checks (in `{{pagespeed_checks_html}}`)

Full-only:
- Lighthouse category scores: Performance · Accessibility · Best Practices · SEO
- Lab metrics: FCP · LCP · TBT · CLS · Speed Index
- Final URL and screenshot availability

### E-E-A-T Checks (in `{{eeat_checks_html}}`)

Core checks:
- About Us · Contact · Privacy Policy · Terms of Service · Media/Partners (only if present)

Contact logic (Contact row only):
- A dedicated `/contact` page is **not required**
- **Pass** if contact is reachable via any of: dedicated contact page (HTTP 200) · About page with contact details · footer/nav mailto, email, social links, or contact form
- **Fail** only when no contact pathway exists anywhere on the site
- Missing `/contact` alone is **not** a fail when About or footer/nav already expose contact info

E-E-A-T infrastructure rules — two layers per trust page:
- **Layer 1 — Exists:** HTTP 200 for the trust page URL (Contact uses Contact-specific rules above)
- **Layer 2 — Reachable:** linked from footer or main nav

| Page | Required |
|---|---|
| About Us | Yes |
| Contact | Yes — dedicated page optional; About or footer/nav contact details satisfy this |
| Privacy Policy | Yes