seo 0.1.0 → 0.2.1

package/skills/striking-distance/SKILL.md

@@ -1,52 +0,0 @@
----
-name: striking-distance
-description: Find retained GSC query-page rows with average positions from 11 through 20; use it to build a bounded review queue near page-one visibility.
----
-
-# Review striking-distance rows
-
-Use `striking-distance` to find query-page combinations whose retained GSC
-average position falls from 11 through 20. This range can surface useful review
-candidates, but it is a heuristic boundary. Average position varies by search,
-device, country, and day, so the report does not prove that a URL consistently
-ranks on a literal second results page or predict how many clicks a change will
-produce.
-
-## Run the report
-
-With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`, call
-`seo_describe_report` with `{"id":"striking-distance"}`, then call
-`seo_run_report` with only described parameters. Example:
-`{"id":"striking-distance","params":{"site":"sc-domain:example.com","days":28,"minImpressions":50,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}}`.
-
-The CLI has exact registry parity:
-
-```sh
-seo reports describe striking-distance --json
-seo reports run striking-distance --params '{"site":"sc-domain:example.com","days":28,"minImpressions":50,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json
-```
-
-Add `brandTerms`, JavaScript rendering, or bounded fetch-rate controls only
-after inspecting the schema and when the investigation needs them.
-
-## Interpret the output
-
-Check `range`, `rangeDays`, `dataStatus`, and `source` before the item list.
-`source.possiblyTruncated` and retained-row completeness limit any all-clear.
-Use `selection` to see what was invalid, outside the position range, branded,
-below thresholds, eligible, returned, or limited. `methodology` explains the
-priority heuristic.
-
-For each item, read the observed query, URL, clicks, impressions, CTR, average
-position, recommendation evidence, and optional `contentVerification`.
-`verification` reports requested, attempted, verified, technical, and failed
-counts; unverified or failed pages must keep lower confidence. Groups and
-templates show repeated patterns only within retained candidates.
-
-## Act safely
-
-Audit a small number of high-impression candidates. Fix verified technical
-problems first; otherwise compare intent, title framing, page coverage, and
-internal links against observed query evidence. Do not rewrite a page solely
-because it sits inside the position band, and do not present the priority score
-as expected traffic or ranking lift.

package/skills/striking-distance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Striking distance"
-  short_description: "Find retained GSC query and page rows averaging positions 11 through 20"
-  default_prompt: "Use $striking-distance to run the striking-distance report and explain its evidence and limits."

package/skills/technical-watch/SKILL.md

@@ -1,49 +0,0 @@
----
-name: technical-watch
-description: Coordinate crawl comparison, URL Inspection monitoring, and optional link recovery. Use it for a bounded recurring watch without claiming inventory-wide coverage.
----
-
-# Technical watch workflow
-
-This workflow watches several technical surfaces together: crawl change,
-sitemap-derived URL inspection, and optional recovery of historically valuable
-links. It is useful after releases and on a schedule. Its components have
-different coverage and freshness, so a successful run does not prove every URL
-is crawlable, indexed, unchanged, or free of issues.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "workflows"` and select `technical-watch`.
-2. Call `seo_describe_report` with `id: "technical-watch"`; choose the components required.
-3. Call `seo_run_report` with that id and only schema-valid parameters.
-
-CLI parity:
-
-```sh
-seo reports describe technical-watch --json
-seo reports run technical-watch --params '{"site":"sc-domain:example.com","startUrl":"https://example.com/","sitemaps":["https://example.com/sitemap.xml"],"limit":250,"dailyLimit":200,"inspectLimit":25,"recoverLinks":true}' --json
-```
-
-Provide `startUrl` for crawl comparison and `sitemaps` for index monitoring.
-`dailyLimit`, `inspectLimit`, `maxUrls`, and crawl `limit` are real coverage
-bounds. Enable `js` only when rendering is required.
-
-## Interpret and act
-
-Inspect every workflow step and nested `crawl`, `index`, and `recovery` output
-independently. For crawls, compare run ids, limits, failures, warnings, and
-changed items. For inspection, distinguish selected, unselected-due, attempted,
-failed, quota-blocked, deferred, current issue, and regression states. URL
-Inspection is a provider snapshot; sitemap discovery is not proof of indexing.
-For recovery, historical clicks-at-risk are observed history, not forecast loss.
-
-Reproduce new failures, verify redirect chains and intentional controls, then
-fix confirmed regressions with a rollback path. Schedule another bounded run to
-confirm recovery. Never remove `noindex`, canonicals, robots rules, or redirects
-without checking intent. Partial crawls, capped sitemap inventories, quotas,
-and failed subqueries must stay visible in any all-clear statement.
-
-Use MCP `structuredContent` for automation and Markdown only for the human watch
-summary.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Technical watch workflow"
-  short_description: "Run crawl-diff and URL Inspection monitoring together"
-  default_prompt: "Use $technical-watch to run the technical-watch report and explain its evidence and limits."

package/skills/top-fixes/SKILL.md

@@ -1,38 +0,0 @@
----
-name: top-fixes
-description: Rank recurring technical crawl findings into a bounded implementation queue with visible scoring factors. Use for triage before inspecting affected URLs and rule-level evidence.
----
-
-# Prioritize technical fixes
-
-Large crawls need triage, but priority must remain explainable. This report groups issues by rule and ranks them using severity, affected-page count, estimated effort, and any available Search Console or analytics evidence. It is a deterministic queue from retained evidence, not a forecast of rankings, traffic, conversions, or revenue.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` only when discovery is needed. Call `seo_describe_report` with `{ "id": "top-fixes" }`, then call `seo_run_report` with:
-
-```json
-{
-  "id": "top-fixes",
-  "params": {
-    "reportId": "crawl_example_20260710",
-    "category": "metadata",
-    "limit": 5
-  }
-}
-```
-
-Confirm `isError` is false and read `structuredContent`. CLI parity is:
-
-```sh
-seo reports describe top-fixes --json
-seo reports run top-fixes --params '{"reportId":"crawl_example_20260710","category":"metadata","limit":5}' --json
-```
-
-Use `url` only for an intentional fresh crawl. Reusing a saved report keeps the queue tied to the same issue inventory.
-
-## Turn priority into work
-
-Read `dataSources`, summary, warnings, and caveats before the ranked fixes. For each item inspect the rule id, affected count, sample URLs, `scoreFactors`, `whyThisRanks`, effort, fix guidance, and verification steps. Missing provider joins must stay unavailable; numeric zeros are meaningful only when the corresponding source is complete and valid.
-
-The category and result limits narrow the queue, while the original crawl may also be capped or partial. Therefore rank means "highest among retained eligible findings," not globally highest. Run `affected-urls` for the same rule and report id, inspect representative templates, and use `explain-crawl-issue` before assigning work. Confirm intentional indexability and canonical controls with the publisher. After implementation, repeat the same crawl configuration and verify the observed rule evidence rather than relying on a score change alone.

package/skills/top-fixes/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Top fixes"
-  short_description: "Return a bounded technical fix queue from crawl evidence"
-  default_prompt: "Use $top-fixes to run the top-fixes report and explain its evidence and limits."

package/skills/traffic-anomaly/SKILL.md

@@ -1,52 +0,0 @@
----
-name: traffic-anomaly
-description: Test whether recent finalized GSC clicks or impressions differ unusually from an observed baseline; use it to confirm movement before investigating possible causes.
----
-
-# Detect unusual traffic movement
-
-Use `traffic-anomaly` when a dashboard looks different and you need a
-repeatable check against recent history. It compares a recent finalized GSC
-window with an observed baseline for clicks and impressions. Statistical
-unusualness helps decide whether deeper investigation is warranted. It does not
-identify a cause, diagnose a site defect, or prove that an external event
-affected the property.
-
-## Run the report
-
-With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`. Call
-`seo_describe_report` with `{"id":"traffic-anomaly"}` before choosing windows.
-Then call `seo_run_report`, for example
-`{"id":"traffic-anomaly","params":{"site":"sc-domain:example.com","days":90,"recentDays":7,"refresh":false}}`.
-
-CLI parity uses the same report definition:
-
-```sh
-seo reports describe traffic-anomaly --json
-seo reports run traffic-anomaly --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"refresh":false}' --json
-```
-
-The discovery schema currently exposes broad numeric types for these window
-fields. Use sensible positive whole-day values even though all bounds are not
-expressed in JSON Schema.
-
-## Interpret the output
-
-Read `coverage` first. Confirm the requested dates, expected and observed days,
-missing days, invalid rows, duplicate rows, and `status`. Partial coverage can
-change the baseline and must stay in the conclusion. `rows` is not a quality
-verdict.
-
-Each entry in `anomalies` names the metric, baseline and comparison dates,
-means and totals, `percentChange`, `zScore`, `significanceMethod`, `direction`,
-and `significant`. A null percentage from a zero baseline is different from
-zero change. `outside-flat-baseline` handles movement where an observed
-baseline has no variance; it still describes only the supplied data.
-
-## Act safely
-
-If movement is significant and coverage is adequate, run `segment-impact` for
-pages and queries, then check site changes, seasonality, indexing, and tracking.
-If it is normal, keep monitoring rather than forcing a story. Never label the
-result a penalty, algorithm update, recovery, or causal diagnosis without
-independent evidence.

package/skills/traffic-anomaly/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Traffic anomaly"
-  short_description: "Detect statistically unusual recent GSC movement"
-  default_prompt: "Use $traffic-anomaly to run the traffic-anomaly report and explain its evidence and limits."

package/skills/update-correlation/SKILL.md

@@ -1,51 +0,0 @@
----
-name: update-correlation
-description: Overlay finalized GSC anomaly windows with official Google ranking-update dates; use it for timing context while keeping attribution explicitly unestablished.
----
-
-# Add update timing context
-
-Use `update-correlation` only after defining the traffic window you want to
-examine. It combines the anomaly analysis with official ranking incident dates
-and known local changes. Overlap can make an update a reasonable investigation
-context. It cannot show that the update caused a gain or loss, even when the
-movement is large and no other change has been recorded.
-
-## Run the report
-
-With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`. Call
-`seo_describe_report` with `{"id":"update-correlation"}`, then use
-`seo_run_report`, for example
-`{"id":"update-correlation","params":{"site":"sc-domain:example.com","days":90,"recentDays":7,"paddingDays":2,"refresh":false}}`.
-
-The same definition is available through the CLI:
-
-```sh
-seo reports describe update-correlation --json
-seo reports run update-correlation --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"paddingDays":2,"refresh":false}' --json
-```
-
-The schema currently types window and padding values as general numbers. Pass
-positive whole-day values and avoid excessive padding that makes overlap almost
-inevitable.
-
-## Interpret the output
-
-Start with `classification`, but always keep `attribution` and `confidence` in
-view. The report intentionally returns attribution as `not-established` and
-confidence as `none`. Inspect the underlying `anomalies`, exact
-`overlappingUpdates`, and `confounders` before repeating the summary.
-
-Use `evidence` for observed movement and date overlap, `caveats` for window,
-padding, freshness, and source limits, and `source` to identify the official
-feed. `significant-movement-with-update-overlap` means both facts occurred in
-the configured window. `update-overlap-without-significant-movement` is not an
-impact result. `no-update-overlap` does not explain any movement that remains.
-
-## Act safely
-
-Test saved deploys, redirects, pruning, blocking, tracking, and content changes
-first when they overlap. Use `segment-impact` or the postmortem workflow to map
-affected templates and queries. Preserve winning patterns and investigate
-losers with page-level evidence. Never describe temporal overlap as a penalty,
-reward, recovery, or confirmed algorithm effect.

package/skills/update-correlation/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Update correlation"
-  short_description: "Compare recent GSC movement with official Google ranking update windows"
-  default_prompt: "Use $update-correlation to run the update-correlation report and explain its evidence and limits."

package/skills/update-postmortem/SKILL.md

@@ -1,49 +0,0 @@
----
-name: update-postmortem
-description: Compare retained winners and losers around a Google ranking update window. Use it to structure a postmortem while explicitly keeping causation unestablished.
----
-
-# Update postmortem workflow
-
-This workflow organizes performance movement around a known Google update,
-including template and segment evidence plus optional local change-log context.
-It helps identify where to investigate. Temporal overlap and exposure do not
-prove that the update caused any change, and retained winners and losers are not
-a complete property inventory when sources are capped or filtered.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "workflows"` and select `update-postmortem`.
-2. Call `seo_describe_report` with `id: "update-postmortem"`; inspect the current schema.
-3. Call `seo_run_report` with that id and only described parameters.
-
-CLI parity:
-
-```sh
-seo reports describe update-postmortem --json
-seo reports run update-postmortem --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"knownConfounders":["Site migration on 2026-05-12"],"includeChangeLog":true}' --json
-```
-
-Record specific known confounders rather than vague suspicions. The change log
-is supporting context, not automatic attribution.
-
-## Interpret and act
-
-Start with workflow step statuses, finalized date windows, source completeness,
-failed measurements, retained limits, and caveats. Then inspect `update`,
-`insights`, `templateMovement`, and `segments`. Keep positive and negative
-movement visible. The report's cause remains not established even when dates
-overlap. Compare like-for-like metrics and note brand filtering, invalid rows,
-duplicate aggregation, and partial provider results.
-
-Safe next steps are falsifiable: inspect representative URLs from affected
-segments, reproduce technical changes, compare deployed templates, validate the
-local change log, and measure a bounded intervention. Preserve known
-confounders in the handoff. Do not roll back, rewrite, merge, or delete content
-solely because it appears among losers. Never claim update causation, recovery
-probability, future traffic, or ranking impact from this workflow.
-
-Use MCP `structuredContent` as the machine contract and Markdown only for the
-human-readable postmortem.

package/skills/update-postmortem/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Update postmortem workflow"
-  short_description: "Analyze winners and losers around a Google ranking update window"
-  default_prompt: "Use $update-postmortem to run the update-postmortem report and explain its evidence and limits."