seo-audit · diff

git:20261009.579f4fa to git:20261105.f7f8170

89 added, 36 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: seo-audit
- description: Run a one-step-seo audit and turn findings into a prioritized action plan.
+ description: Run one-step-seo against a URL, local HTML file, or build directory, interpret the independent Search SEO and AI Visibility scores, and return an evidence-backed P0-P3 remediation plan.
---
- # seo-audit sub-skill
+ # seo-audit — End-to-End SEO & AI Visibility Audit
- ## Steps
+ ## 1. Description & Activation Criteria
- 1. Confirm target URL + scope (single page vs `--pages N` crawl). For
- beginners, `quick` applies sensible defaults (5 pages, all formats):
- ```bash
- npx one-step-seo quick <url> --out ./seo-report
- ```
- 2. Otherwise run:
- ```bash
- npx one-step-seo audit <url> --pages 5 --out ./seo-report --format html,md,json
- ```
- For CI gating, add `--fail-on P0` (exits 2 on critical findings).
- If the audit reports a `T05-robots-disallow` refusal, stop and ask the
- user before re-running with `--force`.
- 3. Open `report.json`. Summarize:
- - Search SEO score + band, AI Visibility score + band
- - Top P0/P1 findings with evidence quotes
- - Page-by-page notes for multi-page runs (`index.html` dashboard first for
- totals and worst pages, `index.md` for links)
- 4. Output sections:
- - Executive summary (3 bullets — reuse the report's verdict)
- - Priority actions (Problem → Evidence → Action → Impact → Effort → Owner)
- - Passed checks (1 line each)
- - 30/60/90-day plan
- 5. Never blend the two scores. Never promise rankings.
+ Use `seo-audit` when the user asks to:
- ## Reading report.json
+ - Audit a website, single page, local HTML file, or static build folder (`./dist`, `./out`, `./public`) for SEO or AI search visibility.
+ - Interpret `report.json`, `report.md`, `report.html`, or multi-page `index.html` outputs.
+ - Produce a prioritized P0–P3 remediation plan with effort, impact, and owner triage.
+ - Check why a page is underperforming in traditional search or generative answer engines (ChatGPT Search, Claude, Perplexity, Google AI Overviews).
- Stable shape (`lib/schema-report.json`): `scores.{search,ai}.{score,band}`,
- `counts.{P0,P1,P2,P3,pass}`, `findings[]` (priority-sorted P0 first),
- `page.*` facts, `site.*` booleans. `report.md` adds triage labels and
- snippets per finding — quote them instead of inventing your own.
+ Do **not** activate this skill to directly mutate user HTML files without first running an audit; use `seo-fix` after user approval for local file edits.
- ## Severity guide
+ ## 2. Inputs & Prerequisites
- - P0: page not indexable / no HTTPS / no title — fix today
- - P1: title/meta/H1/alt/sitemap/answer-block — fix this week
- - P2: OG, FAQ, tables, image dims, llms.txt — fix this month
- - P3: polish (twitter:card, og:url, hreflang, entity drift, llms structure)
+ - **Target (required)**: Public `http(s)` URL, local `.html`/`.htm` path, or build directory.
+ - **Node.js**: `>=18.0.0` (verify via `npx one-step-seo doctor`).
+ - **Optional parameters**:
+ - `--pages <1..200>`: Maximum pages to crawl (default `1` for `audit`, `5` for `quick`).
+ - `--crawl <links|sitemap>`: Discovery strategy (`links` BFS or `sitemap` XML seeding).
+ - `--profile <default|blog|product|docs|home>`: Page-type threshold calibration.
+ - `--skills <list>` / `--exclude-skills <list>`: Domain-scoped check filtering.
+ - `--psi`: Live Google PageSpeed Insights lab + CrUX field metrics (requires `PSI_API_KEY`).
+
+ ## 3. Step-by-Step Workflow
+
+ 1. **Select the execution mode**:
+ - Single live URL or local HTML file: `npx one-step-seo page <target> --out ./seo-report`
+ - Multi-page site audit: `npx one-step-seo audit <target> --pages 10 --crawl sitemap --out ./seo-report`
+ - Fast 5-page overview: `npx one-step-seo quick <target> --out ./seo-report`
+ - Offline build folder audit: `npx one-step-seo audit ./dist --pages 20 --offline --out ./seo-report`
+ 2. **Read the canonical machine artifact (`./seo-report/report.json`)**:
+ - Inspect `scores.search` (`0-100`, band `A-F`) and `scores.ai` (`0-100`, band `A-F`). Never average or blend the two scores.
+ - Check `truncated` (whether HTML exceeded the 5 MiB cap) and `counts` (`P0`, `P1`, `P2`, `P3`, `pass`).
+ - Check whether `T05-robots-disallow` is the sole finding (indicating `robots.txt` blocked the crawl and `--force` is needed only if the user owns the site).
+ 3. **Triage findings by severity and reach**:
+ - **P0 (Critical blockers, -25 Search)**: `T01-https`, `T02-status`, `T07-noindex`, `O01-title-missing`, `S01-json-invalid`. Fix immediately.
+ - **P1 (High impact, -10 Search)**: `T03-redirects`, `T05-robots`, `T06-sitemap`, `T08-canonical`, `T13-mixed` (active), `T16-broken-links`, `T17-canonical-http`, `O02-meta-missing`, `O03-h1-missing`, `O03-h1-multi`, `O08-alt`, `O10-internal`, `C01-thin`, `S01-none`, `G02-ai-blocked`.
+ - **P2 (Medium optimization, -3 Search)**: Title/meta length, heading order, `O06-og`, `O07-favicon`, `O09-img-dims`, `C02-answer`, `C03-extractable`, `S02-*` schema properties, `G01-llms`, `G03-facts`, `G09-snippet-controls`, `P01-html-size`, `P02-img-count`, `T14-third-party`.
+ - **P3 (Polish & GEO depth, -1 Search or GEO-only)**: `O03-h1-drift`, `O11-generic-anchors`, `C04-faq`, `C05-table-headers`, `S03-faq-parity`, `G04-entity`, `G05-llms-quality`, `G06-freshness`, `G07-question-headings`, `G08-stat-density`, `G10-author`, `G11-semantic-content`, `T15-security-headers`, `W01-social`, `W02-og-url`, `W03-hreflang`.
+ 4. **Synthesize the action plan**:
+ - Group recommendations into Immediate Blockers (P0/P1), Content & Schema Enhancements (P2), and AI Citability / Polish (P3).
+ - Provide the exact verification command to re-run after fixes.
+
+ ## 4. Tools & CLI Commands
+
+ ```bash
+ # Single page audit (URL or local file)
+ npx one-step-seo page https://example.com --out ./seo-report
+
+ # Multi-page crawl seeded from sitemap with broken-link verification
+ npx one-step-seo audit https://example.com --pages 15 --crawl sitemap --check-links --out ./seo-report
+
+ # Offline static build directory audit
+ npx one-step-seo audit ./dist --pages 25 --offline --out ./seo-report
+ ```
+
+ ## 5. Evidence Requirements
+
+ - Every claim in your summary **must** cite the finding `id` (e.g., `T08-canonical`), `severity` (`P1`), and exact `evidence` string from `report.json`.
+ - Quote actual measured values from `report.page` (`titleLength`, `metaDescriptionLength`, `wordCount`, `h1`, `schemaTypes`) and `report.site` (`robots`, `sitemap`, `sitemapUrls`, `llmsTxt`, `aiCrawlersBlocked`).
+ - Never invent unmeasured metrics, search volume, backlink counts, or ranking positions.
+
+ ## 6. Expected Outputs
+
+ Present a structured response containing:
+
+ 1. **Scorecard**: Search SEO (`score/100`, band) and AI Visibility (`score/100`, band) side by side, plus `P0 / P1 / P2 / P3 / pass` counts.
+ 2. **One-Sentence Verdict**: Plain-language health summary (matching `report.md` executive summary).
+ 3. **Top 3 Urgent Fixes**: Finding ID, severity, evidence, recommended fix, and `Impact / Effort / Owner`.
+ 4. **AI Visibility & Citability Checklist**: Passing (`[x]`) vs missing (`[ ]`) signals from `scores.ai.details.signals`.
+ 5. **Artifacts & Verification Command**: Paths to `report.html`, `index.html`, `report.md`, and `report.json`, plus the re-run CLI command.
+
+ ## 7. Limitations & External Data
+
+ - **Readiness signals, not Google scores**: Scores measure adherence to documented technical SEO and AI extractability best practices, not live search rankings.
+ - **Static HTML parsing**: Evaluates server-rendered or static HTML response bodies (up to 5 MiB); client-only JavaScript DOM mutations after hydration are not executed.
+ - **External data**: Core Web Vitals (`P03-psi-lab`, `P04-psi-field`) are only populated when `--psi` is run with `PSI_API_KEY`. Missing PSI metrics are reported as `null` / unavailable, never `0`.
+
+ ## 8. Safety & Approval Rules
+
+ - Respect `robots.txt` by default. Only pass `--force` if the user explicitly confirms they own the target property and want to bypass `robots.txt` for diagnostic testing.
+ - Use `--block-private-ips` when auditing untrusted or user-supplied URLs to enforce SSRF and DNS-rebinding protections.
+ - Never modify source or build files during `seo-audit`; transition to `seo-fix` and request approval before applying file changes.
+
+ ## 9. Examples
+
+ ```bash
+ # Audit a product page with the product calibration profile
+ npx one-step-seo page https://example.com/shop/backpack --profile product --out ./seo-report
+
+ # Audit a documentation site and fail CI if any P0 or P1 findings exist
+ npx one-step-seo audit https://docs.example.com --pages 10 --profile docs --fail-on P1 --out ./seo-report
+ ```