/seo

name: seo
description: Use and read this skill immediately if the user request is in any way related to SEO or a site's organic search or AI search presence. That includes site audits, rankings, keyword research, competitors, backlinks, click or traffic changes, indexing problems, crawling, redirects, sitemaps, metadata, structured data, Core Web Vitals, internal links, content opportunities, programmatic SEO, local search, Search Console, Google Analytics or Clicky questions, Google update impact, llms.txt, AI search visibility in ChatGPT, Claude, Perplexity, or Google AI Overviews, and client SEO reporting. Routes to evidence-backed local reports through the SEO CLI and MCP server.

seo

Use structured reports for evidence, then inspect source only where a finding needs it. Reports keep observations, findings, caveats, costs, and provenance separate. Data stays local unless a requested crawl or provider call needs the network.

Before the first CLI call, run `command -v seo`. If it is missing, run `npm i -g seo`, confirm `seo --version`, then continue. Use available MCP tools without reinstalling.

Broad audits and source changes

For a broad audit, run this before manual page exploration:

seo report --url <absolute-url> --search-console-export <path> --actions-only --json

Omit `--search-console-export` when no export was supplied. Capture the whole JSON. Do not pipe it through `head`.

Follow this sequence:

1. Read every field in `findings`, plus `inventories`, retained evidence, caveats, and warnings. A `fix` contains an instruction. A `review` contains change conditions; it is not an instruction to edit. 2. Compare the live homepage identity with source metadata and content. Treat the live product as current unless the user says the source is an undeployed pivot. Search history describes past demand, not product direction. 3. Track every finding id and exact title, plus every inventory URL. Counts must match `findings.counts.returned` and `returnedItems`. Decide inventory rows separately from their evidence; never apply one blanket policy. 4. Use the allowed outcomes. For a fix, choose `fixed`, `deferred`, or `not-needed`. For a review, answer its question and choose `changed`, `no-change`, or `deferred`, with an evidence-backed reason. Apply only supported changes. Build or test the source, run each changed item's verification, then rerun the same report against the local build. 5. Return both complete tables. Include each finding's outcome, reason, and verification, and each inventory URL's disposition and evidence.

Do not finish while a finding or inventory row is absent from the handoff. If an inventory returns `nextPage`, fetch every page first.

Discover, describe, run

With MCP:

1. `seo_list_reports` lists report ids and purposes. 2. `seo_describe_report` returns usage, schema, reading order, limits, verification, and related reports. 3. `seo_run_report` runs bounded `params`. Read `structuredContent`.

The CLI has the same catalog:

seo reports list --json
seo reports describe <report-id> --json
seo reports run <report-id> --params '<json>' --json

Describe a report before its first run. Follow `readOrder`, `doNotClaim`, and `related`; do not guess parameters. For fixes, pass `view: "actions"` to MCP or `--actions-only` to the JSON CLI command.

Installed provider packages can also add agent actions. Discover them before calling provider-specific data:

seo providers list --json
seo providers describe <provider-id> --json
seo providers run <provider-id> <action-id> --params '<json>' --json

Use the described input schema. Treat the returned provider data as evidence with its named source and limits. A provider action is not a report finding.

Setup and selection

Use `setup-check` or `seo doctor` when auth is unknown. Use `--project <id>` for a saved project. Without one, pass `--site sc-domain:example.com` or `--url https://example.com`. Crawl audits need no Google connection. Agent commands use `--json`, which never prompts.

Common jobs

Run the first report, read it, then decide. Do not run every report blindly.

| Job | Reports | |---|---| | Page not indexed or missing from Google | `index-coverage`, `index-monitor` (URL Inspection), `audit-page`, `redirect-trace` | | Traffic or clicks dropped | `search-performance-overview`, `traffic-anomaly`, `update-correlation`, `segment-impact`, `decaying-pages`, `link-recovery` | | Audit a whole site | `report`, then `site-crawl`, `top-fixes`, or `ai-search-scorecard` when needed | | More clicks from existing pages | `quick-wins`, `ctr-underperformers`, `striking-distance`, `second-page`, `internal-links` | | AI search visibility or readiness | `ai-readiness`, `agent-readiness`, `geo-gaps`, `ai-mention-research`, `ai-prompt-observations`, `ai-referrals` | | Plan content from real demand | `query-clusters`, `page-opportunities`, `content-optimization`, `cannibalisation` | | Research keywords and competitors | `competitive-opportunities`, `keyword-research`, `serp-results`, `ranked-keywords`, `ranking-pages`, `serp-competitors`, `competitor-keyword-gap` | | Local or programmatic SEO | `local-search-demand`, `pseo-patterns`, `pseo-opportunities`, `pseo-audit` | | Links, Bing, or server logs | `domain-rating`, `link-evidence`, `bing-webmaster-overview`, `server-log-analysis` | | Catch regressions | `technical-watch`, `crawl-diff`, `index-watch`, `measure-change` | | Client-ready reporting | `monthly-report`, `narrative-report`, `monthly-action-plan` | | Turn crawl findings into tickets | `top-fixes`, `affected-urls`, `explain-crawl-issue` |

When provider access is unavailable, describe the report and use its `researchFiles` and `columns` schema. Read import provenance and never guess column mappings.

For a branded client report, use built-in HTML output or create one standalone local HTML file from structured JSON. Preserve evidence st