seo 0.0.14 → 0.1.0

package/skills/crawl-diff/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: crawl-diff
+description: Compare a bounded same-origin crawl with its previous saved snapshot; use it to review technical changes after a release without claiming complete site coverage.
+---
+
+# Compare crawl snapshots
+
+Use `crawl-diff` after a deploy, migration, or planned technical change. It
+crawls a bounded same-origin set, saves the result, and compares it with the
+previous saved run for the same surface. This turns status, indexability,
+canonical, metadata, content, and inventory movement into a review queue. It
+does not prove that a changed page affected search performance.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"monitoring"}`, then call
+`seo_describe_report` with `{"id":"crawl-diff"}`. Run the exact schema with
+`seo_run_report`, for example
+`{"id":"crawl-diff","params":{"startUrl":"https://example.com/","site":"sc-domain:example.com","limit":250,"js":false,"refresh":true}}`.
+
+CLI parity uses the same definition:
+
+```sh
+seo reports describe crawl-diff --json
+seo reports run crawl-diff --params '{"startUrl":"https://example.com/","site":"sc-domain:example.com","limit":250,"refresh":true}' --json
+```
+
+The schema types `limit` as a broad number. Pass a positive whole-page bound and
+keep it stable between comparison runs.
+
+## Interpret the output
+
+Compare `run` with `previousRun` before reading `summary`. A missing previous
+run means the current crawl is a baseline, not a change result. Check the start
+URL, limit, URL count, timestamps, rendering choice, and `warnings` for both
+runs.
+
+`summary` counts crawled, added, removed, changed, new errors, indexability
+flips, and high-priority recommendations. Trace every important count into
+`items`, where `before`, `after`, and `changes` preserve observed evidence.
+`recommendations` rank review actions; they do not override the raw snapshots.
+A removed URL may be outside the current discovered set or limit rather than
+deleted. A fetch or extraction failure cannot support a resolved issue.
+
+## Act safely
+
+Verify high-priority status and indexability changes directly, then compare the
+deployment intent. Restore accidental failures or controls, but leave intended
+redirects, canonicals, and noindex directives alone. Repeat with comparable
+scope after a fix. Never call a bounded diff an inventory-wide audit or infer
+ranking impact from technical change alone.

package/skills/crawl-diff/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Crawl diff"
+  short_description: "Compare a bounded live crawl with its previous snapshot"
+  default_prompt: "Use $crawl-diff to run the crawl-diff report and explain its evidence and limits."

package/skills/crawl-history/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: crawl-history
+description: Discover locally saved crawl snapshots and their compact metadata without loading full evidence. Use to select stable report ids for follow-ups, comparisons, or verification.
+---
+
+# List saved crawl reports
+
+This report is the index for local crawl history. It returns metadata only, ordered newest first, so an agent can choose a snapshot without loading pages and issues or fetching the site again. It says what is stored locally, not what is currently true online.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` if discovery is needed. Call `seo_describe_report` with `{ "id": "crawl-history" }`, then `seo_run_report` with:
+
+```json
+{
+  "id": "crawl-history",
+  "params": {
+    "site": "sc-domain:example.com",
+    "limit": 10
+  }
+}
+```
+
+Confirm MCP `isError` is false, then consume `structuredContent`. The equivalent CLI commands are:
+
+```sh
+seo reports describe crawl-history --json
+seo reports run crawl-history --params '{"site":"sc-domain:example.com","limit":10}' --json
+```
+
+The site filter prevents an unrelated recent crawl from becoming the implicit source. Increase `limit` only when older baselines are genuinely needed.
+
+## Choose a source deliberately
+
+Review each report's id, site, start URL, creation time, status, total pages, issue count, configuration hash, and storage version. Counts are orientation metadata, not enough to judge severity or data completeness. A smaller page count could reflect a scope change, cap, failure, or real site change.
+
+Select an explicit id and load it with `crawl-report` before analysis. For a comparison, inspect both candidates' configuration and caveats instead of assuming adjacent timestamps are comparable. If the expected snapshot is absent, do not silently substitute another site or a fresh crawl; state that the local report was not found. Report lists can also expose old data, so include the creation time whenever presenting a saved finding as context.

package/skills/crawl-history/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "List crawl reports"
+  short_description: "List saved crawl metadata"
+  default_prompt: "Use $crawl-history to run the crawl-history report and explain its evidence and limits."

package/skills/crawl-report/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: crawl-report
+description: Load a saved crawl snapshot without fetching the site again and opt into detailed evidence only when needed. Use for investigation, verification, or a stable source for follow-up reports.
+---
+
+# Load a saved crawl report
+
+Saved reports make technical analysis reproducible: several follow-ups can use the same crawl instead of observing the site at different times. Loading a report is a local storage operation, not a fresh check, so always retain its creation time and original crawl boundaries in the explanation.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` only for report discovery. Call `seo_describe_report` with `{ "id": "crawl-report" }`, then call `seo_run_report` with:
+
+```json
+{
+  "id": "crawl-report",
+  "params": {
+    "id": "crawl_example_20260710",
+    "includeIssues": true
+  }
+}
+```
+
+Check `isError` and use MCP `structuredContent`. CLI parity is:
+
+```sh
+seo reports describe crawl-report --json
+seo reports run crawl-report --params '{"id":"crawl_example_20260710","includeIssues":true}' --json
+```
+
+Omitting `id` loads the latest saved report, optionally filtered by `site`. Use an explicit id whenever reproducibility matters. `includePages` adds request and page records; `includeIssues` adds the issue inventory.
+
+## Read the snapshot
+
+Confirm `id`, source URL and site, `generatedAt`, definition id, configuration hash, crawl status, and `requestEvidenceStatus`. Then inspect summary counts, `pageLimitReached`, data sources, warnings, and caveats. Provider states and crawl completeness determine which conclusions are supported.
+
+Keep the default compact result for orientation. Request large page or issue arrays only to answer a concrete question, and filter downstream work by stable rule and URL fields rather than parsing rendered text. A report can be internally valid yet stale, capped, or partial. It cannot prove the current live state. For comparisons, load both reports and establish equivalent scope before interpreting deltas; for verification, run a new crawl with the same configuration and retain both report ids.

package/skills/crawl-report/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Get crawl report"
+  short_description: "Load one saved crawl report"
+  default_prompt: "Use $crawl-report to run the crawl-report report and explain its evidence and limits."

package/skills/crawler-rules/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: crawler-rules
+description: Discover stable crawler rule ids with their categories and guidance metadata before querying findings. Use when an agent needs a valid filter for explanations or affected-URL reports.
+---
+
+# Discover crawler rules
+
+Rules are the stable vocabulary connecting crawl issues, summaries, affected URLs, and remediation guidance. Listing them answers "which checks exist?" It does not say that a site triggered those checks or that every listed convention is a search-engine requirement.
+
+## Run it
+
+For MCP, use `seo_list_reports` with category `crawl` only if report discovery is needed. Call `seo_describe_report` with `{ "id": "crawler-rules" }`, then `seo_run_report` with:
+
+```json
+{
+  "id": "crawler-rules",
+  "params": { "category": "metadata" }
+}
+```
+
+Read `structuredContent` after checking `isError`. CLI parity is:
+
+```sh
+seo reports describe crawler-rules --json
+seo reports run crawler-rules --params '{"category":"metadata"}' --json
+```
+
+Omit `category` to discover the full inventory. Useful categories include response, indexability, canonical, metadata, headings, content, links, images, structured-data, international, performance, mobile, security, social, and geo.
+
+## Use ids, not prose
+
+Read the returned id, title, category, default severity, and guidance metadata. Pass the exact id to `explain-crawl-issue` for the rule contract or to `affected-urls` for crawl evidence. Do not infer that similarly named rules have identical source semantics, and do not create implementation work from the catalog alone.
+
+The category input is constrained to the crawler's supported category enum. Describe the report before filtering and pass one of those exact values; unknown or misspelled categories are rejected as invalid input rather than becoming a misleading empty result. A valid category can still return no rules if the registry changes, so use the unfiltered inventory for discovery. Treat default severity as general triage metadata; actual priority comes from affected pages, observed evidence, scope, intent, and available demand data.

package/skills/crawler-rules/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "List rules"
+  short_description: "List crawler rule ids and guidance metadata"
+  default_prompt: "Use $crawler-rules to run the crawler-rules report and explain its evidence and limits."

package/skills/ctr-underperformers/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: ctr-underperformers
+description: Find high-impression page-one GSC rows below a site-aware CTR benchmark; use when an agent needs a bounded snippet review queue with heuristic shortfalls kept explicit.
+---
+
+# CTR underperformers
+
+Use this report to prioritise retained query/page rows whose observed CTR is materially below a position-based benchmark. It aggregates duplicate rows before analysis and prefers a robust site-aware peer benchmark when enough evidence exists, otherwise it uses a built-in fallback curve. The result can identify snippets worth reviewing, but it cannot observe the live SERP layout, explain user intent, isolate title or description effects, or promise that the calculated shortfall is recoverable.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"opportunities"}`.
+2. Call `seo_describe_report` with `{"id":"ctr-underperformers"}`.
+3. Call `seo_run_report` with `{"id":"ctr-underperformers","params":{"site":"sc-domain:example.com","minImpressions":250,"includeBrand":false}}`.
+
+The CLI calls the same handler:
+
+```sh
+seo reports describe ctr-underperformers --json
+seo reports run ctr-underperformers --params '{"site":"sc-domain:example.com","minImpressions":250,"includeBrand":false}' --json
+```
+
+`site` is required. This catalog schema exposes only `minImpressions` and `includeBrand`; the report itself uses a final-data 28-day window and reports its output limit in `summary`.
+
+## Interpret and act
+
+Check `dataStatus`, `range`, `source.completeness`, `possiblyTruncated`, validation counts, and `selection` before looking at the queue. Invalid rows make the report partial; duplicate rows are aggregated, not silently counted twice. For every item, keep query, URL, impressions, position, observed CTR, target CTR, benchmark source/confidence, and estimated shortfall together. The shortfall is directional prioritisation math, not a traffic forecast. Page-one average position also hides day, device, geography, and result-feature variation.
+
+Safe actions are to inspect the current SERP and displayed title link, confirm the page matches intent, then test clearer framing where evidence supports it. Annotate the change and compare a complete later period. Do not rewrite already appropriate copy merely to chase the benchmark, infer causation from CTR alone, or call a partial empty result an all-clear.

package/skills/ctr-underperformers/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CTR underperformers"
+  short_description: "Find retained GSC queries below a position-based CTR benchmark"
+  default_prompt: "Use $ctr-underperformers to run the ctr-underperformers report and explain its evidence and limits."

package/skills/decaying-pages/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: decaying-pages
+description: Compare retained GSC query-page rows across equal finalized windows to find observed click declines; use when an agent needs a bounded investigation queue without invented attribution.
+---
+
+# Decaying queries and pages
+
+Use this report to identify retained query/page combinations that lost clicks between adjacent equal-length periods or year-over-year windows. It requires evidence in both windows, excludes URL shifts, and groups returned rows by diagnosis signal and page template. This avoids turning a row missing from GSC's retained query data into zero traffic. The report shows observed movement, not why it happened.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"opportunities"}`.
+2. Call `seo_describe_report` with `{"id":"decaying-pages"}`.
+3. Call `seo_run_report` with `{"id":"decaying-pages","params":{"site":"sc-domain:example.com","days":28,"comparison":"previous-period","limit":20,"minDropPct":20,"minPreviousClicks":10,"minClickLoss":5}}`.
+
+The CLI uses the same report definition:
+
+```sh
+seo reports describe decaying-pages --json
+seo reports run decaying-pages --params '{"site":"sc-domain:example.com","days":28,"comparison":"previous-period","limit":20,"minDropPct":20,"minPreviousClicks":10,"minClickLoss":5}' --json
+```
+
+`site` is required. Choose `year-over-year` only when the requested window fits GSC's available history. Brand terms and `includeBrand` control navigational-query filtering.
+
+## Interpret and act
+
+Read `dataStatus`, `ranges`, and `source.completeness` first. Check current and previous fetched rows, caps, truncation, invalid rows, excluded URL shifts, and output limits in `selection`. `summary.observedRetainedQueryClickLoss` covers eligible retained rows; `returnedObservedRetainedQueryClickLoss` covers only the bounded output. Each item preserves current and previous clicks, impressions, CTR, position, `clickLoss`, `dropPct`, signals, and an evidence scope of `retained-query-page-row`. A diagnosis such as `lost_position` or `lost_ctr` labels correlated movement, not a cause.
+
+Safe actions include checking deployments and annotations, live indexability, SERP composition, demand seasonality, and page-template patterns before editing. Use groups to find repeated technical or content hypotheses, then verify individual URLs. Do not sum capped rows into a property-wide loss, treat missing retained rows as zero, or claim that a content change, ranking update, or technical issue caused the decline without separate evidence.

package/skills/decaying-pages/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Decaying queries and pages"
+  short_description: "Find observed click declines across retained GSC windows"
+  default_prompt: "Use $decaying-pages to run the decaying-pages report and explain its evidence and limits."

package/skills/entity-readiness/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: entity-readiness
+description: Inventory entity-related markup and identity signals without claiming recognition or authority. Use when reviewing schema types, names, authors, dates, sameAs links, and social references across crawlable pages.
+---
+
+# Review entity readiness
+
+Consistent names, authorship, structured data, and external identity references can make a site easier to interpret. This report measures those observable signals across evaluated pages. It does not score authority, validate ownership of linked profiles, or prove that any search or AI system recognizes an entity.
+
+## Run it
+
+For MCP, discover the report with `seo_list_reports` category `crawl` only when necessary. Call `seo_describe_report` with `{ "id": "entity-readiness" }`, then `seo_run_report` with:
+
+```json
+{
+  "id": "entity-readiness",
+  "params": { "reportId": "crawl_example_20260710" }
+}
+```
+
+Use `structuredContent` after confirming `isError` is false. CLI parity is:
+
+```sh
+seo reports describe entity-readiness --json
+seo reports run entity-readiness --params '{"reportId":"crawl_example_20260710"}' --json
+```
+
+Pass `url` only when a fresh crawl is intended. A saved report keeps this inventory aligned with other technical findings.
+
+## Read the observations
+
+Check `dataStatus`, `evaluatedPages`, `crawlPages`, and caveats before interpreting coverage. The analysis evaluates eligible, successfully fetched pages; skipped or non-indexable pages are not evidence of absence. Checks are informational observations with counts and coverage, not pass/fail requirements.
+
+Use `entities.schemaTypes` to see which types were parsed, `sameAsByType` and `sameAs` to review identity references, `socialProfiles` to inspect linked profiles, and `authors` to find observed bylines or structured authors. Sample the source pages before recommending global markup changes: a product, article, person, and organization need different semantics. Fix malformed or inconsistent markup only when the page's real subject supports it. Confirm names, URLs, authorship, and dates with the publisher, then re-crawl the same scope. Never infer Knowledge Graph inclusion, ownership, expertise, rankings, visibility, or citations from these signals alone.

package/skills/entity-readiness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Entity readiness"
+  short_description: "Review entity-related site observations"
+  default_prompt: "Use $entity-readiness to run the entity-readiness report and explain its evidence and limits."

package/skills/explain-crawl-issue/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: explain-crawl-issue
+description: Translate one crawler rule id into technical meaning, remediation guidance, and a verification method. Use after a crawl identifies a rule and before turning it into implementation work.
+---
+
+# Explain a crawler rule
+
+Crawler findings use stable rule ids so agents can join summaries, affected URLs, and guidance without parsing prose. This report explains the rule definition; it does not inspect a site or prove that the rule triggered on any particular page.
+
+## Run it
+
+If the id is unknown, use `crawler-rules` first. For MCP report discovery, call `seo_list_reports` with category `crawl` only when needed. Then call `seo_describe_report` with `{ "id": "explain-crawl-issue" }` and `seo_run_report` with:
+
+```json
+{
+  "id": "explain-crawl-issue",
+  "params": { "ruleId": "missing_title" }
+}
+```
+
+Check MCP `isError`, then read `structuredContent`. The exact CLI equivalent is:
+
+```sh
+seo reports describe explain-crawl-issue --json
+seo reports run explain-crawl-issue --params '{"ruleId":"missing_title"}' --json
+```
+
+## Apply the guidance carefully
+
+Read the rule's category, default severity, why it matters, fix steps, ignored impact, verification method, and agent hints. Default severity is generic prioritization metadata; actual urgency depends on affected templates, page purpose, response state, demand evidence, and publisher intent. Guidance describes the condition checked by the crawler, not a search-engine penalty or guaranteed ranking effect.
+
+Pair the definition with `affected-urls` from the same saved crawl. Inspect the per-URL evidence and sample enough page types to find the implementation boundary. For `missing_title`, for example, confirm that the final HTML truly lacks a useful title and that the crawler did not receive an error or intermediate response before changing a template. Create the smallest shared fix, preserve intentional controls, and use the stated verification method on the same bounded URLs. If no affected-URL evidence exists, present the output as reference documentation only.

package/skills/explain-crawl-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Explain issue"
+  short_description: "Explain one crawler rule"
+  default_prompt: "Use $explain-crawl-issue to run the explain-crawl-issue report and explain its evidence and limits."

package/skills/generate-llms-txt/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: generate-llms-txt
+description: Generate a bounded llms.txt draft from eligible crawl pages while exposing its URL and token budgets. Use when an agent needs a reviewable starting point rather than an automatically publishable file.
+---
+
+# Generate an llms.txt draft
+
+This report turns crawl evidence into concise agent-facing navigation. It selects successfully fetched, indexable pages, removes common utility paths, groups suitable URLs, and stops at explicit URL and token budgets. The output is a draft: the crawler cannot determine publisher intent or guarantee factual summaries.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` only if discovery is needed. Call `seo_describe_report` with `{ "id": "generate-llms-txt" }`, then call `seo_run_report` with:
+
+```json
+{
+  "id": "generate-llms-txt",
+  "params": {
+    "reportId": "crawl_example_20260710",
+    "maxUrls": 50,
+    "tokenBudget": 4000,
+    "exclude": ["/account/*", "/search"]
+  }
+}
+```
+
+Check `isError` and consume `structuredContent`. CLI parity is:
+
+```sh
+seo reports describe generate-llms-txt --json
+seo reports run generate-llms-txt --params '{"reportId":"crawl_example_20260710","maxUrls":50,"tokenBudget":4000,"exclude":["/account/*","/search"]}' --json
+```
+
+## Review before publishing
+
+Inspect `content`, `includedUrls`, `estimatedTokens`, and `sections`. Confirm every URL is canonical, public, current, useful to an agent, and safe to promote. Review generated titles and descriptions against the pages themselves. Use exclusions for private, transactional, faceted, search, or low-value routes, and keep the file deliberately small.
+
+Load the source with `crawl-report` to check its date, page cap, failures, and caveats. The generator currently does not return a separate candidate count, omitted count, source metadata block, or explicit truncation flag. Reaching `maxUrls` or the token budget should therefore be treated as possible truncation, not a complete inventory. A technically valid draft does not prove search or AI benefit, selection, indexing, visibility, or citations. Publish only after human review, then fetch the final file and validate its links.

package/skills/generate-llms-txt/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Generate llms.txt"
+  short_description: "Generate an llms.txt draft from crawl evidence"
+  default_prompt: "Use $generate-llms-txt to run the generate-llms-txt report and explain its evidence and limits."

package/skills/geo-gaps/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: geo-gaps
+description: Find URL-level technical barriers to AI-search eligibility while keeping access and selection separate. Use when reviewing response, crawl, indexability, canonical, or snippet restrictions from a crawl.
+---
+
+# Find AI-search eligibility gaps
+
+Content cannot be selected when a system cannot retrieve or use it, but technical access never guarantees selection. This report narrows crawl evidence to response failures, robots restrictions, non-indexing directives, canonicalized pages, and snippet controls. It is a diagnostic URL list, not a visibility score.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` only if discovery is required. Call `seo_describe_report` with `{ "id": "geo-gaps" }`, then call `seo_run_report` with:
+
+```json
+{
+  "id": "geo-gaps",
+  "params": {
+    "reportId": "crawl_example_20260710",
+    "limit": 25
+  }
+}
+```
+
+Confirm `isError` is false and consume `structuredContent`. The CLI flow is:
+
+```sh
+seo reports describe geo-gaps --json
+seo reports run geo-gaps --params '{"reportId":"crawl_example_20260710","limit":25}' --json
+```
+
+## Interpret each gap
+
+For every URL, separate `issues` from `searchEligibility`. Review successful HTML response, crawl permission, indexable-candidate status, declared and effective indexability, canonical evidence, and snippet eligibility. A `null` access state means unknown, not allowed. Semantic HTML, structured data, authorship, dates, question headings, and answerable blocks are observations; they do not override a hard access restriction or create eligibility by themselves.
+
+Read `dataStatus`, `source`, and `selection` before interpreting the URL list. `source.partialReasons` explains missing page or request evidence, an incomplete crawl, page-cap stops, skipped URLs, failed requests, and extraction failures. Keep `configuredMaxPages`, `pageLimitReached`, request evidence status, and the evaluated, matched, returned, and truncated page counts with any conclusion. Propagated `warnings` and `caveats` remain part of the result.
+
+Confirm intent before treating `noindex`, robots rules, canonicals, or snippet limits as defects. Fix unintended response and access conflicts first, then verify the exact URL and directive after deployment. A `complete` result describes only the pages evaluated by that crawl, while `partial` or `unavailable` evidence cannot support an all-clear. An empty or short gap list does not prove indexing, visibility, selection, citation, or complete site coverage.

package/skills/geo-gaps/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO gaps"
+  short_description: "Return technical AI-search eligibility gaps from crawl evidence"
+  default_prompt: "Use $geo-gaps to run the geo-gaps report and explain its evidence and limits."

package/skills/index-coverage/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: index-coverage
+description: Compare a saved crawl and sitemap with Google Search Console page results, then choose representative URLs for URL Inspection. Use when an agent needs to investigate index coverage or decide where limited URL Inspection checks will answer the most useful questions without treating a missing Search Analytics row as proof that a page is unindexed.
+---
+
+# Investigate index coverage signals
+
+Use `index-coverage` when the question is "which pages should I inspect?" A
+site can expose a page through links, a crawl, or a sitemap while Search
+Console returns no page row for the chosen period. That mismatch deserves
+review. It does not prove that the page is unindexed.
+
+The report compares three different kinds of evidence:
+
+- A saved crawl shows which pages the local crawler fetched and which current
+  controls it observed.
+- Sitemaps show URLs submitted as discovery hints. They do not prove crawling
+  or indexing.
+- Search Analytics page rows show Google Search visibility returned during an
+  exact finalized date range. They are not a complete index inventory.
+
+Use URL Inspection after this report when you need Google's current indexed
+verdict for a representative URL.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"monitoring"}`. Call
+`seo_describe_report` with `{"id":"index-coverage"}`, then call
+`seo_run_report`, for example:
+
+```json
+{"id":"index-coverage","params":{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"days":90,"rowLimit":100000}}
+```
+
+The report uses the latest saved crawl for `site` unless `crawlReportId` names
+one explicitly. Run `site-crawl` first when no suitable local crawl exists.
+Pass `sitemaps` when the crawl did not capture useful robots.txt sitemap
+declarations or when you need a specific sitemap scope.
+
+The CLI uses the same schema and report logic:
+
+```sh
+seo reports describe index-coverage --json
+seo reports run index-coverage --params '{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"days":90,"rowLimit":100000}' --json
+```
+
+## Read the evidence before the URL lists
+
+Start with `sources`. Check `completeness`, `rowLimit`, `rowLimitReached`,
+invalid URLs, duplicate URLs, the Search Console date range, and invalid
+metric rows. A partial or truncated source makes absence comparisons less
+reliable.
+
+Then inspect these groups:
+
+- `retainedSearchVisibility` contains pages with Search Analytics
+  impressions in the selected period.
+- `crawlableWithoutRetainedSearchVisibility` contains fetched crawlable pages
+  with no returned Search Console row. Treat these as review candidates.
+- `blockedOrNonIndexable` keeps current crawl controls and historical search
+  visibility separate. A control can be intentional.
+- `sitemapOnly` and `searchConsoleOnly` show mismatches in the available source
+  inventories. Scope, redirects, URL variants, and source limits may explain
+  them.
+- `templateReview` groups repeated URL shapes for sampling. A cluster is not a
+  content-quality, duplication, or index-bloat verdict.
+
+Every detail list is limited. Use `count`, `returned`, and `omitted` together
+before describing the size of a group.
+
+## Choose useful follow-up checks
+
+Pick representative URLs from important templates, high-value site sections,
+and unexpected sitemap-only groups. Prefer a small sample that tests different
+failure theories over a long random list.
+
+Run `index-watch` for those URLs to collect exact URL Inspection evidence. Use
+`index-coverage-plan` when the inventory is too large for the available daily
+quota. Fix crawl or sitemap scope problems before drawing conclusions from
+cross-source mismatches.
+
+Never call a URL indexed because it had Search Analytics visibility during the
+period. Never call it unindexed because no row appeared. Do not turn a limited
+or incomplete source into a whole-site index coverage percentage.

package/skills/index-coverage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Index coverage signals"
+  short_description: "Choose pages for URL Inspection from crawl and search evidence"
+  default_prompt: "Use $index-coverage to compare crawl, sitemap, and Search Console evidence, then choose representative URLs for URL Inspection."

package/skills/index-coverage-plan/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: index-coverage-plan
+description: Allocate sitemap URLs across available GSC properties under URL Inspection capacity; use it to design a monitoring cycle before spending inspection quota.
+---
+
+# Plan inspection coverage
+
+Use `index-coverage-plan` when sitemap inventory is larger than the URL
+Inspection checks you can run each day. It fetches sitemap URLs, maps them to
+the most specific available Search Console properties, estimates cycle time,
+and can suggest URL-prefix properties for large folders. It does not call URL
+Inspection and does not report whether any URL is indexed.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"monitoring"}`. Call
+`seo_describe_report` with `{"id":"index-coverage-plan"}`, then call
+`seo_run_report`, for example
+`{"id":"index-coverage-plan","params":{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"dailyLimit":200,"targetCycleDays":7,"maxUrls":50000}}`.
+
+The CLI uses the same report schema:
+
+```sh
+seo reports describe index-coverage-plan --json
+seo reports run index-coverage-plan --params '{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"dailyLimit":200,"targetCycleDays":7,"maxUrls":50000}' --json
+```
+
+Pass `properties` only when you intentionally want to override discovered GSC
+properties. Every sitemap URL must belong to the root property.
+
+## Interpret the output
+
+Read `summary.sitemapUrls`, `urlCount`, property count, daily capacity,
+estimated cycle days, target cycle days, and suggestion count together.
+`properties` shows each allocation, daily limit, estimated cycle, and sample
+URLs. `suggestions` identifies folders that might benefit from a separate
+URL-prefix property and explains the calculated reason.
+
+Inspect every `warning`. Sitemap fetch failures, invalid or out-of-property
+URLs, nested-sitemap boundaries, deduplication, or `maxUrls` truncation make the
+plan incomplete. Estimated cycle time is arithmetic based on discovered URLs
+and configured capacity; it is not a promise that Google will process or index
+those URLs.
+
+## Act safely
+
+Use the plan to set a realistic recurring `index-monitor` limit. Add a suggested
+property only if you control it and the operational benefit is worth the setup.
+Fix sitemap discovery problems before increasing quota. Do not report an index
+coverage percentage, excluded count, or all-clear from this allocation plan.

package/skills/index-coverage-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Index coverage plan"
+  short_description: "Plan URL Inspection allocation across Search Console properties"
+  default_prompt: "Use $index-coverage-plan to run the index-coverage-plan report and explain its evidence and limits."

package/skills/index-monitor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: index-monitor
+description: Select due sitemap URLs and store bounded Google URL Inspection snapshots; use it for recurring index-state monitoring under local quota controls.
+---
+
+# Monitor sitemap URLs
+
+Use `index-monitor` for a recurring, quota-aware sample of sitemap URLs. It
+builds a bounded inventory, allocates URLs to the most specific GSC property,
+selects due checks, calls URL Inspection, and stores snapshots for later change
+classification. The result describes Google's indexed snapshot for selected
+URLs. It is not a live crawl and cannot establish the status of every sitemap
+URL in one run.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"monitoring"}`, then
+`seo_describe_report` with `{"id":"index-monitor"}`. Call `seo_run_report` with
+schema-valid parameters, for example
+`{"id":"index-monitor","params":{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"dailyLimit":200,"inspectLimit":25,"maxUrls":50000,"languageCode":"en-GB"}}`.
+
+CLI parity uses the same registry:
+
+```sh
+seo reports describe index-monitor --json
+seo reports run index-monitor --params '{"site":"sc-domain:example.com","sitemaps":["https://example.com/sitemap.xml"],"dailyLimit":200,"inspectLimit":25,"maxUrls":50000,"languageCode":"en-GB"}' --json
+```
+
+## Interpret the output
+
+Read `dataStatus` and `source` first. Check sitemap and inventory limits,
+discovered and invalid URLs, truncation flags, omitted minimum count, daily
+limit, inspection limit, freshness window, and retry interval.
+
+In `summary`, keep inventory states distinct: never attempted, never succeeded,
+retry waiting, fresh, stale, due, selected, unselected due, attempted,
+inspected, failed, quota blocked, deferred, and skipped. A due URL that was not
+selected has no new inspection result. `properties` explains allocation and
+execution per property. In `items`, separate `inspectionStatus`, `indexStatus`,
+current issue codes, regressions, recoveries, alerts, and operational errors.
+Read `caveats` and `warnings` before an all-clear.
+
+## Act safely
+
+Investigate regressions and current issues with a live page audit, sitemap
+review, and the exact inspection evidence. Retry failed, deferred, or
+quota-blocked checks according to `retryAt`; do not convert them into SEO
+defects. Increase cycle coverage gradually. A complete selected batch still
+does not prove inventory-wide indexing, recrawl timing, or future inclusion.

package/skills/index-monitor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Index monitor"
+  short_description: "Run bounded sitemap-driven URL Inspection monitoring"
+  default_prompt: "Use $index-monitor to run the index-monitor report and explain its evidence and limits."