seo 0.0.15 → 0.1.0

package/skills/performance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SEO Performance"
+  short_description: "Interpret lab and field performance evidence"
+  default_prompt: "Use $performance to audit this URL and explain the lab and field performance evidence."

package/skills/performance-audit/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: performance-audit
+description: Audit one URL with local Lighthouse lab data and optional CrUX field Core Web Vitals; use when an agent must separate reproducible diagnostics, real-user evidence, and fallback transport checks.
+---
+
+# Performance audit
+
+Use this report to diagnose page performance with three deliberately separate evidence classes. Lighthouse provides one local lab run and actionable diagnostics. CrUX, when `SEO_CRUX_API_KEY` is configured and coverage exists, provides p75 field Core Web Vitals for a device and URL or origin scope. If Lighthouse cannot run, the report falls back to unscored HTTP transport evidence so the failure remains useful without pretending it measured page experience.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"ai-search"}`.
+2. Call `seo_describe_report` with `{"id":"performance-audit"}`.
+3. Call `seo_run_report` with `{"id":"performance-audit","params":{"url":"https://example.com/","strategy":"mobile","refresh":true}}`.
+
+The CLI invokes the same report:
+
+```sh
+seo reports describe performance-audit --json
+seo reports run performance-audit --params '{"url":"https://example.com/","strategy":"mobile","refresh":true}' --json
+```
+
+`url` is required; `strategy` is `mobile` or `desktop`. Omit `refresh` to allow the 24-hour local cache.
+
+## Interpret and act
+
+Start with `dataStatus`, `source`, `labDataStatus`, and `fieldDataStatus`. A Lighthouse `score`, `grade`, lab metrics, and `labInsights` describe that test environment and run. CrUX `fieldData.metrics` describes aggregated real-user p75 values; preserve `scope`, `formFactor`, `collectionPeriod`, missing metrics, and assessment. Origin-level data is not page-level evidence. If `source` is `fetch-fallback`, `fallbackFetchDuration` is the complete local fetch workflow, not TTFB, Lighthouse, LCP, CLS, TBT, or INP, and it never earns a score.
+
+Use `topActions` as hypotheses tied to its evidence, then reproduce the relevant lab issue and verify after a change. Prioritise field failures with adequate coverage, recurring lab bottlenecks, and explicit savings evidence. Do not combine lab and field values into a new score, compare mobile with desktop as equivalent populations, or claim a ranking outcome from a passing or failing audit.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Performance audit"
+  short_description: "Audit one URL with Lighthouse and optional CrUX"
+  default_prompt: "Use $performance-audit to run the performance-audit report and explain its evidence and limits."

package/skills/pseo-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pseo-audit
+description: Audit programmatic SEO template families with retained Google Search Console data, sitemap discovery, bounded page crawls, and exact URL Inspection evidence. Use when an agent needs to find repeated URL templates, compare their search visibility, check sampled index or crawl problems, or review whether generated pages have distinct intent and utility.
+---
+
+# pSEO audit
+
+Call `seo_list_reports` with category `reporting` when discovery is needed.
+Call `seo_describe_report` with id `pseo-audit`, then call `seo_run_report` with
+that id and only the described parameters. Read `structuredContent` as the
+machine contract. Use the CLI for CI, saved JSON, or environments without MCP.
+
+```bash
+seo reports describe pseo-audit --json
+seo reports run pseo-audit --params '{"site":"sc-domain:example.com","detail":"summary"}' --json
+
+seo pseo audit --project <project> --json
+```
+
+The catalog command is the portable agent path and rejects parameters outside
+the MCP schema. The focused pSEO command adds human-readable flags and project
+selection while calling the same implementation.
+
+Pass `--site sc-domain:example.com` instead of `--project` when no project profile exists.
+
+## Run the audit in two passes
+
+Start with discovery and retained Search Console evidence. Keep MCP output compact.
+
+```json
+{
+  "site": "sc-domain:example.com",
+  "detail": "summary"
+}
+```
+
+Add sitemap URLs when Search Console may not expose the full template population.
+
+```bash
+seo pseo audit \
+  --project example \
+  --sitemap https://example.com/sitemap.xml \
+  --json
+```
+
+Rerun important templates with bounded technical samples. Three crawl and three URL Inspection samples are a sensible starting point. The maximum is 10 per template.
+
+```json
+{
+  "site": "sc-domain:example.com",
+  "crawlSamples": 3,
+  "inspectSamples": 3,
+  "detail": "full"
+}
+```
+
+URL Inspection uses property quota. Only request it when index evidence changes the decision.
+
+## Read the evidence in this order
+
+1. Check `dataStatus`, `source`, `selection`, `warnings`, and `caveats`.
+2. Use `population` to separate discovered, GSC-visible, sampled, and untested URLs.
+3. Read the template `verdict`, then confirm it against `crawl`, `inspection`, and `evidence`.
+4. Use `metrics.topQueries`, `queryPatterns`, and sample-level fields for the proposed action.
+
+The report applies the output limit after ranking eligible templates by retained page impressions, clicks, URL count, and a stable signature tie-break.
+
+## Keep claims inside the contract
+
+- `PASS` is the only indexed URL Inspection verdict. `NEUTRAL` means excluded, `FAIL` means invalid, and every other value is unknown.
+- `coverageState` is diagnostic text. Never parse it to decide whether a URL is indexed.
+- URL Inspection describes Google's indexed snapshot for one URL. It does not prove that every URL in the template is healthy or currently appearing in search.
+- Clicks, impressions, CTR, and position come from retained page-dimension Search Analytics rows. They are not guaranteed property totals.
+- Query patterns and examples come from retained query/page rows. Anonymized and lower-ranked rows may be absent.
+- Word count is descriptive. Do not recommend a minimum word count or call a page thin because it is short.
+- Literal query-term coverage and path entity fit are review heuristics. They are not Google ranking factors or spam-policy verdicts.
+- A sitemap URL with no GSC row does not prove zero demand. Performance may be omitted or credited to a canonical URL.
+
+## Explain verdicts precisely
+
+- `index-risk` means one or more sampled URLs returned exact excluded or invalid verdicts. State the sample count.
+- `crawl-risk` means sampled URLs showed HTTP, robots, noindex, canonical, or fetch failures.
+- `content-review` means at least three usable samples showed repeated metadata or weak literal term coverage. Ask for human review of originality, accuracy, and page-specific utility.
+- `opportunity` means retained page rows triggered position, CTR, or entity-fit heuristics. Verify the query intent before changing templates.
+- `healthy` requires at least two conclusive indexed samples and two usable crawl samples. It remains a sample finding.
+- `inconclusive` means search evidence exists but technical sampling is too weak for a health verdict.
+- `no-data` means no retained page evidence was found for the detected template. Do not turn that into a quality judgment.
+
+## Useful controls
+
+- `templateLimit`: 1 to 100 templates.
+- `minimumTemplateUrls`: 2 to 100 repeated URLs. The default is 3.
+- `minimumTemplateShare`: 0 to 1. The default is 0, so count controls discovery.
+- `minimumTemplateImpressions`: retained page-impression threshold. The default is 0.
+- `crawlSamples` and `inspectSamples`: 0 to 10 per template.
+- `brandTerms`: explicit terms to exclude. Domain-derived terms are used when none are supplied.
+- `refresh`: bypass supported local provider and HTTP caches.
+
+For CSV files run:
+
+```bash
+seo export pseo --project <project> --out ./seo-exports/pseo
+```

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pSEO Audit"
+  short_description: "Audit programmatic SEO templates with evidence"
+  default_prompt: "Use $pseo-audit to audit this site's programmatic SEO templates and explain the evidence."

package/skills/query-clusters/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: query-clusters
+description: Group retained GSC queries by deterministic token overlap and page evidence; use when an agent needs reproducible demand themes without embeddings or assumed search intent.
+---
+
+# Query clusters
+
+Use this report to organise retained GSC query/page rows into stable lexical themes. It normalizes queries, removes low-actionability and optionally branded rows, aggregates page evidence, then groups related wording by shared tokens. This is useful for navigation, information architecture, and review queues because the same input produces the same grouping. Token overlap does not prove shared intent, justify a new page, or establish that current URLs compete with each other.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"opportunities"}`.
+2. Call `seo_describe_report` with `{"id":"query-clusters"}`.
+3. Call `seo_run_report` with `{"id":"query-clusters","params":{"site":"sc-domain:example.com","scope":"/guides/","minImpressions":50,"limit":20,"includeBrand":false}}`.
+
+The CLI uses the same registry and report handler:
+
+```sh
+seo reports describe query-clusters --json
+seo reports run query-clusters --params '{"site":"sc-domain:example.com","scope":"/guides/","minImpressions":50,"limit":20,"includeBrand":false}' --json
+```
+
+`site` is required. `scope` filters to pages containing the supplied string. The catalog schema exposes a fixed final-data 28-day report window; inspect `range` rather than assuming another period.
+
+## Interpret and act
+
+Start with `summary`: retain cluster count, query count, clicks, impressions, threshold, limit, brand filtering, and high-opportunity count. Read each cluster's member queries, pages, demand, performance, and recommendation together. Expected CTR and opportunity labels are heuristic, using a leave-cluster-out site benchmark when enough peer evidence exists and otherwise a fallback curve. Page-two clusters do not claim a CTR-only click lift. Queries omitted below the threshold or outside the output cap remain outside the conclusion.
+
+Safe actions include reviewing whether a cluster maps to one intent, improving section structure on an existing page, clarifying navigation, or investigating URL overlap with a dedicated report. Do not create one page per cluster, merge pages based on tokens alone, infer semantic equivalence, or describe a low-volume omitted theme as absent demand.

package/skills/query-clusters/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Query cluster"
+  short_description: "Cluster retained GSC queries by token overlap"
+  default_prompt: "Use $query-clusters to run the query-clusters report and explain its evidence and limits."

package/skills/quick-wins/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: quick-wins
+description: Rank retained position 4-10 GSC query-page rows below a site-aware CTR target; use when an agent needs a bounded opportunity queue with optional live-content verification.
+---
+
+# Quick wins
+
+Use this report to prioritise retained query/page rows with meaningful impressions, average positions from 4 through 10, and CTR below a leave-target-out site benchmark or documented fallback curve. Optional page verification checks whether the live page covers the query or presents technical evidence before recommending a content action. “Quick win” describes the review queue, not effort, certainty, or expected traffic.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"opportunities"}`.
+2. Call `seo_describe_report` with `{"id":"quick-wins"}`.
+3. Call `seo_run_report` with `{"id":"quick-wins","params":{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"verifyContent":true,"verifyLimit":5}}`.
+
+The CLI calls the same definition:
+
+```sh
+seo reports describe quick-wins --json
+seo reports run quick-wins --params '{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"verifyContent":true,"verifyLimit":5}' --json
+```
+
+`site` is required. `limit` bounds returned rows and `verifyLimit` bounds live page checks. Use `js:true` and higher fetch rates only when needed and permitted.
+
+## Interpret and act
+
+Check `dataStatus`, date range, source row cap, `possiblyTruncated`, `selection.invalidRows`, filters, and limited rows. Read `methodology` and each item's benchmark confidence before using `targetCtr`. `estimatedCtrClickShortfall` and priority score are heuristics, explicitly not estimated lift. Inspect `verification.requested`, attempted, verified, failed, and technical counts. An unverified item still has GSC evidence but cannot support a content-coverage conclusion. Review groups and template patterns for repeated hypotheses without converting their sums into forecasts.
+
+Safe actions are to inspect the live SERP, resolve technical conflicts, test clearer snippet framing, improve a genuinely missing answer, or add a relevant internal link. Record the change and compare a later complete window. Do not promise clicks, force query wording into copy, treat average position as a stable rank, or call filtered or capped evidence an all-clear.

package/skills/quick-wins/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Quick wins"
+  short_description: "Find high-impression ranking and CTR review candidates"
+  default_prompt: "Use $quick-wins to run the quick-wins report and explain its evidence and limits."

package/skills/redirect-trace/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: redirect-trace
+description: Record every HTTP redirect hop and inspect the final page's indexability signals; use it to debug loops, broken chains, and destination mismatches for one URL.
+---
+
+# Trace one redirect path
+
+Use `redirect-trace` when a specific URL behaves unexpectedly after a move,
+canonical change, or routing release. It follows HTTP redirects manually,
+records each response, and audits the final destination for basic indexability
+and canonical evidence. The trace is one observation from the machine and time
+that ran it; CDNs, geography, cookies, user agents, and later deploys can differ.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"monitoring"}`. Call
+`seo_describe_report` with `{"id":"redirect-trace"}`, then call
+`seo_run_report`, for example
+`{"id":"redirect-trace","params":{"url":"https://example.com/old-page","maxHops":8,"js":false,"refresh":true}}`.
+
+The CLI uses the same registry:
+
+```sh
+seo reports describe redirect-trace --json
+seo reports run redirect-trace --params '{"url":"https://example.com/old-page","maxHops":8,"refresh":true}' --json
+```
+
+`maxHops` is currently a broad number in discovery. Pass a small positive whole
+number; very large chains are not a useful success condition.
+
+## Interpret the output
+
+Read `chain` in order. Each step contains the requested URL, status, `Location`,
+resolved next URL, and duration. Then compare `finalUrl` with `finalPage` and
+`summary.finalStatus`. `summary.issues` can identify a loop, hop limit,
+redirect without location, final 4xx or 5xx, non-indexable final page, or a
+canonical mismatch.
+
+Inspect `metaRobots`, `xRobotsTag`, canonical, and `warnings` as observations.
+A missing `finalPage` or fetch warning limits indexability conclusions.
+JavaScript rendering affects final-page extraction, not the HTTP redirect chain.
+A canonical pointing elsewhere can be intentional; a 302 can also be
+intentional. The report does not know the desired destination.
+
+## Act safely
+
+Confirm the intended URL map before editing redirects. Prefer one direct
+permanent redirect for a genuine move, remove loops, restore missing locations,
+and align the final canonical only when the destination is correct. Re-run the
+trace after deployment. Do not declare an SEO defect or ranking impact from a
+chain difference without intent and search evidence.

package/skills/redirect-trace/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Redirect trace"
+  short_description: "Trace one redirect chain"
+  default_prompt: "Use $redirect-trace to run the redirect-trace report and explain its evidence and limits."

package/skills/refresh-priorities/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: refresh-priorities
+description: Combine several first-party opportunity reports into a bounded refresh queue. Use it to prioritize investigation while preserving each source's distinct meaning and limits.
+---
+
+# Refresh priorities workflow
+
+This workflow helps choose what to inspect next by combining decay, position,
+CTR, exposure, diagnosis, content verification, and optional GA4 signals. It
+does not make those signals interchangeable or predict the benefit of an edit.
+The queue is a deterministic prioritization aid, not an autonomous content
+brief.
+
+## Run it
+
+Use the exact MCP discovery flow:
+
+1. Call `seo_list_reports` with `category: "workflows"` and select `refresh-priorities`.
+2. Call `seo_describe_report` with `id: "refresh-priorities"`; inspect all bounds.
+3. Call `seo_run_report` with that id and schema-valid parameters.
+
+CLI parity:
+
+```sh
+seo reports describe refresh-priorities --json
+seo reports run refresh-priorities --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json
+```
+
+Add `ga4PropertyId` only when that property's sessions are needed and accessible.
+`verifyLimit` caps fetched content checks; it does not verify every queued URL.
+
+## Interpret and act
+
+Read the workflow's steps and skipped states before its queue. For each queued
+item preserve `source`, `impactKind`, score breakdown, date window, completeness,
+verification status, and rationale. A click decline, low CTR, second-page
+average position, and GA4 session signal have different semantics. Missing GA4
+or failed content fetches must remain unavailable, not become zero-weight proof.
+
+Inspect the top few URLs manually. Confirm query intent, current content,
+technical accessibility, internal links, competing pages, and whether a recent
+change already explains the observation. Choose a bounded edit only when the
+evidence supports it, record the change date, and measure later. Never delete,
+merge, or rewrite content solely from the combined score. Do not present the
+score as expected clicks, revenue, ranking lift, or causal confidence.
+
+MCP `structuredContent` is the machine contract. Use Markdown for a concise
+human queue while retaining the underlying evidence fields for agents.

package/skills/refresh-priorities/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Refresh priorities workflow"
+  short_description: "Rank several first-party opportunity reports into one action queue"
+  default_prompt: "Use $refresh-priorities to run the refresh-priorities report and explain its evidence and limits."

package/skills/search-performance-overview/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: search-performance-overview
+description: Find where Google Search clicks and impressions changed, which pages or queries explain the movement, and which focused report to run next. Use when search performance moved or an agent needs a first-party baseline but does not yet know where to investigate.
+---
+
+# Search performance overview
+
+Use this when organic search performance changed and you do not yet know which
+pages, queries, countries, or devices explain it. It is also the best first
+report for a newly connected Search Console property. The report finds where
+the movement sits, then points to the focused report that can verify the issue.
+
+## Run it
+
+Use the exact MCP discovery flow:
+
+1. Call `seo_list_reports` with `category: "workflows"` and select `search-performance-overview`.
+2. Call `seo_describe_report` with `id: "search-performance-overview"` and inspect its schema.
+3. Call `seo_run_report` with that id and only schema-valid parameters.
+
+CLI parity:
+
+```sh
+seo reports describe search-performance-overview --json
+seo reports run search-performance-overview --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false}' --json
+```
+
+`days` sets the main evidence window and `recentDays` sets the recent comparison
+period. `limit` caps the items returned; it does not increase provider coverage.
+
+## Interpret and act
+
+Read the workflow envelope first: `workflow`, `site`, `generatedAt`, `summary`,
+`steps`, `actions`, and `output`. Every step has its own status and evidence.
+Then inspect the report's `dataStatus`, skipped sections, partial reasons,
+priorities, and nested anomaly, update, segment, decay, cannibalisation,
+striking-distance, and quick-win results. Do not let one complete section hide a
+failed or capped neighbour.
+
+Start with actions that cite reproducible evidence. Confirm affected URLs,
+provider dates, selection limits, and intentional technical controls before
+editing anything. Run a focused report to inspect detail rather than asking this
+broad workflow for a larger payload. Sparse data may legitimately skip a
+section. Update overlap, opportunity scores, average position, and timing are
+investigation signals, not causation or forecasts.
+
+Treat MCP `structuredContent` as the machine contract. Use Markdown for the
+human summary while preserving structured evidence references in any handoff.

package/skills/search-performance-overview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Search performance overview"
+  short_description: "Find where Google Search performance changed"
+  default_prompt: "Use $search-performance-overview to find where Google Search performance changed, explain the pages or queries behind it, and choose the next focused report."

package/skills/second-page/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: second-page
+description: Find retained GSC page-query rows with average positions from 10 through 20. Use them as bounded investigation prompts, not promised ranking wins.
+---
+
+# Second-page opportunities
+
+This report surfaces page-query combinations near the first-page boundary so an
+agent can inspect whether the page satisfies the observed query. It is a triage
+tool. Average position is aggregated across searches, locations, devices, and
+time; it is not an exact rank, proof of intent mismatch, or evidence that an
+edit will improve performance.
+
+## Run it
+
+Use the exact MCP discovery flow:
+
+1. Call `seo_list_reports` with `category: "reporting"` and select `second-page`.
+2. Call `seo_describe_report` with `id: "second-page"`; inspect bounds and defaults.
+3. Call `seo_run_report` with `id: "second-page"` and matching parameters.
+
+CLI parity:
+
+```sh
+seo reports describe second-page --json
+seo reports run second-page --params '{"site":"sc-domain:example.com","range":28,"minImpressions":50,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json
+```
+
+`range` is the analysis window. `minImpressions` removes very sparse candidates.
+`limit` is a retained-output cap. `verifyContent` fetches only up to
+`verifyLimit` candidates, so unverified items remain unknown rather than failed.
+
+## Interpret and act
+
+Check source completeness, date range, `selection`, `methodology`, provenance,
+brand filtering, and caveats before ranking the items. Duplicate provider rows
+should already be aggregated deterministically, but retained limits still mean
+the output is not a complete inventory. Read impressions, clicks, CTR, and
+average position as observed metrics. Treat the priority value as a transparent
+heuristic, not expected click lift.
+
+For a promising item, inspect the live page and search intent, verify that the
+query is appropriate for the URL, review internal linking and competing pages,
+then make one defensible change. Preserve pages already satisfying intent.
+Never add text solely to hit a length threshold, promise a first-page result,
+or infer cannibalisation from one row. If the source is capped, partial, or
+filtered, say so in the recommendation.
+
+Use MCP `structuredContent` as the machine contract and Markdown only to explain
+the evidence and next investigation to a human.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Second-page opportunities"
+  short_description: "Find URLs with retained GSC average positions above 10 through 20"
+  default_prompt: "Use $second-page to run the second-page report and explain its evidence and limits."

package/skills/segment-impact/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: segment-impact
+description: Compare matched retained GSC rows across adjacent periods for one dimension; use it to locate where observed movement is concentrated without treating missing rows as zero.
+---
+
+# Compare segment movement
+
+Use `segment-impact` after a property-level change is visible and you need to
+find which pages, queries, countries, or devices moved. It compares equal-length
+adjacent finalized GSC windows. The report deliberately limits conclusions to
+segments retained in both windows, so its deltas are comparable without
+inventing zeros for rows that disappeared from one retained result set.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`, then
+`seo_describe_report` with `{"id":"segment-impact"}`. Then call
+`seo_run_report` with the described report, for example
+`{"id":"segment-impact","params":{"site":"sc-domain:example.com","dimension":"page","days":28,"compareDays":28,"limit":20,"maxRows":50000,"unmatchedLimit":10}}`.
+
+The CLI uses the same schema:
+
+```sh
+seo reports describe segment-impact --json
+seo reports run segment-impact --params '{"site":"sc-domain:example.com","dimension":"page","days":28,"compareDays":28,"limit":20,"maxRows":50000,"unmatchedLimit":10}' --json
+```
+
+Use either relative windows or an explicit `startDate` and `endDate` after
+checking the current schema. Do not send undeclared fields.
+
+## Interpret the output
+
+Confirm `before`, `after`, and `rangeDays` before reading movement. Inspect
+`dataStatus`, `source.before`, `source.after`, and `source.completeness` for
+provider calls, row caps, and possible truncation. `selection` explains invalid,
+duplicate, conflicting, matched, unmatched, returned, and limited rows.
+
+In `items`, `clickDelta` and `impressionDelta` are after minus before. A positive
+`positionDelta` is worse because a larger GSC average position is lower in the
+results. `unmatchedSegments` are observations retained in one window only; they
+are not gains from or losses to zero. Read `warnings`, `caveats`, and
+`methodology` before describing a leading segment.
+
+## Act safely
+
+Use the top matched movers to define a smaller investigation: audit affected
+pages, group repeated templates, or compare query intent. Check unmatched rows
+separately with a wider export if they matter. Segment concentration does not
+establish why movement happened, and a limited or possibly truncated result
+cannot support an inventory-wide winner or loser claim.

package/skills/segment-impact/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Segment impact"
+  short_description: "Compare retained GSC movement by page, query, device, or country"
+  default_prompt: "Use $segment-impact to run the segment-impact report and explain its evidence and limits."

package/skills/seo/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: seo
+description: Route SEO work across the local seo CLI and MCP server. Use when an agent needs to choose between technical SEO, Search Console, GA4, crawl, opportunity, monitoring, and reporting workflows or inspect evidence returned by several reports.
+---
+
+# seo
+
+Use the `seo` MCP server exposed by the repository or installed package.
+
+Reason from MCP `structuredContent`. Treat text or Markdown content as the
+display layer. When MCP is unavailable use explicit CLI selectors and `--json`:
+
+```bash
+seo report --project <project> --json
+seo report --site sc-domain:example.com --json
+```
+
+Use the default Markdown output from `seo report-narrative` or
+`seo monthly-report` only when the user wants a readable report rather than a
+machine contract.
+
+## MCP flow
+
+The default MCP server exposes three tools:
+
+1. Call `seo_list_reports` to discover compact report ids, optionally by
+   category.
+2. Call `seo_describe_report` once for the selected id to load its exact JSON
+   Schema.
+3. Call `seo_run_report` with that id and a bounded `params` object.
+
+Do not guess parameters or ask for every report schema up front. Reuse a schema
+for repeated runs in the same session.
+
+## Which report id to use
+
+- Diagnosis: `search-performance-overview`,
+  `segment-impact`, `striking-distance`, `traffic-anomaly`, and
+  `update-correlation`.
+- Main follow-ups: `refresh-priorities`, `quick-wins`, `second-page`,
+  `decaying-pages`, `cannibalisation`, `ctr-underperformers`, and `query-clusters`.
+- Page work: `audit-page`, `page-opportunities`, `content-optimization`,
+  `internal-links`, and `performance-audit`.
+- Technical crawling: `site-crawl`, `top-fixes`, `affected-urls`,
+  `explain-crawl-issue`, `crawl-report`, and `compare-crawls`.
+- Indexing and monitoring: `index-coverage`, `index-watch`, `index-monitor`,
+  `index-coverage-plan`, `crawl-diff`, `redirect-trace`, and `link-recovery`.
+- AI-search evidence: `ai-readiness`, `geo-gaps`, `community-intent`,
+  `seo-to-ai-query`, and `ai-referrals`.
+- Reporting and measurement: `narrative-report`, `monthly-report`,
+  `measure-change`, `pseo-audit`, `update-postmortem`, and
+  `technical-watch`.
+- Local setup health: `setup-check`.
+
+Use the CLI for project-profile administration and intentionally raw provider
+queries. Useful commands include `seo projects list --json`, `seo gsc-query`,
+`seo url-inspect`, `seo ga4-properties`, `seo ga4-report`, and `seo updates`.
+
+## Rules
+
+- Treat observations as evidence within the report's methodology and data limits. Do not invent metrics.
+- Check `dataStatus`, source completeness, selection counts, warnings, and caveats before summarising a report.
+- In diagnosis output, check `summary.updateAttributionStatus` first and treat `summary.updateAttribution` as update-correlation context, not the site's overall diagnosis.
+- If `dataStatus` is `partial` or `unavailable`, name the skipped or incomplete evidence before describing findings. Treat capped sources the same way. Never turn unavailable or capped evidence into a zero-result claim.
+- Treat quick-win CTR targets and calculated shortfalls as deterministic prioritisation heuristics, not traffic forecasts.
+- Quote `principle` and `evidenceRef` when explaining recommendations.
+- Do not generate titles, metas, or copy. Keep advice structural and diagnostic.
+- If the tool returns no rows, say that clearly instead of padding the answer.
+- Remember that grouped GSC query totals can undercount due to anonymised rows.
+
+## Refresh behaviour
+
+- Tool output is cached locally.
+- Pass `refresh: true` when the user explicitly wants a fresh fetch.

package/skills/seo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "seo"
+  short_description: "Route local SEO reports and inspect evidence"
+  default_prompt: "Use $seo to choose the right local SEO report and explain its evidence."

package/skills/seo-fix-queue/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: seo-fix-queue
+description: Turn seo crawl and report evidence into a prioritized implementation queue. Use when the user wants exact SEO fixes, implementation tickets, affected URLs, verification steps, or a ranked technical SEO and GEO backlog.
+---
+
+# SEO fix queue
+
+Run the bounded queue directly:
+
+```bash
+seo crawl-queue --project <project> --json
+seo crawl-queue https://example.com --json
+```
+
+Through MCP, use `seo_run_report` with report id `site-crawl` and
+`saveReport: true`. Pass its `reportId` to report ids `top-fixes` and
+`affected-urls`. Reuse that report instead of crawling again. Call
+`seo_describe_report` before a report when its parameters are not already
+known.
+
+## Check the evidence before ranking work
+
+1. Read `dataStatus`, source joins, selection counts, warnings, and caveats.
+2. Check `summary.pageLimitReached`. A capped crawl cannot support an
+   inventory-wide zero or all-clear.
+3. Preserve the returned priority order unless stronger evidence supports a
+   change.
+4. Use GSC or GA4 evidence only when the source join is available. Do not call a
+   page search-visible or valuable from crawl evidence alone.
+5. Keep failed fetches, missing provider data, and filtered rows separate from
+   observed zeros.
+
+Each queue item should retain its rule id, priority, evidence, affected count,
+bounded URL sample, fix, and verification step. Explain unfamiliar rules with
+structured output:
+
+```bash
+seo explain --rule <rule-id> --json
+```
+
+Use report id `explain-crawl-issue` through `seo_run_report`.
+
+Write Markdown implementation tickets only when the user wants a handoff file:
+
+```bash
+seo crawl --project <project> --format markdown --output seo-fixes.md
+```
+
+Keep the final answer short. Show the top material fixes and end with the next
+verification command. Do not dump every rule the crawler checked.

package/skills/seo-fix-queue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SEO fix queue"
+  short_description: "Build a bounded evidence-backed SEO backlog"
+  default_prompt: "Use $seo-fix-queue to turn this site's crawl evidence into a prioritized implementation queue."