seo 0.1.0 → 0.2.0

package/skills/decaying-pages/SKILL.md

@@ -1,31 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,34 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,32 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,37 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,37 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,84 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,50 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,49 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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."

package/skills/index-watch/SKILL.md

@@ -1,77 +0,0 @@
----
-name: index-watch
-description: Monitor a bounded URL set with Google Search Console URL Inspection and interpret exact indexed-state evidence, current reviews, regressions, recoveries, failures, and quota-deferred checks. Use when an agent needs to check whether watched URLs changed indexing state, investigate exact robots/indexing/fetch/canonical evidence, or plan recurring sitemap monitoring without overstating URL Inspection as a live test.
----
-
-# Index watch
-
-Call `seo_list_reports` with category `monitoring` when discovery is needed.
-Call `seo_describe_report` with id `index-watch`, then call `seo_run_report`
-with that id and only the described parameters. Read `structuredContent` as the
-machine contract. Use report id `index-monitor` for a bounded oldest-first
-sitemap sample. Use report id `index-coverage-plan` before monitoring a large
-inventory across multiple Search Console properties.
-
-For the shared schema-backed CLI path:
-
-```bash
-seo reports describe index-watch --json
-seo reports run index-watch --params '{"site":"sc-domain:example.com","urls":["https://example.com/a","https://example.com/b"],"dailyLimit":25}' --json
-```
-
-This validates the same parameters used by MCP. The focused commands below add
-saved monitoring state, sitemap selection, and friendlier flags for recurring
-human workflows.
-
-## Run the report
-
-1. Pass the selected Search Console property as `site`.
-2. Keep explicit `urls` at 100 or fewer. Every URL must belong to the property.
-3. Use `dailyLimit` only to set a lower local safety limit. It cannot exceed
-   Google's documented 2,000 daily inspections per property.
-4. For sitemap monitoring, check `source.possiblyTruncated`, `dataStatus`,
-   `warnings`, `neverAttempted`, `neverSucceeded`, `retryWaiting`, `fresh`,
-   `stale`, `due`, `selected`, and `unselectedDue` before summarising coverage.
-5. Read `currentIssues`, `regressions`, `recoveries`, `failed`, `quotaBlocked`,
-   and `deferred` separately.
-
-CLI equivalents:
-
-```bash
-seo index-watch --site sc-domain:example.com --urls https://example.com/a,https://example.com/b --json
-seo index-watch --site sc-domain:example.com --sitemaps https://example.com/sitemap.xml --inspect-limit 25 --json
-seo index-watch --site sc-domain:example.com --sitemaps https://example.com/sitemap.xml --plan --json
-```
-
-## Interpret evidence
-
-- `inspectionStatus: succeeded` means Google returned an indexed snapshot.
-- `indexStatus` maps exact verdicts: `PASS` to `indexed`, `NEUTRAL` to
-  `excluded`, `FAIL` to `invalid`, and everything else to `unknown`.
-- `currentIssue` means stable enum or canonical evidence needs review against
-  the URL's intended state. An excluded URL or alternate canonical may be
-  intentional.
-- `changeKind: regression` means a prior clear successful snapshot became an
-  issue. `recovery` means the reverse.
-- `baseline` means there is no previous successful snapshot. A first-run issue
-  is still a current review and a new alert.
-- `failed`, `quota-blocked`, and `deferred` are operational outcomes, not SEO
-  defects. They are not comparable with a successful indexed state.
-- `requestSent: false` means the local quota broker blocked the call before it
-  reached Google. Use `retryAt` when it is present.
-- Use `issueCodes` and typed `changes` for machine reasoning. Keep
-  `coverageState` as display evidence because Google localises that free text.
-
-## Guardrails
-
-- URL Inspection is Google's indexed version for one URL. It is not a live
-  crawl and does not guarantee current search appearance.
-- Do not report every `NEUTRAL` verdict or canonical difference as a defect.
-- Do not infer inventory-wide health from the bounded selected sample.
-- Sitemap failures wait 24 hours before automatic selection retries. Do not
-  retry quota-blocked or deferred URLs before `retryAt`.
-- The local UTC-day quota ledger cannot observe calls made by other machines or
-  Google clients. A provider 429 remains authoritative.
-- Fix authentication and property access failures instead of treating the
-  report as sparse data.
-- Prefer BYO Google credentials if shared OAuth project quota becomes a limit.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Index Watch"
-  short_description: "Monitor exact Google indexed-state changes safely"
-  default_prompt: "Use $index-watch to inspect a bounded URL set, separate current index reviews from regressions and failures, and explain the evidence without treating Google URL Inspection as a live test."

package/skills/internal-links/SKILL.md

@@ -1,31 +0,0 @@
----
-name: internal-links
-description: Find fetched source pages with query evidence relevant to one target URL and no verified contextual link; use when an agent needs bounded link candidates rather than automatic anchor insertion.
----
-
-# Internal link candidates
-
-Use this report to find source pages whose retained GSC queries overlap with demand for a target URL. It resolves target aliases, fetches bounded candidate pages, checks technical state, and inspects observed links and placement before returning a review candidate. Exact query overlap is stronger than lexical overlap, but neither proves that a link belongs in the page or that adding one will improve rankings.
-
-## Run the report
-
-Use the compact MCP flow:
-
-1. Call `seo_list_reports` with `{"category":"opportunities"}`.
-2. Call `seo_describe_report` with `{"id":"internal-links"}`.
-3. Call `seo_run_report` with `{"id":"internal-links","params":{"site":"sc-domain:example.com","targetUrl":"https://example.com/guides/seo","days":90,"limit":15,"checkLimit":40,"minImpressions":25}}`.
-
-The CLI invokes the same handler:
-
-```sh
-seo reports describe internal-links --json
-seo reports run internal-links --params '{"site":"sc-domain:example.com","targetUrl":"https://example.com/guides/seo","days":90,"limit":15,"checkLimit":40,"minImpressions":25}' --json
-```
-
-`site` and `targetUrl` are required. `checkLimit` bounds fetched candidates; `limit` bounds returned candidates. Increase fetch concurrency or enable JavaScript only when the site and task justify the extra load.
-
-## Interpret and act
-
-Check `dataStatus`, target verification, aliases, canonical, technical signals, and source completeness first. Review `selection.attemptedSources`, checked, failed, unchecked, technical exclusions, alias exclusions, and existing-link exclusions. A low `checkLimit` can leave plausible candidates unchecked. Each item includes exact or lexical query matches, shared terms, impressions, fetch diagnostics, technical signals, and `linkEvidence`. Distinguish `missing`, `non-contextual-only`, and `alias-contextual`; respect observed and limited link counts. Priority is a heuristic combining match evidence, not estimated impact.
-
-Safe action is to read the source passage, confirm the target is genuinely useful there, choose natural anchor wording, add one contextual link, and recrawl to verify it. Do not insert links in bulk, replace navigation links without reason, link from technically unsuitable pages, or claim ranking impact from a candidate score.

package/skills/internal-links/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Internal link candidates"
-  short_description: "Find verified internal-link review candidates for one target URL"
-  default_prompt: "Use $internal-links to run the internal-links report and explain its evidence and limits."

package/skills/link-recovery/SKILL.md

@@ -1,51 +0,0 @@
----
-name: link-recovery
-description: Join retained GSC page value with current redirect and indexability checks; use it to prioritise previously visible URLs that may now be broken or misdirected.
----
-
-# Recover search-value URLs
-
-Use `link-recovery` to find retained GSC page rows with prior clicks or
-impressions whose current fetch path ends in a technical problem. This joins
-historical search observations with a present redirect trace, which is useful
-for triage after migrations or URL changes. Prior visibility helps order the
-queue. It does not prove that fixing a URL will restore the same traffic.
-
-## Run the report
-
-With MCP, call `seo_list_reports` with `{"category":"monitoring"}`, call
-`seo_describe_report` with `{"id":"link-recovery"}`, then use `seo_run_report`.
-Example:
-`{"id":"link-recovery","params":{"site":"sc-domain:example.com","days":90,"limit":25,"minClicks":1,"minImpressions":100,"js":false,"refresh":true}}`.
-
-The CLI has the same schema:
-
-```sh
-seo reports describe link-recovery --json
-seo reports run link-recovery --params '{"site":"sc-domain:example.com","days":90,"limit":25,"minClicks":1,"minImpressions":100,"refresh":true}' --json
-```
-
-The discovery schema currently exposes broad number types. Use positive whole
-days and bounded non-negative thresholds.
-
-## Interpret the output
-
-Confirm `range` and `summary.checked` before reading recoverable counts. The
-summary separates high, medium, and low severity and totals observed clicks and
-impressions for affected retained rows. Those `clicksAtRisk` and
-`impressionsAtRisk` values describe the checked period; they are not a forecast
-of future loss or recovery.
-
-Each item preserves the original URL, final URL, GSC metrics, primary and full
-issue lists, severity, the redirect `trace`, and a recommendation with evidence,
-effort, and confidence. Inspect chain status, final-page indexability,
-canonicals, and warnings directly. Failed checks, selection limits, or retained
-GSC rows outside the returned set constrain coverage.
-
-## Act safely
-
-Restore a page only when it should still exist. Otherwise add one direct 301 to
-the closest equivalent destination and align its canonical after verifying
-intent. Fix server errors and accidental noindex controls before content work.
-Do not redirect unrelated URLs to a homepage, remove intentional controls, or
-promise traffic recovery from historical metrics.

package/skills/link-recovery/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Link recovery"
-  short_description: "Find search-value URLs that now fail technical checks"
-  default_prompt: "Use $link-recovery to run the link-recovery report and explain its evidence and limits."

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

@@ -1,34 +0,0 @@
----
-name: llms-txt-audit
-description: Inspect an optional llms.txt file and derive a bounded set of suitable page candidates from crawl evidence. Use when reviewing agent-facing site navigation without treating the file as a ranking requirement.
----
-
-# Audit llms.txt
-
-`llms.txt` is optional publisher-provided navigation for agents. Its presence is not a general search requirement or ranking signal, and its absence is not a technical SEO defect. This report checks the observed file response and suggests eligible pages that could belong in a useful inventory.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` only when discovery is needed. Call `seo_describe_report` with `{ "id": "llms-txt-audit" }`, then `seo_run_report` with:
-
-```json
-{
-  "id": "llms-txt-audit",
-  "params": { "reportId": "crawl_example_20260710" }
-}
-```
-
-Check MCP `isError`, then read `structuredContent`. The CLI exposes the same contract:
-
-```sh
-seo reports describe llms-txt-audit --json
-seo reports run llms-txt-audit --params '{"reportId":"crawl_example_20260710"}' --json
-```
-
-Using `url` instead of `reportId` starts a fresh crawl. Prefer a saved snapshot when the recommendations will be compared with other reports.
-
-## Interpret the result
-
-Review `exists`, the resolved file URL, response status, headline, issues, and `recommendedPages`. Candidate pages are drawn from successfully fetched, indexable pages and exclude common utility or private paths; ordering uses crawl evidence such as internal authority and content depth. That selection is a heuristic inventory, not proof that every important page is present or suitable for publication.
-
-Check the source report's date, cap, partial state, failed requests, warnings, and caveats with `crawl-report`. A short recommendation list from a capped crawl is not sitewide evidence. If the file exists, verify that its URLs are current, canonical, public, and aligned with publisher intent. If it does not exist, recommend creating one only when it improves agent navigation. Keep any generated file concise and human-reviewed; never claim that adding it will improve indexing, rankings, traffic, AI selection, or citations.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Audit llms.txt"
-  short_description: "Inspect optional llms.txt evidence from a crawl"
-  default_prompt: "Use $llms-txt-audit to run the llms-txt-audit report and explain its evidence and limits."