Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

feat(audit): persist full audit reports and renderer wiring

Daniel83de78bc449e
diff --git a/agents/seo-content.md b/agents/seo-content.md
index 07320ab..9331dbb 100644
--- a/agents/seo-content.md
+++ b/agents/seo-content.md
@@ -65,6 +65,13 @@ Provide:
## Fetching pages (v2.0.0)
-Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes summary fields including `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate); use `--output` or import `render_page.render_page()` when full raw/rendered HTML is required. SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+
+## Persistence Contract
+
+If `output_dir` is provided by the audit orchestrator, write:
+
+- `output_dir/findings/content.md`: E-E-A-T, readability, thin content, duplication, topical coverage, and AI citation findings
+- Structured JSON-compatible findings for `audit-data.json` under the Content Quality category
E-E-A-T scoring should run against `extracted_text` rather than `content` — trafilatura strips navigation chrome, footers, and cookie banners, so author bios and main-content trust signals score correctly without dilution.
diff --git a/agents/seo-ecommerce.md b/agents/seo-ecommerce.md
index 47c5854..3d03c88 100644
--- a/agents/seo-ecommerce.md
+++ b/agents/seo-ecommerce.md
@@ -18,7 +18,7 @@ When delegated tasks during an SEO audit or analysis:
1. Detect e-commerce signals: product schema, price elements, add-to-cart buttons,
shopping cart, product grids, Shopify/WooCommerce/Magento markers
-2. Analyze product pages using `scripts/fetch_page.py` and `scripts/parse_html.py`
+2. Analyze product pages using `scripts/render_page.py --mode auto` and `scripts/parse_html.py`
3. Validate Product schema against Google's required and recommended fields
4. If DataForSEO credentials available, fetch marketplace data via
`scripts/dataforseo_merchant.py`
diff --git a/agents/seo-performance.md b/agents/seo-performance.md
index 7f8ef59..cd4aa8d 100644
--- a/agents/seo-performance.md
+++ b/agents/seo-performance.md
@@ -25,7 +25,7 @@ Google evaluates the **75th percentile** of page visits, 75% of visits must meet
## When Analyzing Performance
1. Use PageSpeed Insights API if available
-2. Otherwise, analyze HTML source for common issues
+2. Use `python scripts/render_page.py <URL> --mode auto --json` before HTML/source inspection so SPA content is visible when needed
3. Provide specific, actionable optimization recommendations
4. Prioritize by expected impact
@@ -64,8 +64,11 @@ Google evaluates the **75th percentile** of page visits, 75% of visits must meet
## Tools
```bash
-# PageSpeed Insights API
-curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=API_KEY"
+# PageSpeed Insights API (uses header-based API key handling)
+python scripts/pagespeed_check.py URL --json
+
+# SPA-aware HTML/render inspection
+python scripts/render_page.py URL --mode auto --json
# Lighthouse CLI
npx lighthouse URL --output json
@@ -87,3 +90,10 @@ Provide:
- Core Web Vitals status (pass/fail per metric)
- Specific bottlenecks identified
- Prioritized recommendations with expected impact
+
+## Persistence Contract
+
+If `output_dir` is provided by the audit orchestrator, write:
+
+- `output_dir/findings/performance.md`: evidence, scores, bottlenecks, and recommendations
+- Structured JSON-compatible findings for `audit-data.json` under the Performance category
diff --git a/agents/seo-schema.md b/agents/seo-schema.md
index 3ee8009..e7b58f6 100644
--- a/agents/seo-schema.md
+++ b/agents/seo-schema.md
@@ -68,6 +68,13 @@ Provide:
## Fetching pages (v2.0.0)
-Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes summary fields including `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate); use `--output` or import `render_page.render_page()` when full raw/rendered HTML is required. SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+
+## Persistence Contract
+
+If `output_dir` is provided by the audit orchestrator, write:
+
+- `output_dir/findings/schema.md`: detected schema, validation errors, missing opportunities, and generated recommendations
+- Structured JSON-compatible findings for `audit-data.json` under the Schema / Structured Data category
For schema audits on SPA sites prefer `--mode always`: many sites inject JSON-LD client-side via React Helmet, Next/Head, or vue-meta, so the raw HTML will be empty of structured data even when the rendered DOM has the full graph. Compare `raw_content` vs `content` to confirm whether schema is server-rendered.
diff --git a/agents/seo-sxo.md b/agents/seo-sxo.md
index d86bcd7..a72af82 100644
--- a/agents/seo-sxo.md
+++ b/agents/seo-sxo.md
@@ -19,7 +19,7 @@ then comparing that against the target page.
### 1. Fetch and Parse Target Page
-- Fetch the target URL using `python scripts/fetch_page.py "<url>"` (SSRF protection)
+- Fetch the target URL using `python scripts/render_page.py "<url>" --mode auto --json` (SPA-aware SSRF-protected renderer)
- Parse with `python scripts/parse_html.py "<url>"` to extract SEO elements
- Identify: page type, title, H1, meta description, headings, word count, schema, CTAs, media
- If no keyword was provided, derive primary keyword from title + H1 overlap
@@ -85,7 +85,7 @@ Score the target page across 7 dimensions (100 points total):
## Pre-Delivery Checklist
Before presenting results, verify:
-- [ ] URL was fetched via scripts/fetch_page.py (not raw curl)
+- [ ] URL was fetched via scripts/render_page.py --mode auto (not raw curl)
- [ ] At least 5 SERP results were analyzed
- [ ] Page type classification uses the taxonomy reference
- [ ] User stories cite specific SERP signals
diff --git a/agents/seo-technical.md b/agents/seo-technical.md
index 8cb5342..a0c3f2b 100644
--- a/agents/seo-technical.md
+++ b/agents/seo-technical.md
@@ -53,4 +53,11 @@ Provide a structured report with:
## Fetching pages (v2.0.0)
-Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes `raw_content` (pre-JS), `content` (post-JS), `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate). SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+Use `python scripts/render_page.py <URL> --mode auto --json` for page HTML. `auto` does a raw fetch and only spins up Playwright when an SPA shell is detected; use `--mode always` to force a render or `--mode never` to skip Playwright entirely. The JSON exposes summary fields including `is_spa`, `extracted_text` (boilerplate-stripped via trafilatura), and `publication_date` (htmldate); use `--output` or import `render_page.render_page()` when full raw/rendered HTML is required. SSRF and DNS-rebinding protection live in `scripts/url_safety.py` — never call `requests.get` directly on user-supplied URLs.
+
+## Persistence Contract
+
+If `output_dir` is provided by the audit orchestrator, write:
+
+- `output_dir/findings/technical.md`: crawlability, indexability, security, URL, mobile, rendering, and agent-UX findings
+- Structured JSON-compatible findings for `audit-data.json` under the Technical SEO category
diff --git a/agents/seo-visual.md b/agents/seo-visual.md
index e44d823..0a1da6d 100644
--- a/agents/seo-visual.md
+++ b/agents/seo-visual.md
@@ -28,16 +28,9 @@ pip install playwright && playwright install chromium
Use the screenshot script (`scripts/capture_screenshot.py` in the plugin root) for browser automation:
-```python
-from playwright.sync_api import sync_playwright
-
-def capture(url, output_path, viewport_width=1920, viewport_height=1080):
- with sync_playwright() as p:
- browser = p.chromium.launch()
- page = browser.new_page(viewport={'width': viewport_width, 'height': viewport_height})
- page.goto(url, wait_until='networkidle')
- page.screenshot(path=output_path, full_page=False)
- browser.close()
+```bash
+python scripts/capture_screenshot.py URL --all --output screenshots/
+python scripts/render_page.py URL --mode auto --a11y-tree --json
```
## Viewports to Test
@@ -77,3 +70,11 @@ Provide:
- Mobile responsiveness assessment
- Above-the-fold content evaluation
- Specific issues with element locations
+
+## Persistence Contract
+
+If `output_dir` is provided by the audit orchestrator, write:
+
+- `output_dir/screenshots/desktop.png` and `output_dir/screenshots/mobile.png` when capture succeeds
+- `output_dir/findings/visual.md`: above-the-fold, mobile, layout, and accessibility-tree findings
+- Structured JSON-compatible findings for `audit-data.json` under the Visual category
diff --git a/scripts/google_report.py b/scripts/google_report.py
index bdcda82..fff3743 100644
--- a/scripts/google_report.py
+++ b/scripts/google_report.py
@@ -18,6 +18,7 @@ import json
import os
import sys
from datetime import datetime
+from html import escape
from pathlib import Path
from typing import Optional
@@ -1018,6 +1019,136 @@ def _build_toc(sections_info):
)
+def _coerce_items(value):
+ """Return a list for scalar-or-list audit fields."""
+ if value is None:
+ return []
+ if isinstance(value, list):
+ return value
+ return [value]
+
+
+def _finding_title(item):
+ if isinstance(item, dict):
+ return item.get("title") or item.get("issue") or item.get("name") or "Finding"
+ return str(item)
+
+
+def _finding_severity(item):
+ if isinstance(item, dict):
+ return str(item.get("severity", "Info"))
+ return "Info"
+
+
+def _finding_description(item):
+ if isinstance(item, dict):
+ return item.get("description") or item.get("details") or item.get("evidence") or ""
+ return ""
+
+
+def _build_full_audit_categories(data, section_num=2):
+ """Build category sections for audit-data.json style reports."""
+ categories = _coerce_items(data.get("categories"))
+ if not categories:
+ return ""
+
+ lines = []
+ lines.append(f'\n<!-- {"=" * 55} {section_num}. AUDIT CATEGORIES {"=" * 3} -->')
+ lines.append('<div class="section">')
+ lines.append(' <div class="section-header">')
+ lines.append(f' <h2>{section_num}. Audit Categories</h2>')
+ lines.append(' </div>')
+ lines.append('')
+
+ for idx, category in enumerate(categories, 1):
+ if not isinstance(category, dict):
+ continue
+ name = escape(str(category.get("name", f"Category {idx}")))
+ score = category.get("score")
+ lines.append(f' <h3>{section_num}.{idx} {name}</h3>')
+ if score is not None:
+ try:
+ score_val = float(score)
+ cls = "status-pass" if score_val >= 80 else ("status-warn" if score_val >= 50 else "status-fail")
+ lines.append(f' <p><strong>Score:</strong> <span class="{cls}">{score_val:g}/100</span></p>')
+ except (TypeError, ValueError):
+ lines.append(f' <p><strong>Score:</strong> {escape(str(score))}</p>')
+
+ what_works = _coerce_items(category.get("what_works"))
+ if what_works:
+ lines.append(' <h4>What Works</h4>')
+ lines.append(' <ul>')
+ for item in what_works:
+ lines.append(f' <li>{escape(str(item))}</li>')
+ lines.append(' </ul>')
+
+ findings = _coerce_items(category.get("findings"))
+ if findings:
+ lines.append(' <h4>Findings</h4>')
+ for finding in findings:
+ title = escape(_finding_title(finding))
+ severity = escape(_finding_severity(finding))
+ desc = escape(_finding_description(finding))
+ recommendation = ""
+ if isinstance(finding, dict) and finding.get("recommendation"):
+ recommendation = escape(str(finding["recommendation"]))
+ severity_class = _rating_css_class(severity)
+ lines.append(' <div class="action-item medium">')
+ lines.append(f' <h4>{title} <span class="{severity_class}">{severity}</span></h4>')
+ if desc:
+ lines.append(f' <p>{desc}</p>')
+ if recommendation:
+ lines.append(f' <p><strong>Recommendation:</strong> {recommendation}</p>')
+ lines.append(' </div>')
+ lines.append(' <hr class="divider">')
+
+ lines.append('</div>')
+ return "\n".join(lines)
+
+
+def _build_audit_action_plan(data, section_num=5):
+ """Build a four-phase or custom action-plan section."""
+ action_plan = data.get("action_plan", {})
+ phases = []
+ if isinstance(action_plan, dict):
+ phases = _coerce_items(action_plan.get("phases") or action_plan.get("roadmap"))
+ elif isinstance(action_plan, list):
+ phases = action_plan
+ if not phases:
+ return ""
+
+ lines = []
+ lines.append(f'\n<!-- {"=" * 55} {section_num}. ACTION PLAN {"=" * 3} -->')
+ lines.append('<div class="section">')
+ lines.append(' <div class="section-header">')
+ lines.append(f' <h2>{section_num}. Action Plan</h2>')
+ lines.append(' </div>')
+ lines.append('')
+
+ for idx, phase in enumerate(phases, 1):
+ if isinstance(phase, dict):
+ name = phase.get("name") or phase.get("phase") or f"Phase {idx}"
+ timeframe = phase.get("timeframe") or phase.get("timeline") or ""
+ items = _coerce_items(phase.get("items") or phase.get("actions"))
+ else:
+ name = f"Phase {idx}"
+ timeframe = ""
+ items = [phase]
+ lines.append(' <div class="roadmap-phase">')
+ heading = escape(str(name))
+ if timeframe:
+ heading = f'{heading} <span class="effort">{escape(str(timeframe))}</span>'
+ lines.append(f' <h4>{heading}</h4>')
+ lines.append(' <ul>')
+ for item in items:
+ lines.append(f' <li>{escape(str(item))}</li>')
+ lines.append(' </ul>')
+ lines.append(' </div>')
+
+ lines.append('</div>')
+ return "\n".join(lines)
+
+
def _build_executive_summary(domain, timestamp, data, report_type):
"""Build the Executive Summary section with metric cards, issues, and wins."""
lines = []
@@ -1028,16 +1159,30 @@ def _build_executive_summary(domain, timestamp, data, report_type):
lines.append(' </div>')
lines.append('')
+ summary = data.get("summary", {}) if isinstance(data.get("summary"), dict) else {}
+
# Context paragraph
- lines.append(f' <p>This report presents a comprehensive Google SEO analysis of '
- f'<strong>{domain}</strong>, generated on {timestamp}. '
- f'Data was collected from Google PageSpeed Insights, Chrome User Experience '
- f'Report (CrUX), Google Search Console, and the URL Inspection API as available.</p>')
+ if summary:
+ business_type = summary.get("business_type")
+ type_text = f' for a <strong>{escape(str(business_type))}</strong> site' if business_type else ""
+ lines.append(f' <p>This report presents a comprehensive SEO audit of '
+ f'<strong>{domain}</strong>{type_text}, generated on {timestamp}. '
+ f'Findings combine technical, content, schema, performance, visual, '
+ f'and search-readiness evidence as available.</p>')
+ else:
+ lines.append(f' <p>This report presents a comprehensive Google SEO analysis of '
+ f'<strong>{domain}</strong>, generated on {timestamp}. '
+ f'Data was collected from Google PageSpeed Insights, Chrome User Experience '
+ f'Report (CrUX), Google Search Console, and the URL Inspection API as available.</p>')
lines.append('')
# Metric cards row
cards = []
+ health_score = summary.get("health_score")
+ if health_score is not None:
+ cards.append(("health", f"{health_score}/100", "SEO Health Score", _score_color(float(health_score))))
+
# PSI performance score
psi = data.get("psi", {})
mobile = psi.get("psi", {}).get("mobile", psi) if isinstance(psi, dict) else {}
@@ -1080,6 +1225,11 @@ def _build_executive_summary(domain, timestamp, data, report_type):
# Critical issues box
issues = []
+ for item in _coerce_items(summary.get("top_findings")):
+ severity = _finding_severity(item)
+ title = _finding_title(item)
+ issues.append(f'<strong>{escape(severity)}:</strong> {escape(title)}')
+
failed_audits = mobile.get("failed_audits", [])
if failed_audits:
top_fail = sorted(failed_audits, key=lambda a: a.get("score", 1))[:3]
@@ -1108,6 +1258,9 @@ def _build_executive_summary(domain, timestamp, data, report_type):
# Quick wins box
wins = []
+ for item in _coerce_items(summary.get("quick_wins")):
+ wins.append(escape(str(item)))
+
qw = gsc.get("quick_wins", [])
if qw:
wins.append(f'{len(qw)} search queries at positions 4-10 with high impressions '
@@ -2029,13 +2182,17 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):
psi = data.get("psi", {})
mobile = psi.get("psi", {}).get("mobile", psi) if isinstance(psi, dict) else {}
perf_score = mobile.get("lighthouse_scores", {}).get("performance") if isinstance(mobile, dict) else None
+ summary = data.get("summary", {}) if isinstance(data.get("summary"), dict) else {}
+ health_score = summary.get("health_score")
+ display_score = health_score if health_score is not None else perf_score
+ has_audit_schema = bool(summary or data.get("categories") or data.get("action_plan"))
sections.append(_build_title_page(
- domain, "Google SEO Intelligence Report",
+ domain, "Full SEO Audit Report" if has_audit_schema else "Google SEO Intelligence Report",
"Comprehensive Analysis",
- score=perf_score,
- score_label="Lighthouse Performance Score" if perf_score else None,
- meta_items=[timestamp, "All Google APIs"],
+ score=display_score,
+ score_label="SEO Health Score" if health_score is not None else ("Lighthouse Performance Score" if perf_score else None),
+ meta_items=[timestamp, "Full Audit"],
))
# Build TOC dynamically based on available data
@@ -2045,6 +2202,14 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):
]},
]
sec_num = 2
+ if data.get("categories"):
+ toc_sections.append({
+ "num": sec_num, "title": "Audit Categories", "subs": [
+ "What Works",
+ "Findings by Severity",
+ ],
+ })
+ sec_num += 1
if data.get("psi") or data.get("crux"):
toc_sections.append({
"num": sec_num, "title": "Core Web Vitals &amp; Performance",
@@ -2070,11 +2235,18 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):
],
})
sec_num += 1
- toc_sections.append({
- "num": sec_num, "title": "Recommendations", "subs": [
- "Prioritized Action Items",
- ],
- })
+ if data.get("action_plan"):
+ toc_sections.append({
+ "num": sec_num, "title": "Action Plan", "subs": [
+ "Phased Roadmap",
+ ],
+ })
+ else:
+ toc_sections.append({
+ "num": sec_num, "title": "Recommendations", "subs": [
+ "Prioritized Action Items",
+ ],
+ })
rec_num = sec_num
sec_num += 1
toc_sections.append({
@@ -2085,6 +2257,10 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):
sections.append(_build_executive_summary(domain, timestamp, data, report_type))
current_sec = 2
+ if data.get("categories"):
+ sections.append(_build_full_audit_categories(data, section_num=current_sec))
+ current_sec += 1
+
if data.get("psi") or data.get("crux"):
cwv_html, fig_num = _build_cwv_section(
data.get("psi", {}), data.get("crux", {}), chart_paths,
@@ -2109,7 +2285,11 @@ def generate_report(report_type, data, domain, output_dir, output_format="pdf"):
sections.append(idx_html)
current_sec += 1
- sections.append(_build_recommendations(data, section_num=rec_num))
+ action_html = _build_audit_action_plan(data, section_num=rec_num)
+ if action_html:
+ sections.append(action_html)
+ else:
+ sections.append(_build_recommendations(data, section_num=rec_num))
sections.append(_build_methodology_footer(domain, timestamp))
# ── Assemble Final HTML ──────────────────────────────────────────────────
diff --git a/skills/seo-audit/SKILL.md b/skills/seo-audit/SKILL.md
index 83ef2a6..f5187d5 100644
--- a/skills/seo-audit/SKILL.md
+++ b/skills/seo-audit/SKILL.md
@@ -14,7 +14,7 @@ metadata:
## Process
-1. **Fetch homepage**: use `scripts/fetch_page.py` to retrieve HTML
+1. **Render homepage**: use `python scripts/render_page.py <url> --mode auto --json` to capture raw HTML, rendered HTML, extracted text, SPA status, and accessibility data when needed
2. **Detect business type**: analyze homepage signals per seo orchestrator
3. **Crawl site**: follow internal links up to 500 pages, respect robots.txt
4. **Delegate to subagents** (if available, otherwise run inline sequentially):
@@ -34,7 +34,8 @@ metadata:
- `seo-drift` -- Drift analysis: compare against stored baseline (spawn when drift baseline exists for the URL via `python scripts/drift_history.py <url>`)
- `seo-ecommerce` -- Product schema, marketplace intelligence (spawn when E-commerce industry detected)
5. **Score** -- aggregate into SEO Health Score (0-100)
-6. **Report** -- generate prioritized action plan
+6. **Persist audit artifacts** -- write all outputs under `{domain}-audit/`
+7. **Report** -- generate prioritized action plan and optional PDF/HTML report
## Crawl Configuration
@@ -49,11 +50,55 @@ Delay between requests: 1 second
## Output Files
-- `FULL-AUDIT-REPORT.md`: Comprehensive findings
-- `ACTION-PLAN.md`: Prioritized recommendations (Critical > High > Medium > Low)
-- `screenshots/`: Desktop + mobile captures (if Playwright available)
+- `{domain}-audit/FULL-AUDIT-REPORT.md`: Comprehensive findings
+- `{domain}-audit/ACTION-PLAN.md`: Prioritized recommendations (Critical > High > Medium > Low)
+- `{domain}-audit/audit-data.json`: Structured audit envelope for report generation
+- `{domain}-audit/findings/*.md`: Per-category specialist findings (`technical.md`, `content.md`, `schema.md`, `performance.md`, `visual.md`, etc.)
+- `{domain}-audit/screenshots/`: Desktop + mobile captures (if Playwright available)
- **PDF Report** (recommended): Generate a professional A4 PDF using `scripts/google_report.py --type full`. This produces a white-cover enterprise report with TOC, executive summary, charts (Lighthouse gauges, query bars, index donut), metric cards, threshold tables, prioritized recommendations with effort estimates, and implementation roadmap. Always offer PDF generation after completing an audit.
+## Structured Audit Data Envelope
+
+Write `{domain}-audit/audit-data.json` with this shape so `python scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain>` can generate a report even when Google API data is unavailable:
+
+```json
+{
+ "summary": {
+ "health_score": 0,
+ "business_type": "detected type",
+ "top_findings": [],
+ "quick_wins": []
+ },
+ "categories": [
+ {
+ "name": "Technical SEO",
+ "score": 0,
+ "what_works": [],
+ "findings": [
+ {
+ "title": "Finding title",
+ "severity": "Critical|High|Medium|Low|Info",
+ "description": "Evidence-backed detail",
+ "recommendation": "Specific fix"
+ }
+ ]
+ }
+ ],
+ "action_plan": {
+ "phases": [
+ {"name": "Phase 1: Critical Fixes", "timeframe": "Week 1", "items": []},
+ {"name": "Phase 2: High-Impact Improvements", "timeframe": "Weeks 2-3", "items": []},
+ {"name": "Phase 3: Content & Authority", "timeframe": "Month 2", "items": []},
+ {"name": "Phase 4: Monitoring & Iteration", "timeframe": "Ongoing", "items": []}
+ ]
+ },
+ "artifacts": {
+ "findings_dir": "findings/",
+ "screenshots_dir": "screenshots/"
+ }
+}
+```
+
## Scoring Weights
| Category | Weight |
diff --git a/skills/seo-cluster/SKILL.md b/skills/seo-cluster/SKILL.md
index e4e0638..f86476b 100644
--- a/skills/seo-cluster/SKILL.md
+++ b/skills/seo-cluster/SKILL.md
@@ -312,7 +312,7 @@ After cluster planning or execution completes, offer:
## Security
-- All URLs fetched via `python scripts/fetch_page.py` (SSRF protection via `validate_url()`)
+- All URLs fetched via `python scripts/render_page.py --mode auto` (SPA-aware SSRF protection via `url_safety`)
- No credentials stored or transmitted
- Output files contain no PII or API keys
- DataForSEO cost checks run before every API call
diff --git a/skills/seo-ecommerce/SKILL.md b/skills/seo-ecommerce/SKILL.md
index 828ada5..d256468 100644
--- a/skills/seo-ecommerce/SKILL.md
+++ b/skills/seo-ecommerce/SKILL.md
@@ -42,7 +42,7 @@ Fetch and parse any product page for on-page SEO quality.
### Workflow
```
-1. python scripts/fetch_page.py <url> → raw HTML
+1. python scripts/render_page.py <url> --mode auto → raw/rendered HTML
2. python scripts/parse_html.py --url <url> → SEO elements
3. Analyze product-specific signals (below)
```
diff --git a/skills/seo-sxo/SKILL.md b/skills/seo-sxo/SKILL.md
index d7defa0..027022f 100644
--- a/skills/seo-sxo/SKILL.md
+++ b/skills/seo-sxo/SKILL.md
@@ -43,7 +43,7 @@ well-optimized it is.
### Step 1: Target Acquisition
-1. Fetch the target URL via `scripts/fetch_page.py` (SSRF-safe)
+1. Fetch the target URL via `scripts/render_page.py --mode auto` (SPA-aware and SSRF-safe)
2. Parse with `scripts/parse_html.py` to extract: title, H1, meta description,
headings hierarchy, word count, schema markup, CTAs, media elements
3. If no keyword provided, extract primary keyword from title tag + H1 overlap
@@ -244,7 +244,7 @@ The SXO score is **separate** from the main SEO Health Score.
## Quality Checklist
Before delivering results, verify:
-- [ ] Target URL was fetched via `scripts/fetch_page.py` (not raw curl/fetch)
+- [ ] Target URL was fetched via `scripts/render_page.py --mode auto` (not raw curl/fetch)
- [ ] Page type classification uses taxonomy from references
- [ ] At least 5 SERP results were analyzed
- [ ] User stories cite specific SERP signals as evidence
diff --git a/tests/test_audit_instructions.py b/tests/test_audit_instructions.py
new file mode 100644
index 0000000..1f0a6e7
--- /dev/null
+++ b/tests/test_audit_instructions.py
@@ -0,0 +1,50 @@
+"""Static instruction guards for full audit persistence and SPA wiring."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_seo_audit_starts_with_render_page_auto() -> None:
+ text = (REPO_ROOT / "skills" / "seo-audit" / "SKILL.md").read_text(encoding="utf-8")
+ process = text[text.index("## Process"):text.index("## Crawl Configuration")]
+ assert "scripts/render_page.py" in process
+ assert "--mode auto" in process
+ assert "scripts/fetch_page.py` to retrieve HTML" not in process
+
+
+def test_seo_audit_requires_persistent_artifacts() -> None:
+ text = (REPO_ROOT / "skills" / "seo-audit" / "SKILL.md").read_text(encoding="utf-8")
+ for artifact in (
+ "FULL-AUDIT-REPORT.md",
+ "ACTION-PLAN.md",
+ "audit-data.json",
+ "findings/",
+ "screenshots/",
+ ):
+ assert artifact in text
+ assert "{domain}-audit" in text
+
+
+def test_audit_agents_use_renderer_or_capture_script() -> None:
+ expectations = {
+ "seo-performance.md": "render_page.py",
+ "seo-visual.md": "capture_screenshot.py",
+ "seo-technical.md": "render_page.py",
+ "seo-content.md": "render_page.py",
+ "seo-schema.md": "render_page.py",
+ }
+ for filename, marker in expectations.items():
+ text = (REPO_ROOT / "agents" / filename).read_text(encoding="utf-8")
+ assert marker in text, f"{filename} must mention {marker}"
+
+
+def test_audit_agents_document_output_dir_findings_contract() -> None:
+ for filename in ("seo-performance.md", "seo-visual.md", "seo-technical.md",
+ "seo-content.md", "seo-schema.md"):
+ text = (REPO_ROOT / "agents" / filename).read_text(encoding="utf-8")
+ assert "output_dir" in text
+ assert "findings/" in text
diff --git a/tests/test_google_report_full_audit.py b/tests/test_google_report_full_audit.py
new file mode 100644
index 0000000..a3e72df
--- /dev/null
+++ b/tests/test_google_report_full_audit.py
@@ -0,0 +1,89 @@
+"""Full audit report generation from non-Google audit data."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+_SCRIPTS = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
+if _SCRIPTS not in sys.path:
+ sys.path.insert(0, _SCRIPTS)
+
+import google_report # noqa: E402
+
+
+def test_full_audit_html_includes_summary_categories_and_roadmap(tmp_path: Path) -> None:
+ data = {
+ "summary": {
+ "health_score": 82,
+ "business_type": "SaaS",
+ "top_findings": [
+ {"title": "Canonical mismatch", "severity": "Critical"},
+ "Thin service pages",
+ ],
+ "quick_wins": ["Add missing meta descriptions"],
+ },
+ "categories": [
+ {
+ "name": "Technical SEO",
+ "score": 74,
+ "what_works": ["HTTPS is enabled", "Robots.txt is reachable"],
+ "findings": [
+ {
+ "title": "Canonical mismatch",
+ "severity": "Critical",
+ "description": "Homepage canonical points to a staging URL.",
+ "recommendation": "Set canonical to the production HTTPS URL.",
+ }
+ ],
+ },
+ {
+ "name": "Content Quality",
+ "score": 68,
+ "what_works": ["Clear product positioning"],
+ "findings": [
+ {
+ "title": "Thin comparison pages",
+ "severity": "High",
+ "description": "Several pages have fewer than 300 words.",
+ }
+ ],
+ },
+ ],
+ "action_plan": {
+ "phases": [
+ {
+ "name": "Phase 1: Indexing Fixes",
+ "timeframe": "Week 1",
+ "items": ["Fix canonical mismatch", "Resubmit sitemap"],
+ },
+ {
+ "name": "Phase 2: Content Expansion",
+ "timeframe": "Weeks 2-3",
+ "items": ["Expand comparison page copy"],
+ },
+ ]
+ },
+ }
+
+ result = google_report.generate_report(
+ "full",
+ data,
+ "example.com",
+ tmp_path,
+ output_format="html",
+ )
+
+ assert result["error"] is None
+ html_path = Path(result["files"][0])
+ html = html_path.read_text(encoding="utf-8")
+ assert "Executive Summary" in html
+ assert "SaaS" in html
+ assert "Technical SEO" in html
+ assert "What Works" in html
+ assert "Canonical mismatch" in html
+ assert "Action Plan" in html
+ assert "Phase 1: Indexing Fixes" in html
+ assert "Content Quality" in html