seo 0.1.0 → 0.2.1

package/skills/affected-urls/SKILL.md

@@ -1,39 +0,0 @@
----
-name: affected-urls
-description: Find the exact crawl issues attached to individual URLs and preserve their joined traffic evidence. Use when turning a rule, category, or severity group into a bounded implementation list.
----
-
-# Find affected URLs
-
-Use this report after a crawl has identified a technical pattern. A rule count is useful for triage, but implementation needs the exact URLs, the observed evidence, and a stable source crawl. Prefer `reportId` so every follow-up refers to the same snapshot; pass `url` only when a new crawl is intentional.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` only when discovery is needed. Then call `seo_describe_report` with `{ "id": "affected-urls" }`. Finally call `seo_run_report` with:
-
-```json
-{
-  "id": "affected-urls",
-  "params": {
-    "reportId": "crawl_example_20260710",
-    "ruleId": "missing_title",
-    "severity": "high",
-    "limit": 50
-  }
-}
-```
-
-Read MCP `structuredContent` as the contract and check `isError` before using it. The text result is a compact explanation, not the data source.
-
-The CLI exposes the same report:
-
-```sh
-seo reports describe affected-urls --json
-seo reports run affected-urls --params '{"reportId":"crawl_example_20260710","ruleId":"missing_title","severity":"high","limit":50}' --json
-```
-
-## Read and act
-
-Each row ties a URL to a rule, category, severity, and crawler evidence. Optional clicks, impressions, and sessions help order work, but inspect `dataSources` first: unavailable provider data must not be interpreted as a real zero. Results are sorted deterministically by severity, joined demand signals, and URL. The `selection` object reports `totalMatchedRows`, `returnedRows`, `limit`, and `truncated`; preserve it whenever the URL array is passed downstream.
-
-Check the requested filters, selection metadata, original crawl cap, warnings, and caveats before calling the set complete. `truncated: true` means more matching issue rows exist in this report than were returned. A capped or partial crawl only supports "affected among evaluated pages." Create fixes from the observed evidence, sample several URL templates, and use `explain-crawl-issue` for rule guidance. Re-run the same bounded crawl after deployment to verify that the rule no longer triggers; disappearance from a differently scoped crawl is not verification.

package/skills/affected-urls/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Affected URLs"
-  short_description: "Return affected URLs from a crawl report"
-  default_prompt: "Use $affected-urls to run the affected-urls report and explain its evidence and limits."

package/skills/ai-readiness/SKILL.md

@@ -1,34 +0,0 @@
----
-name: ai-readiness
-description: Assess technical AI-search readiness without inventing a visibility score or citation forecast. Use when checking access, indexability, snippets, page structure, and optional agent resources from crawl evidence.
----
-
-# Assess AI readiness
-
-AI-search systems can only use content they can retrieve and interpret, but technical eligibility is not selection. This report keeps access, indexability, snippet controls, content observations, bot policy, and agent resources separate. It deliberately returns an evidence-only assessment instead of an aggregate score.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` if the report id is not already known. Call `seo_describe_report` with `{ "id": "ai-readiness" }`, then `seo_run_report` with:
-
-```json
-{
-  "id": "ai-readiness",
-  "params": { "reportId": "crawl_example_20260710" }
-}
-```
-
-Use `structuredContent` after confirming `isError` is false. The equivalent CLI flow is:
-
-```sh
-seo reports describe ai-readiness --json
-seo reports run ai-readiness --params '{"reportId":"crawl_example_20260710"}' --json
-```
-
-Supplying `url` instead of `reportId` starts a fresh crawl. Reusing a saved report makes this assessment comparable with other follow-ups.
-
-## Interpret the assessment
-
-Start with `dataStatus`, the crawl caveats, and each check's `evaluated` flag. `unknown` means the necessary evidence was unavailable; it is not a failure or a pass. Bot access describes the observed policy for the crawl entry point, not proven access to every URL. Valid JSON-LD is syntax evidence, not proof of entity recognition or rich-result eligibility. An optional protocol file can aid machine discovery but its absence is not a search defect.
-
-Prioritize hard technical conflicts first: failed responses, blocked crawling, explicit non-indexing, or restrictive snippet directives where those settings contradict publisher intent. Then review semantic structure and answerable content as observations, not requirements. Verify changes with a fresh crawl using the same scope. Never translate a clean report into claims about indexing, rankings, AI visibility, selection, citations, or traffic; those outcomes require separate evidence.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "AI readiness"
-  short_description: "Review local AI-search readiness evidence"
-  default_prompt: "Use $ai-readiness to run the ai-readiness report and explain its evidence and limits."

package/skills/ai-referrals/SKILL.md

@@ -1,31 +0,0 @@
----
-name: ai-referrals
-description: Measure sessions and landing pages attributed to known AI referral sources in GA4; use when an agent needs bounded analytics evidence without equating missing referrers with zero AI visibility.
----
-
-# AI referrals
-
-Use this report to see which known AI referral domains appeared as GA4 session sources, which landing pages received those sessions, and how activity changed by day. It is useful for observed referral analysis, not for measuring every mention or citation. Referrers can be stripped, reclassified, or recorded as direct or unassigned traffic, so an empty result is not proof that no AI system sent or cited the site.
-
-## Run the report
-
-Use the compact MCP flow:
-
-1. Call `seo_list_reports` with `{"category":"ai-search"}`.
-2. Call `seo_describe_report` with `{"id":"ai-referrals"}` and inspect the current schema.
-3. Call `seo_run_report` with `{"id":"ai-referrals","params":{"property":"123456789","startDate":"28daysAgo","endDate":"yesterday","limit":25}}`.
-
-The CLI uses the same registry and handler:
-
-```sh
-seo reports describe ai-referrals --json
-seo reports run ai-referrals --params '{"property":"123456789","startDate":"28daysAgo","endDate":"yesterday","resultLimit":25}' --json
-```
-
-`property` is required. Dates accept `YYYY-MM-DD` or GA4 relative dates such as `28daysAgo`. `maxRows` bounds retained provider rows. `resultLimit` controls how many of the highest-session landing pages are returned (25 by default); use it to ask for a smaller or larger ranked review set. `limit` is a legacy alias for `maxRows`, so do not use it in new commands.
-
-## Interpret and act
-
-Start with `dataStatus`, `range`, `methodology`, and `dataSource.partialReasons`. Check `possiblyTruncated`, query-level statuses, warnings, returned rows, and the GA4 time zone before comparing totals. `summary.sessions` and `summary.eventCount` are additive; `summary.totalUsers` can be unavailable and must not be reconstructed by adding per-source or per-page values. Check `selection.landingPages` before treating `landingPages` as the whole retained breakdown: it states the output limit and any lower-ranked rows omitted from the response. Use `sources[].observedSessionSources` to preserve the exact attribution evidence, `shareOfAiSessions` only within detected AI sessions, and the returned `landingPages` to choose pages for a qualitative review.
-
-Safe actions include checking whether high-volume landing pages answer the referring context, comparing complete like-for-like periods, and annotating material changes. Do not claim that referral sessions caused conversions, represent all AI traffic, or reveal the prompt, answer, citation, or user intent that produced the visit.

package/skills/ai-referrals/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "AI referrals"
-  short_description: "Find known AI referral traffic in GA4"
-  default_prompt: "Use $ai-referrals to run the ai-referrals report and explain its evidence and limits."

package/skills/audit-page/SKILL.md

@@ -1,50 +0,0 @@
----
-name: audit-page
-description: Audit one fetched URL for technical and on-page evidence. Use it to inspect a specific page without turning page-level observations into sitewide claims.
----
-
-# Audit page
-
-Use this report when a URL needs direct inspection: after a release, while
-investigating a search result, or before recommending a page edit. It combines
-the fetched document with metadata, headings, links, structured data, and
-optional GSC evidence. It does not prove how every crawler rendered the page,
-that Google indexed the fetched version, or that an observed convention affects
-rankings.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "reporting"` and select `audit-page`.
-2. Call `seo_describe_report` with `id: "audit-page"`; do not guess fields.
-3. Call `seo_run_report` with `id: "audit-page"` and parameters matching that schema.
-
-The CLI has the same contract:
-
-```sh
-seo reports describe audit-page --json
-seo reports run audit-page --params '{"url":"https://example.com/product","site":"sc-domain:example.com","refresh":true}' --json
-```
-
-`url` is required. `site` adds Search Console context when access exists.
-Enable `js` only when client rendering is necessary; omitted rendering behavior
-is selected by the report. `refresh` bypasses reusable cached evidence.
-
-## Interpret and act
-
-Start with `fetchDiagnostics`, warnings, and the final fetched URL. A redirect,
-blocked response, rendering failure, or non-HTML response limits every later
-observation. Then inspect the observed page fields, structured-data findings,
-issues, and recommendations. Title pixel width is an estimator for review, not
-a Google limit. Heading counts describe document structure; more or fewer than
-one H1 is not automatically a defect. Content length is evidence, not a quality
-score. If GSC metrics are present, keep their window and property semantics
-attached.
-
-Safe actions are concrete and reversible: repair a broken canonical, make
-important content available in the fetched HTML, correct invalid structured
-data, or investigate a failed response. Verify intent before changing
-`noindex`, canonicals, robots controls, headings, or snippet directives. One
-page cannot support a sitewide conclusion. Read MCP `structuredContent` as the
-machine contract and use Markdown only for the human explanation.

package/skills/audit-page/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Audit page"
-  short_description: "Audit one fetched page"
-  default_prompt: "Use $audit-page to run the audit-page report and explain its evidence and limits."

package/skills/audit-urls/SKILL.md

@@ -1,39 +0,0 @@
----
-name: audit-urls
-description: Audit a known URL set without implying sitewide coverage and optionally save the snapshot for follow-ups. Use for release checks, templates, migrations, or a bounded remediation list.
----
-
-# Audit an explicit URL list
-
-Use this report when the URLs are already known. It avoids sitemap discovery and link traversal, so the result answers "what was observed on these pages?" rather than "what is wrong across the site?" This makes it useful for pre-release checks, representative templates, and verifying a fix list.
-
-## Run it
-
-For MCP, discover with `seo_list_reports` category `crawl` only if needed. Describe the contract with `seo_describe_report` and `{ "id": "audit-urls" }`. Then call `seo_run_report` with:
-
-```json
-{
-  "id": "audit-urls",
-  "params": {
-    "urls": [
-      "https://example.com/",
-      "https://example.com/pricing"
-    ],
-    "includeIssues": true,
-    "saveReport": true
-  }
-}
-```
-
-Check `isError`, then consume `structuredContent`. CLI parity is exact:
-
-```sh
-seo reports describe audit-urls --json
-seo reports run audit-urls --params '{"urls":["https://example.com/","https://example.com/pricing"],"includeIssues":true,"saveReport":true}' --json
-```
-
-## Read and verify
-
-Compare requested URLs with attempted, fetched, failed, retained, and omitted counts. Review response evidence, issue summaries, `requestEvidenceStatus`, warnings, and caveats before acting. `includeIssues` returns the rule inventory; `includePages` adds larger page and request records and should only be enabled when the decision needs them. Saving the report gives later commands a stable `reportId`.
-
-A successful sample does not prove the same template works everywhere, and a failed request may reflect a transient network condition rather than a persistent SEO defect. Group findings by shared implementation, confirm intentional canonicals, robots directives, and `noindex` settings with the publisher, then fix the template rather than individual URLs where appropriate. Re-run the identical URL list after deployment. A URL omitted from the next request is not a verified fix, and this bounded audit must never be described as complete site coverage.

package/skills/audit-urls/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Audit URLs"
-  short_description: "Audit an explicit bounded URL list"
-  default_prompt: "Use $audit-urls to run the audit-urls report and explain its evidence and limits."

package/skills/cannibalisation/SKILL.md

@@ -1,31 +0,0 @@
----
-name: cannibalisation
-description: Find retained GSC queries with material exposure across multiple URLs; use when an agent needs an intent and technical review queue rather than an automatic consolidation verdict.
----
-
-# Multi-URL query exposure
-
-Use this report to find exact normalized queries whose retained GSC impressions are materially distributed across more than one URL. It combines query/page exposure with property-level query demand, suppresses low-actionability cases, and ranks review candidates using demand and secondary exposure. Multiple ranking URLs can be correct for mixed intent, local/entity results, or distinct page purposes, so the report deliberately calls them URL-overlap candidates rather than proven harmful cannibalisation.
-
-## Run the report
-
-Use the compact MCP flow:
-
-1. Call `seo_list_reports` with `{"category":"opportunities"}`.
-2. Call `seo_describe_report` with `{"id":"cannibalisation"}`.
-3. Call `seo_run_report` with `{"id":"cannibalisation","params":{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"includeBrand":false}}`.
-
-The CLI runs the identical definition:
-
-```sh
-seo reports describe cannibalisation --json
-seo reports run cannibalisation --params '{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"includeBrand":false}' --json
-```
-
-`site` is required. `brandTerms` accepts up to 20 explicit terms; use `includeBrand:true` only when navigational brand overlap is part of the investigation.
-
-## Interpret and act
-
-Start with `dataStatus`, both `source.pageExposure` and `source.propertyDemand`, their validation counts, caps, and `source.completeness`. A partial or possibly truncated source cannot support an all-clear. Use `selection` to see why groups were excluded or suppressed. Within each item, inspect every page's clicks, impressions, position, impression share, template, `reviewContext`, HHI, and secondary exposure. `suggestedOwnerUrl` is chosen mechanically by clicks, then impressions, then position; its confidence is low and `requiresIntentReview` is true. `priority.score` is a heuristic, not estimated click lift.
-
-Safe actions include comparing intent and live SERPs, checking canonicals and redirects, clarifying internal-link ownership, or differentiating genuinely distinct pages. Consolidate only when intent, content, technical signals, and business purpose agree. Never redirect or canonicalize a secondary URL solely because it appears in this report.

package/skills/cannibalisation/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Cannibal exposure"
-  short_description: "Find queries exposed across multiple URLs"
-  default_prompt: "Use $cannibalisation to run the cannibalisation report and explain its evidence and limits."

package/skills/community-intent/SKILL.md

@@ -1,39 +0,0 @@
----
-name: community-intent
-description: Find explicit forum, comparison, review, experience, and recommendation language in retained Google Search Console queries. Use when an agent needs to review community-style search intent, rank query hypotheses, or decide which ranking pages need manual intent and SERP inspection.
----
-
-# Community intent
-
-Call `seo_list_reports` with category `ai-search` when discovery is needed.
-Call `seo_describe_report` with id `community-intent`, then call
-`seo_run_report` with that id and only the described parameters. Read
-`structuredContent` as the machine contract. Use the CLI when MCP is
-unavailable:
-
-```bash
-seo reports describe community-intent --json
-seo reports run community-intent --params '{"site":"sc-domain:example.com","days":90,"minImpressions":20,"limit":25}' --json
-seo community-intent --project <project> --json
-```
-
-The generic runner validates the exact MCP schema before any provider call.
-Use the focused command when a human needs named flags and project-profile
-selection. Both paths execute the same report.
-
-For a reproducible report pass `startDate` and `endDate` to MCP or use `--start-date` and `--end-date` in the CLI. Keep the range inside `source.availableDateWindow`. Do not combine an exact range with `days`.
-
-## Read the evidence first
-
-1. Check `dataStatus`, `source.completeness`, `warnings`, and `caveats`.
-2. Use `selection.classifiedRows` for every retained match. Use `selection.returnedRows` for the limited result set.
-3. Treat a capped or partial zero as inconclusive. GSC may omit lower-click queries.
-4. Report `intent`, `signals`, and `matchedTerms` as low-confidence language heuristics.
-
-The classifier uses English patterns. It does not inspect the live SERP, identify the ranking URL, or verify page content. Never state that a page has a content gap from this report alone.
-
-## Turn a result into an action
-
-Use each item as a review queue. Retrieve GSC query/page rows to identify every associated URL, inspect the current search results, then check each relevant page against the observed query language. Recommend a content change only when page or SERP evidence supports it.
-
-Use explicit `brandTerms` when the brand cannot be derived reliably from the property. Keep `includeBrand` false unless branded demand is part of the question.

package/skills/community-intent/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Community intent"
-  short_description: "Review explicit intent signals in GSC queries"
-  default_prompt: "Use $community-intent to find retained GSC queries that need an intent review."

package/skills/compare-crawls/SKILL.md

@@ -1,40 +0,0 @@
----
-name: compare-crawls
-description: Compare two saved crawl snapshots with explicit provenance and completeness. Use it to separate observed page changes from crawl-scope, cap, configuration, or source noise.
----
-
-# Compare crawl snapshots
-
-A crawl diff is useful only when its inputs are comparable. This report surfaces page, issue, response, indexability, title, content, and summary changes between two saved snapshots. By default, `after` means the latest report and `before` means the previous report, optionally within one `site` filter.
-
-## Run it
-
-For MCP, use `seo_list_reports` with category `crawl` only for discovery. Call `seo_describe_report` with `{ "id": "compare-crawls" }`, then call `seo_run_report` with:
-
-```json
-{
-  "id": "compare-crawls",
-  "params": {
-    "after": "latest",
-    "before": "previous",
-    "site": "sc-domain:example.com"
-  }
-}
-```
-
-Read `structuredContent` after checking `isError`. The CLI uses the same parameters:
-
-```sh
-seo reports describe compare-crawls --json
-seo reports run compare-crawls --params '{"after":"latest","before":"previous","site":"sc-domain:example.com"}' --json
-```
-
-Use explicit report ids for a release decision so "latest" cannot move between runs.
-
-## Establish comparability first
-
-Read `comparability.status` before interpreting any delta. The accompanying flags show whether the definition ids, config hashes, sites, start URLs, modes, request scopes, and caps match. `before` and `after` preserve each report id, status, normalized `config`, explicit `requestScope`, `caps`, request-evidence status, joined data-source status, warnings, caveats, and completeness. This is enough to assess the inputs without loading two separate reports.
-
-Next inspect top-level `completeness`. If `truncated` is true, or either input is partial or failed, read its stable reason codes and the report-level `caveats`. An absent page from a capped, skipped, failed, or differently scoped crawl is not proven removed. Source row caps also limit joined GSC or GA4 evidence even when the document crawl completed.
-
-Only then inspect `summary`, `pageChanges`, and `issueChanges`. These fields describe retained observations between the named snapshots. Prioritize newly observed response failures, unintended indexability flips, and issue groups that affect more URLs, then verify titles and content on the affected URLs. Confirm fixes with the same definition and request scope after deployment. When comparability requires review, describe the change as observed between snapshots and name the differing scope, cap, configuration, or incomplete source instead of attributing it to the release.

package/skills/compare-crawls/agents/openai.yaml

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

package/skills/content-optimization/SKILL.md

@@ -1,31 +0,0 @@
----
-name: content-optimization
-description: Build a content brief for one URL from retained GSC queries and live page observations; use when an agent needs evidence-led edit ideas without treating query wording as a content mandate.
----
-
-# Content optimization
-
-Use this report when an existing page has first-party search visibility and needs a focused review. It joins exact-URL GSC query/page rows to a fetched page, classifies query wording into broad intent heuristics, and turns verified opportunity types into title, H1, meta, section, and internal-link angles. It does not prove searcher intent, diagnose why a page ranks where it does, or guarantee that adding the suggested wording will improve traffic.
-
-## Run the report
-
-Use the compact MCP flow:
-
-1. Call `seo_list_reports` with `{"category":"ai-search"}`.
-2. Call `seo_describe_report` with `{"id":"content-optimization"}`.
-3. Call `seo_run_report` with `{"id":"content-optimization","params":{"site":"sc-domain:example.com","url":"https://example.com/guides/seo","days":90,"limit":20,"minImpressions":50,"verifyContent":true}}`.
-
-The CLI runs the same definition:
-
-```sh
-seo reports describe content-optimization --json
-seo reports run content-optimization --params '{"site":"sc-domain:example.com","url":"https://example.com/guides/seo","days":90,"limit":20,"minImpressions":50,"verifyContent":true}' --json
-```
-
-`site` and an HTTP(S) `url` are required. The URL must belong to the selected GSC property. Set `js:true` only when the useful content requires rendering; use `refresh:true` when stale cache evidence would change the decision.
-
-## Interpret and act
-
-Read `sourceReport` before the derived brief. Check its `dataStatus`, `selection`, `benchmark.possiblyTruncated`, `verification.status`, warnings, and caveats. Treat `summary.score`, `primaryIntent`, and `estimatedClickLift` as prioritisation heuristics, not quality grades or forecasts. In `topActions`, separate `technical-check` and `unverified` items from verified `content-gap`, `serp-framing`, `ctr`, or `ranking` observations. Review `intentMix` and the source query metrics so a high-impression theme does not get mistaken for a universal user need.
-
-Safe actions are to fix contradictory technical evidence first, improve a clearly missing answer block, test clearer SERP framing when the body already covers the topic, or leave a well-covered page alone. Do not create one thin section per query, force exact-match wording, change the canonical target, or expand content solely to raise the report score.

package/skills/content-optimization/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Content optimization"
-  short_description: "Build a first-party content review for one URL"
-  default_prompt: "Use $content-optimization to run the content-optimization report and explain its evidence and limits."

package/skills/crawl-diff/SKILL.md

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

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

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

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

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

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

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

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

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

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