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.

chore(hygiene): untrack internal artifacts, normalize python3, refresh docs

Danielbd0cbefab7cc
diff --git a/.gitignore b/.gitignore
index 38d1c85..2568f30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -162,3 +162,9 @@ presentations/
# Internal implementation plans / specs (working notes, not user docs)
docs/superpowers/
+
+# Internal project-management records (private; must not ship to public origin)
+MEMORY.md
+docs/BACKLOG-COMPLETION-REPORT-v2.md
+docs/*COMPLETION-REPORT*.md
+docs/VERIFICATION-AUDIT*.md
diff --git a/AGENTS.md b/AGENTS.md
index 06aa91f..0a5e234 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ Every skill in `skills/*/SKILL.md` is authored to a portable subset of the
Claude Code skill spec. Validate compatibility with your harness via:
```bash
-python scripts/portability_check.py
+python3 scripts/portability_check.py
```
The check confirms each `SKILL.md` has the minimum frontmatter every harness
@@ -97,19 +97,19 @@ provide execution capabilities.
**Running scripts directly** (Cursor doesn't have MCP):
```bash
# Page fetching with SSRF protection
-python scripts/fetch_page.py https://example.com
+python3 scripts/fetch_page.py https://example.com
# HTML parsing for SEO elements
-python scripts/parse_html.py https://example.com
+python3 scripts/parse_html.py https://example.com
# PageSpeed Insights
-python scripts/pagespeed_check.py https://example.com --json
+python3 scripts/pagespeed_check.py https://example.com --json
# Drift baseline
-python scripts/drift_baseline.py https://example.com
+python3 scripts/drift_baseline.py https://example.com
# DataForSEO (requires credentials)
-DATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass python scripts/dataforseo_merchant.py search "keyword"
+DATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass python3 scripts/dataforseo_merchant.py search "keyword"
```
**Cursor Cloud gotchas:**
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4cfd142..1a1c5a7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -609,7 +609,7 @@ release. v2 will be a separate design conversation:
### Fixed
- **YAML frontmatter parsing**: Removed HTML comments before `---` delimiter in 8 files (skills: seo-content, seo-images, seo-programmatic, seo-schema, seo-technical; agents: seo-content, seo-performance, seo-technical). Thanks @kylewhirl for identifying this in the codex-seo fork.
-- **Windows installer**: Merged @kfrancis improvements -- `python -m pip`, `py -3` launcher fallback, requirements.txt persistence, non-fatal subagent copy, better error diagnostics (PR #6)
+- **Windows installer**: Merged @kfrancis improvements -- `python3 -m pip`, `py -3` launcher fallback, requirements.txt persistence, non-fatal subagent copy, better error diagnostics (PR #6)
- **requirements.txt missing after install**: Now copied to skill directory so users can retry (#1)
### Changed
diff --git a/CLAUDE.md b/CLAUDE.md
index f955906..c0f4570 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,7 +21,7 @@ claude-seo/
CONTRIBUTORS.md # Community credits (Pro Hub Challenge)
AGENTS.md # Multi-platform agent instructions (Cursor, Antigravity)
.claude-plugin/
- plugin.json # Plugin manifest (v1.9.8)
+ plugin.json # Plugin manifest (v2.1.0)
marketplace.json # Marketplace catalog for distribution
skills/ # 25 sub-skills (auto-discovered)
seo/ # Main orchestrator skill
@@ -82,7 +82,7 @@ claude-seo/
seo-ecommerce.md # E-commerce SEO analysis
hooks/ # Quality gate hooks
hooks.json # PostToolUse schema validation
- scripts/ # Python execution scripts (30 tracked + 2 dev-only)
+ scripts/ # Python execution scripts (50 tracked + dev-only helpers)
google_auth.py # Credential management (OAuth, SA, API key, 4-tier detection)
backlinks_auth.py # Backlink API credential management (Moz, Bing)
moz_api.py # Moz Link Explorer API (DA/PA, spam, domains, anchors)
@@ -111,6 +111,28 @@ claude-seo/
dataforseo_merchant.py # Google Shopping / Amazon data fetching
dataforseo_normalize.py # DataForSEO response normalization utility
sync_flow.py # FLOW prompt library sync (GitHub API, CC BY 4.0 headers, --dry-run, --ref)
+ url_safety.py # Canonical URL/SSRF safety module (validate, DNS-pin, safe fetch)
+ render_page.py # Shared headless renderer (SPA-aware, Playwright)
+ lcp_subparts.py # LCP subparts breakdown via CrUX API
+ preload_check.py # Speculation Rules / bfcache / prerender / preload detector
+ agent_ux_check.py # Agent-friendly page auditor
+ content_quality.py # QRG-aligned content quality detector
+ content_humanize.py # AI-pattern remover (rewrites AI-typical phrasing)
+ content_verify.py # Claim extractor + citation-gap detector
+ schema_generate.py # JSON-LD generators for high-leverage v2 schema types
+ schema_ecommerce_validate.py # Product schema validator (merchant-listing requirements)
+ iptc_ai_label.py # IPTC DigitalSourceType audit/injection for AI imagery
+ parasite_risk.py # Parasite-SEO risk scanner
+ gbp_deprecation_lint.py # GBP feature-deprecation linter
+ domain_history.py # Expired-domain heritage check
+ seo_updates.py # Primary-source Google updates query tool
+ indexnow_submit.py # IndexNow submitter
+ ucp_check.py # UCP (Universal Commerce Protocol) profile auditor
+ unlighthouse_run.py # Unlighthouse CLI wrapper (site-wide Lighthouse)
+ validate_backlink_report.py # Backlink report validation
+ portability_check.py # Cross-platform portability lint for SKILL.md files
+ release_sign.py # SHA-256 manifest generator for release signing
+ verify_release.py # Verify checkout integrity against a release manifest
mobile_analysis.py # Mobile rendering analysis (gitignored, dev-only)
schema/ # Schema.org JSON-LD templates
extensions/ # Optional add-on install helpers
@@ -160,7 +182,7 @@ claude-seo/
- Follow kebab-case naming for all skill directories
- Agents invoked via Agent tool, never via Bash
- Python dependencies install into `~/.claude/skills/seo/.venv/`
-- Test with `python -m pytest tests/` after changes (if applicable)
+- Test with `python3 -m pytest tests/` after changes (if applicable)
## Security Rules
diff --git a/MEMORY.md b/MEMORY.md
deleted file mode 100644
index 312893e..0000000
--- a/MEMORY.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Project Memory
-
-- 2026-06-12: Completed the v2 open PR/issue backlog sweep with independent verification; final evidence is recorded in `docs/BACKLOG-COMPLETION-REPORT-v2.md`.
diff --git a/README.md b/README.md
index d8b442a..5851c03 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-![Claude SEO terminal banner: animated CRT command palette with /seo audit, /seo schema, /seo geo, system line showing 25 sub-skills, 271 tests, 8 MCP servers](assets/banner.svg)
+![Claude SEO terminal banner: animated CRT command palette with /seo audit, /seo schema, /seo geo, system line showing 25 sub-skills, 316 tests, 8 MCP servers](assets/banner.svg)
# Claude SEO: SEO Analysis Skill for Claude Code
@@ -8,7 +8,7 @@
[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-blue)](https://claude.ai/claude-code)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/github/v/release/AgriciDaniel/claude-seo)](https://github.com/AgriciDaniel/claude-seo/releases)
-[![Tests](https://img.shields.io/badge/tests-271%20passing-brightgreen)](tests/)
+[![Tests](https://img.shields.io/badge/tests-316%20passing-brightgreen)](tests/)
[![Community](https://img.shields.io/badge/AI%20Marketing%20Hub-Pro%20community-purple)](https://www.skool.com/ai-marketing-hub-pro)
> **Two versions of this skill.**
@@ -472,7 +472,7 @@ MIT License. See [LICENSE](LICENSE) for details.
## Contributing
-Contributions welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting PRs. The project enforces a per-PR audit gate covering manifest consistency (14 assertions), the test suite (271 passing), and an 8-dimension security review before any merge to `main`.
+Contributions welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting PRs. The project enforces a per-PR audit gate covering manifest consistency (14 assertions), the test suite (316 passing), and an 8-dimension security review before any merge to `main`.
---
diff --git a/agents/seo-backlinks.md b/agents/seo-backlinks.md
index 1df4aad..d71a0d0 100644
--- a/agents/seo-backlinks.md
+++ b/agents/seo-backlinks.md
@@ -8,7 +8,7 @@ tools: Read, Bash, Write, Glob, Grep
You are a backlink profile analyst. When delegated tasks during an SEO audit:
-1. Check credentials: `python scripts/backlinks_auth.py --check --json`
+1. Check credentials: `python3 scripts/backlinks_auth.py --check --json`
2. Determine tier (0 = CC+verify, 1 = +Moz, 2 = +Bing, 3 = +DataForSEO)
3. Run all available sources for the target domain
4. Merge results with confidence weighting
@@ -17,27 +17,27 @@ You are a backlink profile analyst. When delegated tasks during an SEO audit:
## Tier-Based Workflow
### Tier 0 (Always Available — No Config Needed)
-- Common Crawl domain metrics: `python scripts/commoncrawl_graph.py <domain> --json`
+- Common Crawl domain metrics: `python3 scripts/commoncrawl_graph.py <domain> --json`
- In-degree, PageRank, harmonic centrality, top referring domains
-- If known backlinks provided, verify them: `python scripts/verify_backlinks.py --target <url> --links <file> --json`
+- If known backlinks provided, verify them: `python3 scripts/verify_backlinks.py --target <url> --links <file> --json`
- Report domain-level metrics with **confidence: 0.50** note
- At Tier 0, fewer than 4 scoring factors have data — report **INSUFFICIENT DATA**, not a numeric score
- Never produce a misleading numeric score when most factors lack data sources
### Tier 1 (+ Moz API)
- All Tier 0 checks
-- Moz URL metrics: `python scripts/moz_api.py metrics <url> --json`
+- Moz URL metrics: `python3 scripts/moz_api.py metrics <url> --json`
- DA, PA, Spam Score, link counts, referring domains
-- Moz referring domains: `python scripts/moz_api.py domains <url> --json`
-- Moz anchor text: `python scripts/moz_api.py anchors <url> --json`
-- Moz top pages: `python scripts/moz_api.py pages <domain> --json`
+- Moz referring domains: `python3 scripts/moz_api.py domains <url> --json`
+- Moz anchor text: `python3 scripts/moz_api.py anchors <url> --json`
+- Moz top pages: `python3 scripts/moz_api.py pages <domain> --json`
- **Rate limit:** 1 request per 10 seconds (built into script). Plan calls carefully.
- Report metrics with **confidence: 0.85** note
### Tier 2 (+ Bing Webmaster)
- All Tier 1 checks
-- Bing inbound links: `python scripts/bing_webmaster.py links <url> --json`
-- For competitor gap: `python scripts/bing_webmaster.py compare <url1> <url2> --json`
+- Bing inbound links: `python3 scripts/bing_webmaster.py links <url> --json`
+- For competitor gap: `python3 scripts/bing_webmaster.py compare <url1> <url2> --json`
- Report with **confidence: 0.70** for Bing data
- Bing's unique competitor comparison is especially valuable for gap analysis
@@ -87,7 +87,7 @@ Before returning results, run the automated validator AND manual checks.
### Step 1: Automated validation
Save all collected data to a JSON file and run:
```bash
-python scripts/validate_backlink_report.py --report report_data.json --json
+python3 scripts/validate_backlink_report.py --report report_data.json --json
```
The validator checks: schema claims, JS false negatives, H1 accuracy, reciprocal links,
CC interpretation, and health score sufficiency. If status is "FAIL", fix errors before proceeding.
@@ -110,7 +110,7 @@ If any check fails, fix the report before returning it.
## 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 `python3 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.
Backlink verification (`/seo backlinks verify`) primarily reads outbound `<a>` tags, which are reliably present in raw HTML. `--mode never` is the right choice for speed on bulk verification jobs.
diff --git a/agents/seo-content.md b/agents/seo-content.md
index 9331dbb..3c2f4c2 100644
--- a/agents/seo-content.md
+++ b/agents/seo-content.md
@@ -65,7 +65,7 @@ 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 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.
+Use `python3 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
diff --git a/agents/seo-drift.md b/agents/seo-drift.md
index 5ea50ee..6eaadbb 100644
--- a/agents/seo-drift.md
+++ b/agents/seo-drift.md
@@ -17,10 +17,10 @@ elements by comparing current page state against stored baselines.
## Tools
All page fetching goes through the project's existing scripts with SSRF protection:
-- `python scripts/drift_baseline.py <url>` -- capture a new baseline
-- `python scripts/drift_compare.py <url>` -- compare current state to baseline
-- `python scripts/drift_history.py <url>` -- show change history
-- `python scripts/drift_report.py <file> --output report.html` -- generate HTML report
+- `python3 scripts/drift_baseline.py <url>` -- capture a new baseline
+- `python3 scripts/drift_compare.py <url>` -- compare current state to baseline
+- `python3 scripts/drift_history.py <url>` -- show change history
+- `python3 scripts/drift_report.py <file> --output report.html` -- generate HTML report
Never use curl, wget, or raw HTTP requests. All fetching is handled by
`scripts/fetch_page.py` internally, which validates URLs against private/loopback
diff --git a/agents/seo-ecommerce.md b/agents/seo-ecommerce.md
index 6f754df..36abf53 100644
--- a/agents/seo-ecommerce.md
+++ b/agents/seo-ecommerce.md
@@ -27,7 +27,7 @@ When delegated tasks during an SEO audit or analysis:
Before ANY DataForSEO Merchant API call:
```bash
-python scripts/dataforseo_costs.py check <endpoint>
+python3 scripts/dataforseo_costs.py check <endpoint>
```
Only proceed if `"status": "approved"`. If `"needs_approval"`, surface the cost
@@ -36,7 +36,7 @@ the limitation.
After each API call, log the cost:
```bash
-python scripts/dataforseo_costs.py log <endpoint> <actual_cost>
+python3 scripts/dataforseo_costs.py log <endpoint> <actual_cost>
```
## Analysis Priorities
@@ -65,7 +65,7 @@ Match existing claude-seo patterns:
## 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 `python3 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.
E-commerce sites overwhelmingly inject product schema client-side (Shopify, Magento PWA, headless commerce on Next.js). Prefer `--mode always` for product page audits and compare `raw_content` vs `content` to confirm whether the JSON-LD is server-rendered.
diff --git a/agents/seo-geo.md b/agents/seo-geo.md
index 7414290..9369e12 100644
--- a/agents/seo-geo.md
+++ b/agents/seo-geo.md
@@ -65,7 +65,7 @@ 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 `python3 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.
AI citation analysis benefits from the `extracted_text` field — passage-level scoring should run against trafilatura's boilerplate-stripped output, not the full HTML, so navigation chrome and footers don't dilute the signal.
diff --git a/agents/seo-google.md b/agents/seo-google.md
index 9159fc9..cd1a642 100644
--- a/agents/seo-google.md
+++ b/agents/seo-google.md
@@ -8,7 +8,7 @@ tools: Read, Bash, Write, Glob, Grep # Write needed for report/data file output
You are a Google SEO API data analyst. When delegated tasks during an SEO audit:
-1. Check credentials: `python scripts/google_auth.py --check --json`
+1. Check credentials: `python3 scripts/google_auth.py --check --json`
2. Determine tier (0 = API key, 1 = + service account, 2 = + GA4)
3. Execute tier-appropriate analysis
4. Format output to match claude-seo conventions
@@ -16,20 +16,20 @@ You are a Google SEO API data analyst. When delegated tasks during an SEO audit:
## Tier-Based Workflow
### Tier 0 (API Key Only)
-- Run PSI + CrUX on homepage: `python scripts/pagespeed_check.py <url> --json`
-- Run CrUX History for origin: `python scripts/crux_history.py <origin> --origin --json`
+- Run PSI + CrUX on homepage: `python3 scripts/pagespeed_check.py <url> --json`
+- Run CrUX History for origin: `python3 scripts/crux_history.py <origin> --origin --json`
- Report CWV field data with traffic-light ratings
### Tier 1 (+ Service Account)
- All Tier 0 checks
-- GSC top queries/pages (28 days): `python scripts/gsc_query.py --property <prop> --json`
-- URL Inspection on homepage + key pages: `python scripts/gsc_inspect.py <url> --json`
-- GSC sitemap status: `python scripts/gsc_query.py sitemaps --property <prop> --json`
+- GSC top queries/pages (28 days): `python3 scripts/gsc_query.py --property <prop> --json`
+- URL Inspection on homepage + key pages: `python3 scripts/gsc_inspect.py <url> --json`
+- GSC sitemap status: `python3 scripts/gsc_query.py sitemaps --property <prop> --json`
### Tier 2 (Full)
- All Tier 1 checks
-- GA4 organic traffic (28 days): `python scripts/ga4_report.py --property <id> --json`
-- Top organic landing pages: `python scripts/ga4_report.py --property <id> --report top-pages --json`
+- GA4 organic traffic (28 days): `python3 scripts/ga4_report.py --property <id> --json`
+- Top organic landing pages: `python3 scripts/ga4_report.py --property <id> --report top-pages --json`
## Core Web Vitals Thresholds
@@ -56,7 +56,7 @@ After completing data collection at any tier, ALWAYS offer to generate a PDF rep
The report uses the enterprise template: white cover, navy accents, Times New Roman, charts at 85% width, Google logo on title page. No page-break-inside: avoid (causes white gaps).
```bash
-python scripts/google_report.py --type full --data data.json --domain DOMAIN --format pdf --json
+python3 scripts/google_report.py --type full --data data.json --domain DOMAIN --format pdf --json
```
Report types: `cwv-audit`, `gsc-performance`, `indexation`, `full`.
Before presenting: verify `"review": {"status": "PASS"}` in the JSON output.
diff --git a/agents/seo-local.md b/agents/seo-local.md
index edb8842..57cdab4 100644
--- a/agents/seo-local.md
+++ b/agents/seo-local.md
@@ -79,7 +79,7 @@ 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 `python3 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.
Map embeds, GBP widgets, and review carousels are commonly injected client-side. When auditing local pages on JS-heavy sites prefer `--mode always` so the audit reflects what users (and Google's crawler) actually see post-render.
diff --git a/agents/seo-performance.md b/agents/seo-performance.md
index cd4aa8d..e450fbd 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. Use `python scripts/render_page.py <URL> --mode auto --json` before HTML/source inspection so SPA content is visible when needed
+2. Use `python3 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
@@ -65,10 +65,10 @@ Google evaluates the **75th percentile** of page visits, 75% of visits must meet
```bash
# PageSpeed Insights API (uses header-based API key handling)
-python scripts/pagespeed_check.py URL --json
+python3 scripts/pagespeed_check.py URL --json
# SPA-aware HTML/render inspection
-python scripts/render_page.py URL --mode auto --json
+python3 scripts/render_page.py URL --mode auto --json
# Lighthouse CLI
npx lighthouse URL --output json
@@ -78,8 +78,8 @@ npx lighthouse URL --output json
If Google API credentials are configured, prefer CrUX field data over Lighthouse lab data for CWV assessment:
```bash
-python scripts/pagespeed_check.py URL --json
-python scripts/crux_history.py URL --json
+python3 scripts/pagespeed_check.py URL --json
+python3 scripts/crux_history.py URL --json
```
Field data (28-day Chrome user average) is more representative than lab data (single Lighthouse run). Use lab data as fallback when CrUX returns 404 (insufficient traffic).
diff --git a/agents/seo-schema.md b/agents/seo-schema.md
index e7b58f6..7379a02 100644
--- a/agents/seo-schema.md
+++ b/agents/seo-schema.md
@@ -68,7 +68,7 @@ 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 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.
+Use `python3 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
diff --git a/agents/seo-sxo.md b/agents/seo-sxo.md
index 13ba206..7624142 100644
--- a/agents/seo-sxo.md
+++ b/agents/seo-sxo.md
@@ -19,8 +19,8 @@ then comparing that against the target page.
### 1. Fetch and Parse Target Page
-- 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
+- Fetch the target URL using `python3 scripts/render_page.py "<url>" --mode auto --json` (SPA-aware SSRF-protected renderer)
+- Parse with `python3 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
@@ -95,7 +95,7 @@ Before presenting results, verify:
## 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 `python3 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.
Search experience scoring needs the *rendered* DOM because users see what JS produces. Prefer `--mode always` so above-the-fold analysis matches what the persona actually encounters.
diff --git a/agents/seo-technical.md b/agents/seo-technical.md
index a0c3f2b..2fd1570 100644
--- a/agents/seo-technical.md
+++ b/agents/seo-technical.md
@@ -53,7 +53,7 @@ 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 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.
+Use `python3 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
diff --git a/agents/seo-visual.md b/agents/seo-visual.md
index 0a1da6d..a2d1ea2 100644
--- a/agents/seo-visual.md
+++ b/agents/seo-visual.md
@@ -29,8 +29,8 @@ pip install playwright && playwright install chromium
Use the screenshot script (`scripts/capture_screenshot.py` in the plugin root) for browser automation:
```bash
-python scripts/capture_screenshot.py URL --all --output screenshots/
-python scripts/render_page.py URL --mode auto --a11y-tree --json
+python3 scripts/capture_screenshot.py URL --all --output screenshots/
+python3 scripts/render_page.py URL --mode auto --a11y-tree --json
```
## Viewports to Test
diff --git a/docs/BACKLOG-COMPLETION-REPORT-v2.md b/docs/BACKLOG-COMPLETION-REPORT-v2.md
deleted file mode 100644
index eb5cef8..0000000
--- a/docs/BACKLOG-COMPLETION-REPORT-v2.md
+++ /dev/null
@@ -1,472 +0,0 @@
-# Claude SEO v2 Backlog Completion Report
-
-Date: 2026-06-12
-Branch: `v2`
-Private landing remote: `aimh` (`AI-Marketing-Hub/claude-seo`)
-Public source remote: `origin` (`AgriciDaniel/claude-seo`, push URL disabled)
-
-## Executive Summary
-
-The open public/private PR and issue backlog for `claude-seo` was resolved on `v2`.
-Code changes were landed in logical commits, verified locally, and pushed only to
-`aimh/v2`. The public and private open PR/issue queues now return `[]`.
-
-| Item | Verdict | Primary commit(s) |
-|---|---:|---|
-| #99 manifest registry description cap | Fixed | `0c9d940`, guard in `39ba971` |
-| #110 SSRF/authority confusion | Fixed | `3737468`, hardening in `39ba971` |
-| #122 / PR #104 Google API key leakage | Fixed | `3737468`, `27cfa54`, `39ba971` |
-| #102/#112/#120 hooks portability | Fixed | `49df040` |
-| #114/#124 drift portability and decoding | Fixed | `49df040`, subprocess sweep in `39ba971` |
-| #121 fetch no-charset UTF-8 decoding | Fixed | `49df040` |
-| #103 Cloud NLP entities | Fixed | `c938a78` |
-| #100 Moz auth status and free-tier Basic auth | Fixed | `c938a78`, doc clarification in `39ba971` |
-| PR #113 GSC sitemap indexed field | Fixed | `c938a78`, doc clarification in `39ba971` |
-| #61 audit report schema | Fixed | `83de78b` |
-| #51 audit persistence | Fixed | `83de78b`, complete agent contract in `39ba971` |
-| #11 SPA render wiring | Fixed | `83de78b` |
-| PR #118 metadata | Fixed | `84ed49f` |
-| PR #123 ruff config | Partially accepted | `84ed49f` |
-| Dependabot security/compatibility floors | Reconciled | `84ed49f`, `a4a6ff2` |
-| PR #53 NotebookLM | Deferred/closed | no code taken |
-| PR #46 renderer/path work | Superseded/closed | no code taken |
-| #89 uv migration | Deferred/closed | no code taken |
-| PR #129 task template | Partially accepted | `2b296ff` |
-| PR #98, #126, #127 and stale/superseded PRs | Closed/triaged | comments listed below |
-
-## Verification Summary
-
-Final code verification on `39ba971bb8d33e735def9081ee94c826749dbbb3`
-before the docs-only report commit:
-
-| Gate | Result |
-|---|---:|
-| `python -m pytest tests/ -q` | `316 passed, 15 warnings in 52.32s` |
-| `python scripts/portability_check.py` | `33 SKILL.md files checked`, `0` errors/warnings/info |
-| Google API key and query-key secret scan | no matches |
-| `git diff --check` | pass |
-| AST subprocess text-mode audit | `no unguarded text subprocess calls` |
-| Public open PRs/issues | `[]` / `[]` |
-| Private open PRs/issues | `[]` / `[]` |
-
-Known non-blocking warnings:
-
-- `requests` emitted a local environment dependency warning because the active
- pyenv site-packages had `urllib3 (2.6.3)` and `chardet (7.4.0.post2)` loaded.
- This does not change `requirements.txt`, which now requires `urllib3>=2.7.0,<3.0.0`.
-- Matplotlib/pyparsing deprecation warnings came from installed third-party packages.
-- Live Google/Moz/Bing smoke checks were not required for closure. Mocked and
- local adversarial tests cover the changed request construction and redaction behavior.
-
-## Batch 0: Preflight And Push Safety
-
-Verdict: complete.
-
-- Root cause addressed: the backlog had public and private remotes, so accidental
- public pushes were a material operational risk.
-- Safety state: `origin` push URL is `DISABLED_DO_NOT_PUSH`; `aimh` is the only
- configured GitHub push URL.
-- Verification:
- - `git remote -v` showed `origin` fetch only and `origin DISABLED_DO_NOT_PUSH (push)`.
- - `git remote get-url --push origin` returned `DISABLED_DO_NOT_PUSH`.
- - `git push aimh v2` was the only push command used for code landing.
-
-## Batch 1: Manifest Blocker #99
-
-Verdict: fixed.
-
-- Problem: `.claude-plugin/plugin.json` had a marketplace description over the
- registry cap.
-- Root cause: detailed skill/agent breakdown lived inside the manifest description.
-- Change:
- - `.claude-plugin/plugin.json:4` now keeps the description at `436` chars while
- preserving SEO/search/security and capability terms.
- - `tests/test_manifest_consistency.py` now guards the `<500` character limit.
-- Verification:
- - `python -m pytest tests/test_manifest_consistency.py -q` included in targeted
- run: `127 passed, 1 warning`.
- - Full suite: `316 passed, 15 warnings`.
-
-## Batch 2: Security #110, #122, PR #104
-
-### #110 SSRF And Authority Confusion
-
-Verdict: fixed, with second-pass hardening after independent audit.
-
-- Problem: parse-then-request callers could be tricked by authority confusion such
- as backslashes, userinfo, `#@`, encoded authority delimiters, or host disagreement.
-- Root cause: the original boolean URL validator did not reject every authority
- form that HTTP clients can parse differently from `urllib.parse`.
-- Changes:
- - `scripts/url_safety.py:161` rejects raw authority backslashes, percent-encoded
- authority, userinfo, `@`, and `#@` confusion.
- - `scripts/url_safety.py:249` applies authority-confusion rejection in
- `validate_url()`.
- - `scripts/url_safety.py:286` applies the same rejection before strict DNS
- resolution in `validate_url_strict()`.
- - `scripts/url_safety.py:447` adds DNS-pinned `safe_requests_head()`.
- - `scripts/verify_backlinks.py:55` migrates backlink HEAD checks to
- `safe_requests_head()`.
- - `scripts/verify_backlinks.py:121` keeps source URLs behind SSRF validation.
- - `scripts/bing_webmaster.py:137` and `scripts/bing_webmaster.py:328` make URL
- scheme checks case-insensitive before validation.
-- Independent audit findings fixed in `39ba971`:
- - `metadata.google.internal%2e` and `127.0.0.1%2e` now fail closed.
- - malformed `127.0.0.1..` resolution errors are wrapped as URL safety failures.
- - `HTTP://127.0.0.1/` no longer bypasses Bing's validation branch.
-- Verification:
- - `tests/test_url_safety.py` includes `\@`, `#@`, userinfo, private-IP userinfo,
- metadata host variants, encoded authority, and loopback vectors.
- - Local loopback repro showed `verify_backlinks.py` made zero loopback hits for
- `127.0.0.1:port\@1.1.1.1` confusion input.
- - Full suite: `316 passed, 15 warnings`.
-
-### #122 And PR #104 Google API Keys
-
-Verdict: fixed, with stale-example and fallback hardening after independent audit.
-
-- Problem: Google API keys could be placed in URLs or leak through exception/output
- strings.
-- Root cause: several Google API helpers used query parameters, and redaction was
- not applied consistently to all standalone fallback scripts/docs.
-- Changes:
- - Google API helpers now use `X-Goog-Api-Key` through shared headers.
- - `scripts/nlp_analyze.py:109` and `scripts/nlp_analyze.py:164` pass API keys
- in headers and redact exception strings.
- - `extensions/banana/scripts/generate.py:58` uses a keyless URL,
- `extensions/banana/scripts/generate.py:76` sends `X-Goog-Api-Key`, and
- `extensions/banana/scripts/generate.py:86` redacts upstream HTTP error bodies.
- - `extensions/banana/scripts/edit.py:66` uses a keyless URL,
- `extensions/banana/scripts/edit.py:83` sends `X-Goog-Api-Key`, and
- `extensions/banana/scripts/edit.py:93` redacts upstream HTTP error bodies.
- - `docs/MCP-INTEGRATION.md:85` and `docs/MCP-INTEGRATION.md:101` now show
- header-based PSI and CrUX examples.
-- Verification:
- - `tests/test_google_api_key_safety.py` asserts key headers and redacted
- exception paths.
- - `tests/test_banana_api_key_safety.py` forces HTTP errors and verifies no raw
- Google key or query-parameter key output.
- - Secret scan found no Google key prefix or query-key parameter matches under
- `scripts`, `skills`, `docs`, `tests`, or `extensions`.
-
-## Batch 3: Cross-Platform #102/#112/#120, #114/#124, #121
-
-### Hooks #102/#112/#120
-
-Verdict: fixed.
-
-- Problem: hooks assumed POSIX shell/Python behavior and non-canonical file path
- variables.
-- Root cause: hook config used patterns that were not native-Windows safe.
-- Changes:
- - `hooks/hooks.json:8` uses command `node`.
- - `hooks/hooks.json:10` uses canonical `args`.
- - `hooks/hooks.json:13` uses `${tool_input.file_path}`.
- - `hooks/run-python-hook.js:10` probes `$CLAUDE_SEO_PYTHON`, `py -3`,
- `python3`, and `python`.
- - `hooks/run-python-hook.js:27` rejects Windows Store stub output.
- - `hooks/run-python-hook.js:53` preserves hook exit status, including `2`.
-- Verification:
- - Hook tests assert canonical args, no `$FILE_PATH`, no shell launcher, and
- preserved block exit code.
- - `python scripts/portability_check.py` returned zero warnings.
-
-### Drift #114/#124
-
-Verdict: fixed.
-
-- Problem: drift baseline used `/dev/stdout`/stdin-style assumptions and brittle
- subprocess decoding.
-- Root cause: POSIX-only handoff and implicit locale decoding.
-- Changes:
- - `scripts/drift_baseline.py:157` creates a UTF-8 tempfile for fetched HTML.
- - `scripts/drift_baseline.py:190` passes that tempfile path positionally to
- `parse_html.py`.
- - `scripts/drift_baseline.py:166` and `scripts/drift_baseline.py:190` use
- `encoding="utf-8", errors="replace"`.
- - `scripts/drift_baseline.py:229` applies the same explicit decoding to CWV
- subprocess calls.
- - `39ba971` swept the remaining text-mode subprocess calls in `scripts/`.
-- Verification:
- - Drift invalid-byte repro preserved `0x8f` as replacement char and produced a
- stable hash.
- - AST audit returned `no unguarded text subprocess calls`.
-
-### Fetch Decoding #121
-
-Verdict: fixed.
-
-- Problem: no-charset UTF-8 pages could be decoded nondeterministically.
-- Root cause: response decoding relied on requests' fallback behavior.
-- Change:
- - `scripts/fetch_page.py:88` decodes bytes with BOM, HTTP charset, meta charset,
- then UTF-8 with replacement.
-- Verification:
- - Tests cover no-charset UTF-8, explicit ISO-8859-1, meta charset, and invalid
- bytes.
- - Repro output for `Dash - Cafe` used valid UTF-8 bytes and no mojibake.
-
-## Batch 4: Functional #103, #100, PR #113
-
-### #103 Cloud NLP Entities
-
-Verdict: fixed.
-
-- Problem: entity extraction needed Cloud Natural Language v1 entity metadata while
- keeping v2 for other features.
-- Root cause: v2 `annotateText` did not provide the same Knowledge Graph metadata
- and salience behavior for entities.
-- Changes:
- - `scripts/nlp_analyze.py:44` keeps v2 annotateText for sentiment,
- classification, and moderation.
- - `scripts/nlp_analyze.py:45` adds v1 `documents:analyzeEntities`.
- - `scripts/nlp_analyze.py:100` routes entities through v1.
- - `scripts/nlp_analyze.py:148` filters entity extraction out of the v2 feature map.
- - `scripts/nlp_analyze.py:255` keeps URL analysis behind SSRF validation and
- `safe_requests_get()`.
-- Verification:
- - `tests/test_nlp_analyze.py` verifies v1 entity endpoint, v2 non-entity
- endpoint, salience/KG fields, headers, and redaction.
-
-### #100 Moz Auth
-
-Verdict: fixed.
-
-- Problem: Moz free-tier `accessId:secret` credentials were not supported cleanly,
- and status messaging implied untested credentials were fully verified.
-- Root cause: token-style auth was the only first-class path.
-- Changes:
- - `scripts/moz_api.py:49` builds Basic auth for raw or base64
- `accessId:secret`.
- - `scripts/moz_api.py:110` selects `Authorization: Basic ...` or legacy
- `x-moz-token` as appropriate.
- - `scripts/backlinks_auth.py` setup guidance now mentions both token-style and
- `accessId:secret` Moz credentials.
-- Verification:
- - `tests/test_moz_api.py` verifies Basic auth and token fallback.
-
-### PR #113 GSC Sitemap Indexed Field
-
-Verdict: fixed.
-
-- Problem: GSC sitemap output exposed deprecated `contents[].indexed`.
-- Root cause: sitemap list output treated `indexed` as indexation truth.
-- Changes:
- - `scripts/gsc_query.py:39` documents URL Inspection as the indexation source
- of truth.
- - `scripts/gsc_query.py:235` strips `indexed` from sitemap contents.
- - `skills/seo-google/SKILL.md` was corrected to avoid implying sitemap indexed
- counts are crawl/index coverage.
-- Verification:
- - `tests/test_gsc_query.py` verifies the stripped field and indexation note.
-
-## Batch 5: Reports, Audit Persistence, SPA Wiring #61, #51, #11
-
-### #61 Full Audit Report Schema
-
-Verdict: fixed.
-
-- Problem: full audit reports needed executive summary, category sections with
- `what_works`, and a four-phase action plan.
-- Root cause: `google_report.py` was optimized for Google data sections, not a
- full audit envelope.
-- Changes:
- - `scripts/google_report.py:1049` builds audit category sections.
- - `scripts/google_report.py:1077` renders `what_works`.
- - `scripts/google_report.py:1109` builds action plan phases.
- - `scripts/google_report.py:2188` detects full audit schema.
- - `scripts/google_report.py:2261` and `scripts/google_report.py:2288` insert
- categories and action plans into the report.
-- Verification:
- - `tests/test_google_report.py` covers full audit report sections.
-
-### #51 Audit Persistence
-
-Verdict: fixed, completed after independent audit.
-
-- Problem: full audits needed a durable output directory contract.
-- Root cause: the skill described analysis, but specialist agents did not all
- commit to writing findings when `output_dir` was supplied.
-- Changes:
- - `skills/seo-audit/SKILL.md:37` requires all outputs under `{domain}-audit/`.
- - `skills/seo-audit/SKILL.md:53` lists `FULL-AUDIT-REPORT.md`.
- - `skills/seo-audit/SKILL.md:54` lists `ACTION-PLAN.md`.
- - `skills/seo-audit/SKILL.md:55` lists `audit-data.json`.
- - `skills/seo-audit/SKILL.md:56` lists `findings/*.md`.
- - `skills/seo-audit/SKILL.md:57` lists `screenshots/`.
- - `skills/seo-audit/SKILL.md:58` and `skills/seo-audit/SKILL.md:62` keep
- generated report output inside `{domain}-audit/`.
- - `39ba971` added `output_dir/findings/*.md` contracts to all audit-spawnable
- specialist agents.
-- Verification:
- - `tests/test_audit_instructions.py` asserts every audit-spawnable agent includes
- `output_dir` and `findings/`.
-
-### #11 SPA Render Wiring
-
-Verdict: fixed.
-
-- Problem: full audits needed to start from the shared SPA-aware renderer.
-- Root cause: some audit flows still began from raw fetch assumptions.
-- Change:
- - `skills/seo-audit/SKILL.md:17` starts with
- `python scripts/render_page.py <url> --mode auto --json`.
-- Verification:
- - Audit instruction tests assert render-first workflow and shared renderer alignment.
-
-## Batch 6: Metadata, Lint, Dependencies
-
-Verdict: complete.
-
-- PR #118:
- - `pyproject.toml:8` adds author metadata.
- - `pyproject.toml:11` adds project keywords.
-- PR #123:
- - `pyproject.toml:17` adds scoped Ruff configuration.
- - The broad 82-file autofix was intentionally not taken.
-- Dependency reconciliation:
- - `requirements.txt:7` bumps `lxml`.
- - `requirements.txt:8` bumps `playwright`.
- - `requirements.txt:9` bumps `Pillow`.
- - `requirements.txt:10` bumps `urllib3` to `>=2.7.0,<3.0.0`.
- - `requirements.txt:24` bumps `google-api-python-client`.
- - `requirements.txt:27` bumps `google-auth-httplib2`.
-- Verification:
- - Full suite passed after dependency floor changes.
- - Private Dependabot #3 received a correction comment because `htmldate` remains
- a dependency; it stays closed because the PR was not tied to a verified
- security/compatibility requirement.
-
-## Batch 7: Large PR And Strategic Dispositions
-
-Verdict: complete.
-
-- PR #53 NotebookLM: closed deferred. No code taken due unofficial API,
- dependency/maintenance weight, and stale skill-count impact.
-- PR #46 renderer/path work: closed superseded by the narrower v2 renderer/path
- and portability work. No extra code salvaged.
-- #89 uv migration: closed no-go for this pass. Dedicated installer/workflow
- migration required.
-- PR #129: accepted only `.github/ISSUE_TEMPLATE/task.yml` in `2b296ff`; declined
- the broader `CLAUDE.md` async-workflow narrative.
-
-## Batch 8: Public/Private Triage Closure
-
-Verdict: complete.
-
-- PR #98 closed as empty/no-op.
-- #127 closed as wrong project.
-- #126 closed as informational/promotional.
-- #11 closed only after SPA render wiring and full tests passed.
-- Superseded Windows PRs #115/#125 were closed with crediting comments.
-- Private Dependabot PRs were reconciled after accepted requirement bumps landed
- on `aimh/v2`.
-
-## Independent Verification
-
-Five read-only specialist auditors reviewed the landed workstreams:
-
-| Auditor | Scope | Result | Follow-up |
-|---|---|---:|---|
-| Boole | SSRF #110 | fixed with gaps | encoded-authority and uppercase-scheme gaps fixed in `39ba971` |
-| Mencius | Google keys #122 | fixed with gaps | Banana fallback and stale docs fixed in `39ba971` |
-| Carson | Manifest/cross-platform | pass with gaps | manifest cap test and CWV subprocess encoding fixed in `39ba971` |
-| Kuhn | NLP/Moz/GSC | pass with doc gaps | GSC and Moz docs clarified in `39ba971` |
-| Plato | Audit persistence/reports | pass with #51 gap | all audit-spawnable agents now have output contracts in `39ba971` |
-
-No auditor-reported blocker remains open.
-
-## Final Landing Evidence
-
-### Code Commit List On `v2`
-
-Backlog code commits added after baseline `2cc42460095fca034264004947941dd2b3f41731`:
-
-```text
-0c9d940 fix(manifest): trim plugin description under registry cap
-3737468 fix(security): harden URL and Google API key handling
-49df040 fix(portability): make hooks and drift fetch cross-platform
-c938a78 fix(api): align NLP Moz and GSC behaviors
-83de78b feat(audit): persist full audit reports and renderer wiring
-84ed49f chore(config): add metadata ruff config and dependency floors
-2b296ff chore(github): add task issue template
-27cfa54 fix(security): remove stale Google key query examples
-a4a6ff2 chore(deps): raise urllib3 floor for security advisories
-39ba971 fix(audit): close independent verification gaps
-```
-
-### Code Push Confirmation
-
-The verified code push used only the private remote:
-
-```text
-$ git push aimh v2
-To https://github.com/AI-Marketing-Hub/claude-seo.git
- a4a6ff2..39ba971 v2 -> v2
-```
-
-Remote verification immediately after code landing:
-
-```text
-39ba971bb8d33e735def9081ee94c826749dbbb3 refs/heads/v2 # aimh
-dabfc1abb4ca9a4d7967242bf00d52593be56ed1 refs/heads/main # origin
-```
-
-### Public PR Closure Comments
-
-- PR #129: `Accepted only the task issue template in private v2 commit 2b296ff. I’m declining the broader CLAUDE.md async-workflow narrative for this pass so project memory stays focused on durable repo instructions. Closing as partially superseded.`
-- PR #128: `Closing as superseded by the v2 portability batch. Commit 49df040 adds the cross-platform hook launcher, Windows Python probing, drift tempfile handoff, and deterministic fetch decoding covered by this PR’s goals.`
-- PR #125: `Thanks for the Windows drift portability work. The behavior is now covered in private v2 commit 49df040 with tempfile handoff, UTF-8 replacement decoding for subprocesses, and regression tests, so I’m closing this as superseded.`
-- PR #123: `Accepted the scoped ruff configuration in private v2 commit 84ed49f. I intentionally did not take the broad 82-file autofix in this backlog pass to keep behavior changes reviewable. Closing as partially superseded.`
-- PR #118: `Accepted in private v2 commit 84ed49f: pyproject authors and keyword metadata were applied and covered by tests. Closing this PR as incorporated.`
-- PR #117: `Closing as superseded by private v2 commit 49df040. The drift baseline Windows path issue is fixed via a portable tempfile handoff and regression coverage.`
-- PR #116: `Accepted in private v2 commit 84ed49f as part of the dependency-floor reconciliation. Closing this PR as incorporated.`
-- PR #115: `Thanks for the non-Latin-1 Windows drift report/fix. Private v2 commit 49df040 covers this with UTF-8 replacement decoding and a regression test using invalid bytes, so I’m closing this as superseded.`
-- PR #113: `Accepted in private v2 commit c938a78. The deprecated sitemap indexed field is stripped and the docs now point to URL Inspection as the source of indexation truth. Closing as incorporated.`
-- PR #111: `Closing as superseded by private v2 commit 49df040. The installer now probes py -3/python3/python and rejects Windows Store stubs.`
-- PR #109: `Accepted in private v2 commit 84ed49f as part of the dependency-floor reconciliation. Closing this PR as incorporated.`
-- PR #108: `Not taking this broad matplotlib floor bump in this backlog pass because it is not tied to the verified security/compatibility fixes and would add unrelated dependency churn. Closing as not planned for this pass.`
-- PR #107: `Accepted in private v2 commit 84ed49f as part of the dependency-floor reconciliation. Closing this PR as incorporated.`
-- PR #106: `Not taking this broad google-auth floor bump in this backlog pass because the accepted dependency changes were limited to verified security/compatibility needs. Closing as not planned for this pass.`
-- PR #104: `Accepted as a superset in private v2 commits 3737468 and 27cfa54. Google API keys now use X-Goog-Api-Key and stale query-string examples were removed. Closing as incorporated.`
-- PR #101: `Closing as superseded by private v2 commit 49df040. The final implementation uses canonical args with a small Node launcher that probes Python across platforms and preserves exit code 2.`
-- PR #98: `Closing as no-op: this PR has no effective change to incorporate.`
-- PR #53: `Closing as deferred for this backlog pass. NotebookLM automation still depends on an unofficial API, adds dependency/maintenance weight, and needs a dedicated skill-count/release update rather than being mixed into backlog fixes.`
-- PR #46: `Closing as superseded by the v2 renderer/path and portability work. I did not salvage extra changes from this PR in this pass because the verified fixes landed through the narrower batches.`
-
-### Public Issue Closure Comments
-
-- Issue #127: `Closing as wrong project for this repository. No claude-seo code change is needed.`
-- Issue #126: `Closing as informational/promotional rather than an actionable claude-seo defect or backlog item.`
-- Issue #124: `Fixed in private v2 commit 49df040. Drift subprocess handling now uses portable tempfile handoff plus UTF-8 replacement decoding, with regression coverage for invalid bytes.`
-- Issue #122: `Fixed in private v2 commits 3737468 and 27cfa54. Google API keys are sent with X-Goog-Api-Key, output is redacted, and stale query-string examples were removed.`
-- Issue #121: `Fixed in private v2 commit 49df040. fetch_page.py now decodes bytes deterministically using header charset, BOM, meta charset, then UTF-8 with replacement.`
-- Issue #120: `Fixed in private v2 commit 49df040. Hooks now use canonical args and a cross-platform launcher instead of shell/POSIX assumptions.`
-- Issue #114: `Fixed in private v2 commit 49df040. drift_baseline.py no longer relies on /dev/stdout or stdin handoff; it passes a tempfile path to parse_html.py.`
-- Issue #112: `Fixed in private v2 commit 49df040. The hook launcher probes CLAUDE_SEO_PYTHON, py -3, python3, then python while preserving block exit code 2.`
-- Issue #110: `Fixed in private v2 commit 3737468. URL validation rejects authority-confusion inputs, userinfo, private-IP userinfo tricks, and unsafe validate-then-request paths were moved to pinned safe request helpers.`
-- Issue #103: `Fixed in private v2 commit c938a78. Entity extraction now uses Cloud Natural Language v1 analyzeEntities for KG metadata and salience, while v2 remains for sentiment/classification/moderation.`
-- Issue #102: `Fixed in private v2 commit 49df040. Hooks no longer depend on a bare python executable and now launch portably across Windows/macOS/Linux.`
-- Issue #100: `Fixed in private v2 commit c938a78. Moz supports free-tier Basic auth credentials, and credential status no longer claims live verification unless a live check has run.`
-- Issue #99: `Fixed in private v2 commit 0c9d940. The plugin manifest description is now below the registry limit while preserving the important SEO/search/security terms.`
-- Issue #89: `Closing as no-go for this backlog pass. uv migration touches installer and workflow behavior and should be handled as a dedicated migration with docs and CI coverage, not mixed into backlog fixes.`
-- Issue #61: `Fixed in private v2 commit 83de78b. google_report.py now supports full-audit executive summaries, category sections with what_works, and phased action plans.`
-- Issue #51: `Fixed in private v2 commit 83de78b. seo-audit now has an explicit persisted artifact contract for FULL-AUDIT-REPORT.md, ACTION-PLAN.md, audit-data.json, findings, and screenshots.`
-- Issue #11: `Fixed in private v2 commit 83de78b and verified with the full test suite. seo-audit now starts from render_page.py --mode auto and related agents/skills are aligned with the shared renderer.`
-
-### Private Dependabot Closure Comments
-
-- Private PR #6: `Accepted in private v2 commit a4a6ff2 because urllib3 2.7.0 addresses high-severity advisories GHSA-mf9v-mfxr-j63j and GHSA-qccp-gfcp-xxvc. Full tests passed after the floor update. Closing as incorporated.`
-- Private PR #5: `Not taking this beautifulsoup4 floor in this backlog pass because the PR does not identify a security or required compatibility fix and would add unrelated dependency churn. Closing as not planned for this pass.`
-- Private PR #4: `Accepted in private v2 commit 84ed49f as part of the dependency-floor reconciliation. This PR was already closed once the branch contained the accepted requirement floor.`
-- Private PR #3 original comment: `Looks like htmldate is no longer a dependency, so this is no longer needed.`
-- Private PR #3 correction comment: `Correction to my previous note: htmldate remains a dependency at the existing floor. I am still not taking this PR in this backlog pass because it was not tied to a verified security/compatibility requirement; keeping it closed as not planned for this pass.`
-- Private PR #2: `Not taking this validators floor in this backlog pass because 0.35.0 drops Python 3.8 support and is not tied to a verified security/compatibility requirement here. Closing as not planned for this pass.`
-- Private PR #1: `Not taking this broad requests floor in this backlog pass. The current floor already includes the tracked security fixes, and the accepted urllib3 security floor landed separately in a4a6ff2. Closing as not planned for this pass.`
-
-### Origin/Main Untouched Attestation
-
-- `origin` push URL: `DISABLED_DO_NOT_PUSH`.
-- No push was made to `origin`.
-- Public `origin/main` was not modified by this execution.
-- Final code push target was `aimh/v2` only.
diff --git a/docs/MIGRATION-v1-to-v2.md b/docs/MIGRATION-v1-to-v2.md
index 2a0765c..9a88384 100644
--- a/docs/MIGRATION-v1-to-v2.md
+++ b/docs/MIGRATION-v1-to-v2.md
@@ -40,35 +40,35 @@ but use exactly the same overall structure.
| New | What it does |
|---|---|
-| `python scripts/content_quality.py` | QRG-aligned filler / AI-pattern / information-density scorer |
-| `python scripts/content_humanize.py` | 40+ deterministic AI-phrasing replacements |
-| `python scripts/content_verify.py` | Claim extraction + citation-gap detection |
-| `python scripts/domain_history.py` | WHOIS-driven expired-domain abuse check |
-| `python scripts/seo_updates.py` | Primary-source Google updates changelog |
+| `python3 scripts/content_quality.py` | QRG-aligned filler / AI-pattern / information-density scorer |
+| `python3 scripts/content_humanize.py` | 40+ deterministic AI-phrasing replacements |
+| `python3 scripts/content_verify.py` | Claim extraction + citation-gap detection |
+| `python3 scripts/domain_history.py` | WHOIS-driven expired-domain abuse check |
+| `python3 scripts/seo_updates.py` | Primary-source Google updates changelog |
| `data/google-updates.json` | 18 confirmed Google updates 2024-03 → 2025-12 |
### Technical / CWV depth (Phase C)
| New | What it does |
|---|---|
-| `python scripts/preload_check.py` | Speculation Rules + bfcache + prerender + LCP preload audit |
-| `python scripts/indexnow_submit.py` | Submit up to 10k URLs to IndexNow (Bing/Yandex/Seznam/Naver) |
-| `python scripts/lcp_subparts.py` | LCP decomposition via CrUX (TTFB, load delay, load duration, render delay) |
-| `python scripts/unlighthouse_run.py` | Multi-page Lighthouse via the MIT Unlighthouse CLI |
+| `python3 scripts/preload_check.py` | Speculation Rules + bfcache + prerender + LCP preload audit |
+| `python3 scripts/indexnow_submit.py` | Submit up to 10k URLs to IndexNow (Bing/Yandex/Seznam/Naver) |
+| `python3 scripts/lcp_subparts.py` | LCP decomposition via CrUX (TTFB, load delay, load duration, render delay) |
+| `python3 scripts/unlighthouse_run.py` | Multi-page Lighthouse via the MIT Unlighthouse CLI |
### Schema completeness (Phase D)
| New | What it does |
|---|---|
-| `python scripts/schema_generate.py reservation/order/discussion/profile` | JSON-LD generators for the four high-leverage v2 types |
-| `python scripts/schema_ecommerce_validate.py` | Product schema policy validator (hasMerchantReturnPolicy, shippingDetails, MemberProgram, EU energy class, ProductGroup) |
+| `python3 scripts/schema_generate.py reservation/order/discussion/profile` | JSON-LD generators for the four high-leverage v2 types |
+| `python3 scripts/schema_ecommerce_validate.py` | Product schema policy validator (hasMerchantReturnPolicy, shippingDetails, MemberProgram, EU energy class, ProductGroup) |
| `skills/seo-schema/references/deprecated-types-2024-2026.md` | Reference: every retired rich-result type with its replacement |
### AI search + 5 new extensions (Phase E)
| New | What it does |
|---|---|
-| `python scripts/parasite_risk.py` | Site-reputation-abuse risk scanner per Nov 2024 Google policy |
+| `python3 scripts/parasite_risk.py` | Site-reputation-abuse risk scanner per Nov 2024 Google policy |
| `extensions/ahrefs/` | Official `@ahrefs/mcp` server wired into Claude Code |
| `extensions/seranking/` | AI Share-of-Voice across ChatGPT/Gemini/Perplexity/AI Overviews/AI Mode |
| `extensions/profound/` | Time-series LLM citation tracker |
@@ -80,7 +80,7 @@ but use exactly the same overall structure.
| New | What it does |
|---|---|
-| `python scripts/gbp_deprecation_lint.py` | Detects retired GBP chat / `.business.site` / Q&A references |
+| `python3 scripts/gbp_deprecation_lint.py` | Detects retired GBP chat / `.business.site` / Q&A references |
| `skills/seo-google/references/dma-consent-mode-v2.md` | EU CTR diagnostic + softened cookieless framing |
| `skills/seo-hreflang/references/machine-translation-qa.md` | Untranslated-MT detection per Jan 2025 QRG §4.6.5 |
@@ -89,15 +89,15 @@ but use exactly the same overall structure.
| New | What it does |
|---|---|
| `AGENTS.md` (extended) | Codex CLI, Cline, Aider added to supported-harnesses list |
-| `python scripts/portability_check.py` | Cross-platform SKILL.md frontmatter lint |
+| `python3 scripts/portability_check.py` | Cross-platform SKILL.md frontmatter lint |
| Tool-name compatibility table | Read/Write/Edit/Bash/Glob/Grep/WebFetch mappings across Codex/Cline/Aider/Cursor/Antigravity |
### Release signing (Phase H)
| New | What it does |
|---|---|
-| `python scripts/release_sign.py` | Generate a SHA-256 manifest of every git-tracked file |
-| `python scripts/verify_release.py` | Verify a checkout against a signed manifest |
+| `python3 scripts/release_sign.py` | Generate a SHA-256 manifest of every git-tracked file |
+| `python3 scripts/verify_release.py` | Verify a checkout against a signed manifest |
### Hardening
@@ -169,7 +169,7 @@ pip install -r requirements.txt
playwright install chromium
# Verify manifest consistency
-python -m pytest tests/test_manifest_consistency.py -v
+python3 -m pytest tests/test_manifest_consistency.py -v
```
That's it. The first time you run anything that touches
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 95a5fb9..bfc782b 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -78,7 +78,7 @@ curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/requir
1. Install Python from [python.org](https://python.org) and check "Add to PATH"
2. Or use the Windows launcher: `py -3 -m pip install -r requirements.txt`
-3. Use `python -m pip` instead of bare `pip`
+3. Use `python3 -m pip` instead of bare `pip`
---
@@ -94,7 +94,7 @@ playwright install chromium
If that fails:
```bash
pip install playwright
-python -m playwright install chromium
+python3 -m playwright install chromium
```
---
diff --git a/extensions/ahrefs/skills/seo-ahrefs/SKILL.md b/extensions/ahrefs/skills/seo-ahrefs/SKILL.md
index 9af1ec9..257a17c 100644
--- a/extensions/ahrefs/skills/seo-ahrefs/SKILL.md
+++ b/extensions/ahrefs/skills/seo-ahrefs/SKILL.md
@@ -45,7 +45,7 @@ provide the install command above.
Ahrefs API usage is metered per unit. Before running a batch (>= 50 URLs):
-1. Estimate cost with `python scripts/dataforseo_costs.py` (the cost-tracker module is generic and supports Ahrefs unit accounting).
+1. Estimate cost with `python3 scripts/dataforseo_costs.py` (the cost-tracker module is generic and supports Ahrefs unit accounting).
2. Surface the estimate to the orchestrator.
3. Log actual cost after each call.
diff --git a/extensions/bing-webmaster/skills/seo-bing/SKILL.md b/extensions/bing-webmaster/skills/seo-bing/SKILL.md
index 01ccc20..b1967e1 100644
--- a/extensions/bing-webmaster/skills/seo-bing/SKILL.md
+++ b/extensions/bing-webmaster/skills/seo-bing/SKILL.md
@@ -24,11 +24,11 @@ specifically for **Bing/Yandex/Seznam/Naver indexing** and
| Command | Underlying script |
|---|---|
-| `/seo bing links <url>` | `python scripts/bing_webmaster.py links <url>` |
-| `/seo bing compare <urlA> <urlB>` | `python scripts/bing_webmaster.py compare <urlA> <urlB>` |
-| `/seo bing submit <url>` (single URL) | `python scripts/indexnow_submit.py --host ... --urls <url>` |
-| `/seo bing submit-batch <file>` | `python scripts/indexnow_submit.py --urls-file <file>` |
-| `/seo bing verify-indexnow` | `python scripts/indexnow_submit.py --verify-only` |
+| `/seo bing links <url>` | `python3 scripts/bing_webmaster.py links <url>` |
+| `/seo bing compare <urlA> <urlB>` | `python3 scripts/bing_webmaster.py compare <urlA> <urlB>` |
+| `/seo bing submit <url>` (single URL) | `python3 scripts/indexnow_submit.py --host ... --urls <url>` |
+| `/seo bing submit-batch <file>` | `python3 scripts/indexnow_submit.py --urls-file <file>` |
+| `/seo bing verify-indexnow` | `python3 scripts/indexnow_submit.py --verify-only` |
## When this skill applies
diff --git a/extensions/dataforseo/skills/seo-dataforseo/SKILL.md b/extensions/dataforseo/skills/seo-dataforseo/SKILL.md
index 80031e7..5130bf3 100644
--- a/extensions/dataforseo/skills/seo-dataforseo/SKILL.md
+++ b/extensions/dataforseo/skills/seo-dataforseo/SKILL.md
@@ -50,7 +50,7 @@ DataForSEO charges per API call. Be efficient:
**Before every DataForSEO MCP call**, run cost estimation:
```
-python scripts/dataforseo_costs.py check <endpoint> [--count N]
+python3 scripts/dataforseo_costs.py check <endpoint> [--count N]
```
- If `"status": "approved"` → proceed with the API call
@@ -59,7 +59,7 @@ python scripts/dataforseo_costs.py check <endpoint> [--count N]
**After each API call completes**, log the cost:
```
-python scripts/dataforseo_costs.py log <endpoint> <actual_cost>
+python3 scripts/dataforseo_costs.py log <endpoint> <actual_cost>
```
**User commands for cost management:**
diff --git a/skills/seo-audit/SKILL.md b/skills/seo-audit/SKILL.md
index 7d523d3..78d4f37 100644
--- a/skills/seo-audit/SKILL.md
+++ b/skills/seo-audit/SKILL.md
@@ -14,7 +14,7 @@ metadata:
## Process
-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
+1. **Render homepage**: use `python3 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):
@@ -27,11 +27,11 @@ metadata:
- `seo-geo` -- AI crawler access, llms.txt, citability, brand mention signals
- `seo-local` -- GBP signals, NAP consistency, reviews, local schema, industry-specific local factors (spawn when Local Service industry detected: brick-and-mortar, SAB, or hybrid business type)
- `seo-maps` -- Geo-grid rank tracking, GBP audit, review intelligence, competitor radius mapping (spawn when Local Service detected AND DataForSEO MCP available)
- - `seo-google` -- CWV field data (CrUX), URL indexation (GSC), organic traffic (GA4) (spawn when Google API credentials detected via `python scripts/google_auth.py --check`)
- - `seo-backlinks` -- Backlink profile data: DA/PA, referring domains, anchor text, toxic links (spawn when Moz or Bing API credentials detected via `python scripts/backlinks_auth.py --check`, or always include Common Crawl domain-level metrics)
+ - `seo-google` -- CWV field data (CrUX), URL indexation (GSC), organic traffic (GA4) (spawn when Google API credentials detected via `python3 scripts/google_auth.py --check`)
+ - `seo-backlinks` -- Backlink profile data: DA/PA, referring domains, anchor text, toxic links (spawn when Moz or Bing API credentials detected via `python3 scripts/backlinks_auth.py --check`, or always include Common Crawl domain-level metrics)
- `seo-cluster` -- Semantic clustering analysis (spawn when content strategy signals detected: blog, pillar pages, topic clusters)
- `seo-sxo` -- Search experience analysis: page-type mismatch, user stories, persona scoring (always include in full audits)
- - `seo-drift` -- Drift analysis: compare against stored baseline (spawn when drift baseline exists for the URL via `python scripts/drift_history.py <url>`)
+ - `seo-drift` -- Drift analysis: compare against stored baseline (spawn when drift baseline exists for the URL via `python3 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. **Persist audit artifacts** -- write all outputs under `{domain}-audit/`
@@ -59,7 +59,7 @@ Delay between requests: 1 second
## 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> --output-dir {domain}-audit/` can generate a report even when Google API data is unavailable:
+Write `{domain}-audit/audit-data.json` with this shape so `python3 scripts/google_report.py --type full --data {domain}-audit/audit-data.json --domain <domain> --output-dir {domain}-audit/` can generate a report even when Google API data is unavailable:
```json
{
@@ -170,7 +170,7 @@ If DataForSEO MCP tools are available, spawn the `seo-dataforseo` agent alongsid
## Google API Integration (Optional)
-If Google API credentials are configured (`python scripts/google_auth.py --check`), spawn the `seo-google` agent to enrich the audit with real Google field data: CrUX Core Web Vitals (replaces lab-only estimates), GSC URL indexation status, search performance (clicks, impressions, CTR), and GA4 organic traffic trends. The Performance (CWV) category score benefits most from field data.
+If Google API credentials are configured (`python3 scripts/google_auth.py --check`), spawn the `seo-google` agent to enrich the audit with real Google field data: CrUX Core Web Vitals (replaces lab-only estimates), GSC URL indexation status, search performance (clicks, impressions, CTR), and GA4 organic traffic trends. The Performance (CWV) category score benefits most from field data.
## Error Handling
diff --git a/skills/seo-backlinks/SKILL.md b/skills/seo-backlinks/SKILL.md
index e8a54c0..38e985d 100644
--- a/skills/seo-backlinks/SKILL.md
+++ b/skills/seo-backlinks/SKILL.md
@@ -18,12 +18,12 @@ metadata:
Before analysis, detect available data sources:
1. **DataForSEO MCP** (premium): Check if `dataforseo_backlinks_summary` tool is available
-2. **Moz API** (free signup): `python scripts/backlinks_auth.py --check moz --json`
-3. **Bing Webmaster** (free signup): `python scripts/backlinks_auth.py --check bing --json`
+2. **Moz API** (free signup): `python3 scripts/backlinks_auth.py --check moz --json`
+3. **Bing Webmaster** (free signup): `python3 scripts/backlinks_auth.py --check bing --json`
4. **Common Crawl** (always available): Domain-level graph with PageRank
5. **Verification Crawler** (always available): Checks if known backlinks still exist
-Run `python scripts/backlinks_auth.py --check --json` to detect all sources at once.
+Run `python3 scripts/backlinks_auth.py --check --json` to detect all sources at once.
If no sources are configured beyond the always-available tier:
- Still produce a report using Common Crawl domain metrics
@@ -48,9 +48,9 @@ Produce all 7 sections below. Each section lists data sources in preference orde
**DataForSEO:** `dataforseo_backlinks_summary` → total backlinks, referring domains, domain rank, follow ratio, trend.
-**Moz API:** `python scripts/moz_api.py metrics <url> --json` → Domain Authority, Page Authority, Spam Score, linking root domains, external links.
+**Moz API:** `python3 scripts/moz_api.py metrics <url> --json` → Domain Authority, Page Authority, Spam Score, linking root domains, external links.
-**Common Crawl:** `python scripts/commoncrawl_graph.py <domain> --json` → in-degree (referring domain count), PageRank, harmonic centrality.
+**Common Crawl:** `python3 scripts/commoncrawl_graph.py <domain> --json` → in-degree (referring domain count), PageRank, harmonic centrality.
**Scoring:**
@@ -65,9 +65,9 @@ Produce all 7 sections below. Each section lists data sources in preference orde
**DataForSEO:** `dataforseo_backlinks_anchors`
-**Moz API:** `python scripts/moz_api.py anchors <url> --json`
+**Moz API:** `python3 scripts/moz_api.py anchors <url> --json`
-**Bing Webmaster:** `python scripts/bing_webmaster.py links <url> --json` (extract anchor text from link details)
+**Bing Webmaster:** `python3 scripts/bing_webmaster.py links <url> --json` (extract anchor text from link details)
**Healthy distribution benchmarks:**
@@ -86,9 +86,9 @@ Flag if exact-match anchors exceed 15% -- this is a Google Penguin risk signal.
**DataForSEO:** `dataforseo_backlinks_referring_domains`
-**Moz API:** `python scripts/moz_api.py domains <url> --json` → domains with DA scores
+**Moz API:** `python3 scripts/moz_api.py domains <url> --json` → domains with DA scores
-**Common Crawl:** `python scripts/commoncrawl_graph.py <domain> --json` → top referring domains (domain-level, no authority scores)
+**Common Crawl:** `python3 scripts/commoncrawl_graph.py <domain> --json` → top referring domains (domain-level, no authority scores)
Analyze:
- **TLD distribution**: .edu, .gov, .org = high authority. Excessive .xyz, .info = low quality
@@ -100,9 +100,9 @@ Analyze:
**DataForSEO:** `dataforseo_backlinks_bulk_spam_score` + toxic patterns from reference
-**Moz API:** Spam Score from `python scripts/moz_api.py metrics <url> --json` (1-17% scale, >11% = high risk)
+**Moz API:** Spam Score from `python3 scripts/moz_api.py metrics <url> --json` (1-17% scale, >11% = high risk)
-**Verification Crawler:** `python scripts/verify_backlinks.py --target <url> --links <file> --json` (verify suspicious links still exist)
+**Verification Crawler:** `python3 scripts/verify_backlinks.py --target <url> --links <file> --json` (verify suspicious links still exist)
**High-risk indicators (flag immediately):**
- Links from known PBN (Private Blog Network) domains
@@ -124,7 +124,7 @@ Load `references/backlink-quality.md` for the full 30 toxic patterns and disavow
**DataForSEO:** `dataforseo_backlinks_backlinks` with target type "page"
-**Moz API:** `python scripts/moz_api.py pages <domain> --json`
+**Moz API:** `python3 scripts/moz_api.py pages <domain> --json`
Find:
- Which pages attract the most backlinks
@@ -136,9 +136,9 @@ Find:
**DataForSEO:** `dataforseo_backlinks_referring_domains` for both domains, then compare
-**Bing Webmaster (unique!):** `python scripts/bing_webmaster.py compare <url1> <url2> --json` — the only free tool with built-in competitor comparison
+**Bing Webmaster (unique!):** `python3 scripts/bing_webmaster.py compare <url1> <url2> --json` — the only free tool with built-in competitor comparison
-**Moz API:** Compare DA/PA between domains via `python scripts/moz_api.py metrics <url> --json` for each
+**Moz API:** Compare DA/PA between domains via `python3 scripts/moz_api.py metrics <url> --json` for each
Output:
- Domains linking to competitor but NOT to target = link building opportunities
@@ -150,7 +150,7 @@ Output:
**DataForSEO only:** `dataforseo_backlinks_backlinks` with date filters for 30/60/90 day changes
-**Verification Crawler:** For known links, verify current status with `python scripts/verify_backlinks.py`
+**Verification Crawler:** For known links, verify current status with `python3 scripts/verify_backlinks.py`
**Note:** Free sources cannot track new/lost links over time. If this section is requested without DataForSEO, inform the user: "Link velocity tracking requires the DataForSEO extension. Free sources provide point-in-time snapshots only."
diff --git a/skills/seo-cluster/SKILL.md b/skills/seo-cluster/SKILL.md
index f86476b..22d6c46 100644
--- a/skills/seo-cluster/SKILL.md
+++ b/skills/seo-cluster/SKILL.md
@@ -80,7 +80,7 @@ the full algorithm.
- Skip pairs where both are long-tail variants of the same head term (assume same cluster)
**DataForSEO integration:** If DataForSEO MCP is available, use `serp_organic_live_advanced`
-instead of WebSearch for SERP data. Run `python scripts/dataforseo_costs.py check serp_organic_live_advanced --count N`
+instead of WebSearch for SERP data. Run `python3 scripts/dataforseo_costs.py check serp_organic_live_advanced --count N`
before each batch. If `"status": "needs_approval"`, show cost estimate and ask user.
If `"status": "blocked"`, fall back to WebSearch.
@@ -312,7 +312,7 @@ After cluster planning or execution completes, offer:
## Security
-- All URLs fetched via `python scripts/render_page.py --mode auto` (SPA-aware SSRF protection via `url_safety`)
+- All URLs fetched via `python3 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-content-brief/references/page-type-templates.md b/skills/seo-content-brief/references/page-type-templates.md
index 5f9248d..e355702 100644
--- a/skills/seo-content-brief/references/page-type-templates.md
+++ b/skills/seo-content-brief/references/page-type-templates.md
@@ -97,7 +97,7 @@ Select the template that matches the page type. Adapt sections based on the spec
| 8-15 questions | Grouped by subtopic | Each answered in 40-60 words, FS target for each |
| CTA after last question | Convert | Contextual next step |
-**Schema:** FAQPage (every Q&A as mainEntity, critical for rich results)
+**Schema:** FAQPage (every Q&A as mainEntity) — Google retired FAQ rich results for all sites on May 7, 2026, so this no longer produces a SERP rich result; the markup still aids AI Mode / AI Overviews entity resolution (treat as a supporting signal, not a ranking feature). For genuine user Q&A pages, use QAPage instead. See the seo-schema skill for the canonical position.
**Primary keyword:** In H1 as "[Topic]: Frequently Asked Questions", in first answer
## Location Page
diff --git a/skills/seo-dataforseo/SKILL.md b/skills/seo-dataforseo/SKILL.md
index 80031e7..5130bf3 100644
--- a/skills/seo-dataforseo/SKILL.md
+++ b/skills/seo-dataforseo/SKILL.md
@@ -50,7 +50,7 @@ DataForSEO charges per API call. Be efficient:
**Before every DataForSEO MCP call**, run cost estimation:
```
-python scripts/dataforseo_costs.py check <endpoint> [--count N]
+python3 scripts/dataforseo_costs.py check <endpoint> [--count N]
```
- If `"status": "approved"` → proceed with the API call
@@ -59,7 +59,7 @@ python scripts/dataforseo_costs.py check <endpoint> [--count N]
**After each API call completes**, log the cost:
```
-python scripts/dataforseo_costs.py log <endpoint> <actual_cost>
+python3 scripts/dataforseo_costs.py log <endpoint> <actual_cost>
```
**User commands for cost management:**
diff --git a/skills/seo-dataforseo/references/cost-tiers.md b/skills/seo-dataforseo/references/cost-tiers.md
index 97ff303..ab13a51 100644
--- a/skills/seo-dataforseo/references/cost-tiers.md
+++ b/skills/seo-dataforseo/references/cost-tiers.md
@@ -31,7 +31,7 @@
| **Aggressive** | $50.00 | $2.00 | threshold | Agency bulk work |
| **Unlimited** | $999.00 | -- | none | Trusted pipelines |
-Configure with: `python scripts/dataforseo_costs.py config --mode threshold --threshold 0.50 --daily-limit 10.00`
+Configure with: `python3 scripts/dataforseo_costs.py config --mode threshold --threshold 0.50 --daily-limit 10.00`
## Cost Reduction Tips
@@ -44,11 +44,11 @@ Configure with: `python scripts/dataforseo_costs.py config --mode threshold --th
## Approval Flow
Before any DataForSEO MCP call:
-1. Run `python scripts/dataforseo_costs.py check <endpoint> [--count N]`
+1. Run `python3 scripts/dataforseo_costs.py check <endpoint> [--count N]`
2. If `status: "approved"` → proceed
3. If `status: "needs_approval"` → show cost to user, ask to confirm
4. If `status: "blocked"` → inform user daily limit would be exceeded
-5. After call completes, log: `python scripts/dataforseo_costs.py log <endpoint> <cost>`
+5. After call completes, log: `python3 scripts/dataforseo_costs.py log <endpoint> <cost>`
## Warn Endpoints
diff --git a/skills/seo-drift/SKILL.md b/skills/seo-drift/SKILL.md
index e37299a..78df37a 100644
--- a/skills/seo-drift/SKILL.md
+++ b/skills/seo-drift/SKILL.md
@@ -103,8 +103,8 @@ Captures the current state of a page and stores it.
**Execution:**
```bash
-python scripts/drift_baseline.py <url>
-python scripts/drift_baseline.py <url> --skip-cwv
+python3 scripts/drift_baseline.py <url>
+python3 scripts/drift_baseline.py <url> --skip-cwv
```
**Output:** JSON with baseline ID, timestamp, URL, and summary of captured elements.
@@ -126,16 +126,16 @@ Fetches the current page state and diffs it against the most recent baseline.
**Execution:**
```bash
-python scripts/drift_compare.py <url>
-python scripts/drift_compare.py <url> --baseline-id 5
-python scripts/drift_compare.py <url> --skip-cwv
+python3 scripts/drift_compare.py <url>
+python3 scripts/drift_compare.py <url> --baseline-id 5
+python3 scripts/drift_compare.py <url> --skip-cwv
```
**Output:** JSON with all triggered rules, old/new values, severity, and actions.
After comparison, offer to generate an HTML report:
```bash
-python scripts/drift_report.py <comparison_json_file> --output drift-report.html
+python3 scripts/drift_report.py <comparison_json_file> --output drift-report.html
```
---
@@ -146,8 +146,8 @@ Shows all baselines and comparisons for a URL.
**Execution:**
```bash
-python scripts/drift_history.py <url>
-python scripts/drift_history.py <url> --limit 10
+python3 scripts/drift_history.py <url>
+python3 scripts/drift_history.py <url> --limit 10
```
**Output:** JSON array of baselines (newest first) with timestamps and comparison summaries.
diff --git a/skills/seo-ecommerce/SKILL.md b/skills/seo-ecommerce/SKILL.md
index d256468..a6e2831 100644
--- a/skills/seo-ecommerce/SKILL.md
+++ b/skills/seo-ecommerce/SKILL.md
@@ -42,8 +42,8 @@ Fetch and parse any product page for on-page SEO quality.
### Workflow
```
-1. python scripts/render_page.py <url> --mode auto → raw/rendered HTML
-2. python scripts/parse_html.py --url <url> → SEO elements
+1. python3 scripts/render_page.py <url> --mode auto → raw/rendered HTML
+2. python3 scripts/parse_html.py --url <url> → SEO elements
3. Analyze product-specific signals (below)
```
@@ -107,7 +107,7 @@ Live competitive analysis from Google Shopping results.
Before EVERY Merchant API call:
```bash
-python scripts/dataforseo_costs.py check merchant_google_products_search
+python3 scripts/dataforseo_costs.py check merchant_google_products_search
```
- `"status": "approved"` -- proceed
@@ -116,20 +116,20 @@ python scripts/dataforseo_costs.py check merchant_google_products_search
After each call:
```bash
-python scripts/dataforseo_costs.py log merchant_google_products_search <cost>
+python3 scripts/dataforseo_costs.py log merchant_google_products_search <cost>
```
### Workflow
```bash
# Product search: who sells what at what price
-python scripts/dataforseo_merchant.py search "<keyword>" --marketplace google
+python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace google
# Seller analysis: merchant ratings and dominance
-python scripts/dataforseo_merchant.py sellers "<keyword>"
+python3 scripts/dataforseo_merchant.py sellers "<keyword>"
# Normalize results for analysis
-python scripts/dataforseo_normalize.py results.json --module merchant
+python3 scripts/dataforseo_normalize.py results.json --module merchant
```
### Analysis Outputs
@@ -163,7 +163,7 @@ Cross-marketplace intelligence comparing Google Shopping and Amazon.
### Cost Guardrail (MANDATORY)
```bash
-python scripts/dataforseo_costs.py check merchant_amazon_products_search
+python3 scripts/dataforseo_costs.py check merchant_amazon_products_search
```
Amazon endpoints are in the `warn_endpoints` set -- always requires user approval.
@@ -172,10 +172,10 @@ Amazon endpoints are in the `warn_endpoints` set -- always requires user approva
```bash
# Amazon product search
-python scripts/dataforseo_merchant.py search "<keyword>" --marketplace amazon
+python3 scripts/dataforseo_merchant.py search "<keyword>" --marketplace amazon
# Cross-marketplace comparison
-python scripts/dataforseo_merchant.py compare "<keyword>"
+python3 scripts/dataforseo_merchant.py compare "<keyword>"
```
### Cross-Marketplace Report
@@ -313,10 +313,10 @@ capability examples, and the relationship to AP2 (Agent Payments Protocol).
```bash
# Discover and validate the UCP profile
-python scripts/ucp_check.py https://store.example.com --json
+python3 scripts/ucp_check.py https://store.example.com --json
# With endpoint reachability probes (HEAD each declared capability)
-python scripts/ucp_check.py https://store.example.com --probe-endpoints --json
+python3 scripts/ucp_check.py https://store.example.com --probe-endpoints --json
```
The script returns: profile presence, version, declared capabilities,
diff --git a/skills/seo-flow/SKILL.md b/skills/seo-flow/SKILL.md
index 609733f..72765b0 100644
--- a/skills/seo-flow/SKILL.md
+++ b/skills/seo-flow/SKILL.md
@@ -82,7 +82,7 @@ Load prompt files on demand — only for the stage the user requests.
2. Display the full index: all 41 prompts with stage, name, trigger conditions
### On `/seo flow sync`
-1. Run: `python scripts/sync_flow.py`
+1. Run: `python3 scripts/sync_flow.py`
2. Display the JSON summary (files added, updated, unchanged)
3. Show attribution notice after sync completes
diff --git a/skills/seo-google/SKILL.md b/skills/seo-google/SKILL.md
index aabca6f..f356f23 100644
--- a/skills/seo-google/SKILL.md
+++ b/skills/seo-google/SKILL.md
@@ -31,7 +31,7 @@ service account -- run `/seo google setup` for step-by-step instructions.
Before executing any command, check credentials:
```bash
-python scripts/google_auth.py --check --json
+python3 scripts/google_auth.py --check --json
```
Config file: `~/.config/claude-seo/google-api.json`
@@ -91,7 +91,7 @@ Always communicate the detected tier before running commands.
Combined Lighthouse lab data + CrUX field data.
-**Script:** `python scripts/pagespeed_check.py <url> --json`
+**Script:** `python3 scripts/pagespeed_check.py <url> --json`
**Reference:** `references/pagespeed-crux-api.md`
**Default:** Both mobile + desktop strategies, all Lighthouse categories.
@@ -102,13 +102,13 @@ Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.
CrUX field data only (no Lighthouse run). Faster.
-**Script:** `python scripts/pagespeed_check.py <url> --crux-only --json`
+**Script:** `python3 scripts/pagespeed_check.py <url> --crux-only --json`
### `/seo google crux-history <url>`
25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.
-**Script:** `python scripts/crux_history.py <url> --json`
+**Script:** `python3 scripts/crux_history.py <url> --json`
**Reference:** `references/pagespeed-crux-api.md`
Output includes per-metric trend direction, percentage change, and weekly p75 values.
@@ -121,7 +121,7 @@ Output includes per-metric trend direction, percentage change, and weekly p75 va
Search Analytics: clicks, impressions, CTR, position for last 28 days.
-**Script:** `python scripts/gsc_query.py --property <property> --json`
+**Script:** `python3 scripts/gsc_query.py --property <property> --json`
**Reference:** `references/search-console-api.md`
**Default:** 28 days, dimensions=query,page, type=web, limit=1000.
@@ -131,7 +131,7 @@ Includes quick-win detection: queries at position 4-10 with high impressions.
URL Inspection: real indexation status from Google.
-**Script:** `python scripts/gsc_inspect.py <url> --json`
+**Script:** `python3 scripts/gsc_inspect.py <url> --json`
Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state,
page fetch state, canonical selection, mobile usability, rich results.
@@ -140,7 +140,7 @@ page fetch state, canonical selection, mobile usability, rich results.
Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.
-**Script:** `python scripts/gsc_inspect.py --batch <file> --json`
+**Script:** `python3 scripts/gsc_inspect.py --batch <file> --json`
### `/seo google sitemaps <property>`
@@ -148,7 +148,7 @@ List submitted sitemaps with status, errors, warnings. Sitemap contents report
submitted counts only; URL Inspection API is the indexation truth for whether
specific URLs are indexed.
-**Script:** `python scripts/gsc_query.py sitemaps --property <property> --json`
+**Script:** `python3 scripts/gsc_query.py sitemaps --property <property> --json`
---
@@ -158,7 +158,7 @@ specific URLs are indexed.
Notify Google of a URL update.
-**Script:** `python scripts/indexing_notify.py <url> --json`
+**Script:** `python3 scripts/indexing_notify.py <url> --json`
**Reference:** `references/indexing-api.md`
The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages.
@@ -168,7 +168,7 @@ Always inform the user of this restriction. Daily quota: 200 publish requests.
Batch submit URLs from a file. Tracks quota usage.
-**Script:** `python scripts/indexing_notify.py --batch <file> --json`
+**Script:** `python3 scripts/indexing_notify.py --batch <file> --json`
---
@@ -178,7 +178,7 @@ Batch submit URLs from a file. Tracks quota usage.
Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement.
-**Script:** `python scripts/ga4_report.py --property <id> --json`
+**Script:** `python3 scripts/ga4_report.py --property <id> --json`
**Reference:** `references/ga4-data-api.md`
**Default:** 28 days, filtered to Organic Search channel group.
@@ -186,7 +186,7 @@ Organic traffic report: daily sessions, users, pageviews, bounce rate, engagemen
Top organic landing pages ranked by sessions.
-**Script:** `python scripts/ga4_report.py --property <id> --report top-pages --json`
+**Script:** `python3 scripts/ga4_report.py --property <id> --report top-pages --json`
---
@@ -198,7 +198,7 @@ YouTube mentions have the strongest AI visibility correlation (0.737). Free, API
Search YouTube for videos. Returns title, channel, views, likes, duration.
-**Script:** `python scripts/youtube_search.py search "<query>" --json`
+**Script:** `python3 scripts/youtube_search.py search "<query>" --json`
**Reference:** `references/youtube-api.md`
**Quota:** 100 units per search (10,000 units/day free).
@@ -206,7 +206,7 @@ Search YouTube for videos. Returns title, channel, views, likes, duration.
Detailed video info + tags + top 10 comments.
-**Script:** `python scripts/youtube_search.py video <video_id> --json`
+**Script:** `python3 scripts/youtube_search.py video <video_id> --json`
**Quota:** 2 units (video details + comments).
---
@@ -219,7 +219,7 @@ Google's own entity/sentiment analysis. Enhances E-E-A-T scoring.
Full NLP analysis: entities, sentiment, content classification.
-**Script:** `python scripts/nlp_analyze.py --url <url> --json` or `--text "..."`
+**Script:** `python3 scripts/nlp_analyze.py --url <url> --json` or `--text "..."`
**Reference:** `references/nlp-api.md`
**Free tier:** 5,000 units/month. Requires billing enabled on GCP project.
@@ -227,7 +227,7 @@ Full NLP analysis: entities, sentiment, content classification.
Entity extraction only (faster, less quota).
-**Script:** `python scripts/nlp_analyze.py --url <url> --features entities --json`
+**Script:** `python3 scripts/nlp_analyze.py --url <url> --features entities --json`
---
@@ -239,7 +239,7 @@ Gold-standard keyword volume data. Requires Google Ads account.
Generate keyword ideas from seed terms.
-**Script:** `python scripts/keyword_planner.py ideas "<seed>" --json`
+**Script:** `python3 scripts/keyword_planner.py ideas "<seed>" --json`
**Reference:** `references/keyword-planner-api.md`
**Requires:** Ads developer token + customer ID in config (Tier 3).
@@ -247,7 +247,7 @@ Generate keyword ideas from seed terms.
Search volume for specific keywords (comma-separated).
-**Script:** `python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json`
+**Script:** `python3 scripts/keyword_planner.py volume "<kw1>,<kw2>" --json`
---
@@ -280,7 +280,7 @@ After any analysis command, offer to generate a PDF/HTML report.
Generate a professional PDF report with charts and analytics.
-**Script:** `python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf`
+**Script:** `python3 scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf`
| Type | Input | Output |
|------|-------|--------|
@@ -291,8 +291,8 @@ Generate a professional PDF report with charts and analytics.
**Workflow:**
1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
-2. Save JSON output to file: `python scripts/pagespeed_check.py <url> --json > data.json`
-3. Generate report: `python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>`
+2. Save JSON output to file: `python3 scripts/pagespeed_check.py <url> --json > data.json`
+3. Generate report: `python3 scripts/google_report.py --type cwv-audit --data data.json --domain <domain>`
**Convention:** After completing analysis, suggest: "Generate a report? Use `/seo google report <type>`"
diff --git a/skills/seo-google/references/auth-setup.md b/skills/seo-google/references/auth-setup.md
index 4bbe5b3..ead57e3 100644
--- a/skills/seo-google/references/auth-setup.md
+++ b/skills/seo-google/references/auth-setup.md
@@ -106,7 +106,7 @@ Save to `~/.config/claude-seo/google-api.json`:
## Step 8: Verify Setup
```bash
-python scripts/google_auth.py --check
+python3 scripts/google_auth.py --check
```
Expected output at Tier 2 (full):
diff --git a/skills/seo-hreflang/references/machine-translation-qa.md b/skills/seo-hreflang/references/machine-translation-qa.md
index b575cce..75ff293 100644
--- a/skills/seo-hreflang/references/machine-translation-qa.md
+++ b/skills/seo-hreflang/references/machine-translation-qa.md
@@ -38,7 +38,7 @@ content abuse.
- For per-page hreflang validation, stay inside `seo-hreflang`.
- For broader scaled-content scoring (entropy of translated pages,
AI-pattern detection in body), defer to `seo-content` via
- `python scripts/content_quality.py`.
+ `python3 scripts/content_quality.py`.
- For "is this translated by Google's own auto-translate widget"
detection, look for the `.goog-te-banner-frame` iframe; auto-
translate widgets are explicitly exempted from MT-scaled-content
diff --git a/skills/seo-images/SKILL.md b/skills/seo-images/SKILL.md
index 2dbb1af..77cecd6 100644
--- a/skills/seo-images/SKILL.md
+++ b/skills/seo-images/SKILL.md
@@ -321,13 +321,13 @@ https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
```bash
# Audit a directory for the IPTC label (counts: missing, ai, captured, etc.)
-python scripts/iptc_ai_label.py audit ./images/ --json
+python3 scripts/iptc_ai_label.py audit ./images/ --json
# Audit a single image
-python scripts/iptc_ai_label.py audit ./hero.webp --json
+python3 scripts/iptc_ai_label.py audit ./hero.webp --json
# Inject the AI label into an image
-python scripts/iptc_ai_label.py inject ./ai-hero.webp \
+python3 scripts/iptc_ai_label.py inject ./ai-hero.webp \
--source-type trainedAlgorithmicMedia
# Other vocabulary values:
diff --git a/skills/seo-technical/SKILL.md b/skills/seo-technical/SKILL.md
index c63ff03..d944d1d 100644
--- a/skills/seo-technical/SKILL.md
+++ b/skills/seo-technical/SKILL.md
@@ -146,7 +146,7 @@ layout stability across templates, `cursor: pointer` correctness — live in
```bash
# Render with Playwright + capture accessibility tree, then score
-python scripts/agent_ux_check.py https://example.com --json
+python3 scripts/agent_ux_check.py https://example.com --json
```
The scanner outputs an Agent-UX score (0-100) plus itemized issues:
@@ -157,7 +157,7 @@ The scanner outputs an Agent-UX score (0-100) plus itemized issues:
The accessibility-tree snapshot uses Playwright's
`page.accessibility.snapshot(interesting_only=False)`. To capture the tree
-without scoring, use `python scripts/render_page.py <url> --a11y-tree --json`.
+without scoring, use `python3 scripts/render_page.py <url> --a11y-tree --json`.
Surface findings as **opportunities**, not failures. The standards (WebMCP,
agent UX heuristics) are early — don't gate audits on a sub-100 score.
@@ -190,7 +190,7 @@ If DataForSEO MCP tools are available, use `on_page_instant_pages` for real page
## Google API Integration (Optional)
-If Google API credentials are configured, use `python scripts/pagespeed_check.py <url> --json` for real PSI + CrUX field data (replaces lab-only CWV estimates), `python scripts/crux_history.py <url> --json` for 25-week CWV trends, and `python scripts/gsc_inspect.py <url> --json` for real indexation status per URL.
+If Google API credentials are configured, use `python3 scripts/pagespeed_check.py <url> --json` for real PSI + CrUX field data (replaces lab-only CWV estimates), `python3 scripts/crux_history.py <url> --json` for 25-week CWV trends, and `python3 scripts/gsc_inspect.py <url> --json` for real indexation status per URL.
## Error Handling
diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md
index 7909579..eb24d82 100644
--- a/skills/seo/SKILL.md
+++ b/skills/seo/SKILL.md
@@ -58,14 +58,14 @@ extension is also installable (see "Optional Extensions" below).
When the user invokes `/seo audit`, delegate to subagents in parallel:
1. Detect business type (SaaS, local, ecommerce, publisher, agency, other)
2. Spawn subagents: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, seo-geo
-3. If Google API credentials detected (`python scripts/google_auth.py --check`), also spawn seo-google agent
+3. If Google API credentials detected (`python3 scripts/google_auth.py --check`), also spawn seo-google agent
4. If local business detected, also spawn seo-local agent
5. If local business detected AND DataForSEO MCP available, also spawn seo-maps agent
-6. If backlink APIs detected (`python scripts/backlinks_auth.py --check`), also spawn seo-backlinks agent
+6. If backlink APIs detected (`python3 scripts/backlinks_auth.py --check`), also spawn seo-backlinks agent
7. If Firecrawl MCP available, use `firecrawl_map` to discover all site URLs before analysis
8. If content strategy signals detected (blog, pillar pages, topic clusters), also spawn seo-cluster agent
9. If e-commerce detected, also spawn seo-ecommerce agent
-10. If drift baseline exists for this URL (`python scripts/drift_history.py <url>`), also spawn seo-drift agent
+10. If drift baseline exists for this URL (`python3 scripts/drift_history.py <url>`), also spawn seo-drift agent
11. Always include seo-sxo in full audits (search experience applies to all sites)
12. Collect results and generate unified report with SEO Health Score (0-100)
13. **Synthesize via the 10-principle framework** (see "Synthesis Methodology" below) — walk PERCEIVE → ANALYZE → VALIDATE → ACT before bucketing findings into Critical / High / Medium / Low