seo

seo

is a local CLI, MCP server, and report engine using crawl, Search Console, Google Analytics or Clicky, optional Bing evidence, and optional research providers. Reports keep observations, estimates, findings, caveats, costs, and provenance separate. Storage stays local; requested crawls and provider operations still make direct network requests. Discover reports at runtime instead of memorising them.

Discover, describe, run

With the MCP server (preferred):

```
seo_list_reports
```
returns report ids and purposes, optionally by category.
```
seo_describe_report
```
returns one report's usage, schema, reading order, limits, verification, and related ids.
```
seo_run_report
```
runs bounded
```
params
```
. Read
```
structuredContent
```
, not display text.

The same catalog exists without MCP:

bash

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

; reuse its schema and do not guess parameters. When

fixableChecks

exists, fetch guidance only for failed or warning ids in

topActions

with

seo_describe_report

using

id

and

check

(CLI:

seo reports describe <report-id> --check <check-id>

Setup and selection

Use

setup-check

seo doctor

when auth is unknown. Select profiles with

--project <id>

and list them with

seo projects list --json

. Without one, pass

--site sc-domain:example.com

--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 a whole chain 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	`site-crawl` with `health: true` , `report` command (main report), full `site-crawl` only if needed, `top-fixes` , `ai-search-scorecard`
More clicks from existing pages	`quick-wins` , `ctr-underperformers` , `striking-distance` , `second-page` , `internal-links`
AI agent readiness for a content site	`agent-readiness` , `ai-readiness` , `entity-readiness` , `llms-txt-audit`
AI search visibility and eligibility	`ai-readiness` , `geo-gaps` , `ai-mention-research` , `ai-prompt-observations` , `ai-referrals` , `seo-to-ai-query`
Plan content from real demand	`query-clusters` , `page-opportunities` , `content-optimization` , `cannibalisation`
Research keywords and current results	`keyword-research` , `keyword-metrics` , `saved-keywords` , `serp-results`
Turn a topic into a keyword and competitor shortlist	`competitive-opportunities` , then inspect the decision-critical pages or links
Research local demand and page patterns	`local-search-demand` , then `serp-results` or `rank-tracking` for a fixed market when needed
Find search competitors and plausible gaps	`serp-competitors` , `domain-overview` , `ranking-pages` , `ranked-keywords` , `competitor-keyword-gap`
Research programmatic SEO patterns	`pseo-patterns` for observed queries and declared term, pair, or matrix sets; `pseo-opportunities` , `ranking-pages` , or `competitor-keyword-gap` for deeper research; then `pseo-audit` for existing templates
Catch regressions over time	`technical-watch` , `crawl-diff` , `index-watch` , `measure-change` after a fix ships
Track exact keyword positions	`rank-tracking` for a saved set and fixed market/device; `serp-results` for one current query
Review Bing traffic, crawl, query, and page insights	`bing-webmaster-overview` , then `site-crawl` when live page evidence is needed
Review backlink context and linked targets	`domain-rating` , `link-evidence` , then verify selected results, referring URLs, and flagged targets directly
Review real crawler requests in a server log	`server-log-analysis` , then verify important errors against the original log and server configuration
Client-ready reporting	`monthly-report` , `narrative-report` , `monthly-action-plan`
Turn crawl findings into tickets	`top-fixes` , `affected-urls` , `explain-crawl-issue`

Without provider API access, describe

ranked-keywords

ranking-pages

serp-competitors

, or

competitor-keyword-gap

and pass one to four local ranked-keyword exports through

researchFiles

. Read

evidence.imports

before using the rows. If headings are unfamiliar, use the report schema's explicit

columns

map rather than guessing. File dates, hashes, included fields, column mappings, filtered historical rows, rejected rows, and caps define the evidence boundary.

Use

seo report

first for a broad performance question with a known project. For a large or unfamiliar URL, run sitemap health before a full crawl.

Create a client HTML report

For a polished or branded report, create one standalone HTML file from structured data. Built-in

--format html

is a predictable fallback. Start with compact JSON and request

--full

only when deeper evidence is needed. Follow supplied brand direction and design for the findings. Use responsive, accessible, print-friendly HTML, embedded CSS,

noindex,nofollow

, and no remote scripts or assets.

Show site, period, generated date, provider labels, data status, priorities, limitations, and verification. Preserve partial, capped, sampled, missing, and skipped states. Keep observations separate from interpretation and providers separate from each other. Never invent scores, forecasts, causes, or missing values. Omit secrets and unnecessary raw rows. Save locally and report the path.

For a large site, run

site-crawl

with

health: true

and an explicit

sitemapUrl

when known. Read

config.strategy

access

, failures, limits, and sitemap completeness. Full crawl second only for page content, metadata, canonicals, links, structured data, or rendered HTML.

Requests use

SEO-Skill/<version> (+https://seoskill.dev)

. For

access.blockedRequests

, show provider evidence and the identity. Ask for a temporary exception scoped by audit IP, host or paths, and blocking rule. Never recommend a User-Agent-only bypass.

Evidence rules

Check
```
dataStatus
```
, selection counts,
```
caveats
```
, and
```
warnings
```
before summarising any report. Name skipped or incomplete evidence first.
Partial, capped, filtered, or sampled sources never support a zero or an all-clear. Grouped Search Console totals undercount because anonymised query rows are withheld.
Values marked heuristic are prioritisation aids, not forecasts. Never promise clicks, rankings, indexing, or AI citations from any report.
Quote
```
principle
```
and
```
evidenceRef
```
when explaining a recommendation, and give the user the report's verification step alongside any suggested change.
If a report returns no rows, say so plainly.
Intentional controls such as
```
noindex
```
, canonicals, and robots rules are observations until the user confirms they are unintended.
Provider traffic, volume, difficulty, visibility, intent, authority, and ranking history are estimates. Keep them separate from Search Console, connected analytics, crawl, and live result evidence.

Beyond the report catalog

Use

seo help all

for direct provider and administration commands. Bing setup uses

seo providers bing

; link evidence uses

seo links --project <id> --json

seo links --provider ahrefs --target <domain> --json

seo links --provider dataforseo --target <domain> --json

, or a local file. IndexNow writes externally: validate with

seo indexnow submit --dry-run --json

and remove dry run only when authorised. Receipt does not prove crawling or indexing. Prefer registered reports.

Use

refresh: true

--refresh

only when fresh data is requested. Sitemap health always bypasses page-body cache and never writes page responses.

seo

NPX Install

Tags

SKILL.md Content

seo