seo 0.1.0 → 0.2.1

package/skills/measure-change/SKILL.md

@@ -1,52 +0,0 @@
----
-name: measure-change
-description: Measure the before-and-after impact of a saved or ad hoc SEO change with equal finalized Google Search Console windows, optional GA4 landing-page evidence, and an optional control. Use when an agent needs to evaluate a release, page edit, migration, template change, or SEO test without mistaking an incomplete after-period for a decline.
----
-
-# Measure SEO change
-
-Call `seo_list_reports` with category `experiments` when discovery is needed.
-Call `seo_describe_report` with id `measure-change`, 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 measure-change --json
-seo reports run measure-change --params '{"site":"sc-domain:example.com","scope":"page","target":"https://example.com/page","title":"Updated page","changedAt":"2025-10-01","beforeDays":28,"afterDays":28}' --json
-
-seo tests report \
-  --project <project> \
-  --scope page \
-  --target https://example.com/page \
-  --date 2026-06-01 \
-  --before 28 \
-  --after 28 \
-  --json
-```
-
-Describe the report before building ad hoc parameters because the schema keeps
-saved-test and inline-test inputs in one contract. The catalog runner and the
-focused command execute the same measurement logic.
-
-For a saved test, pass its `id` instead of the ad hoc site, scope, target, and date fields.
-
-## Workflow
-
-1. Use the same whole-number duration for `beforeDays` and `afterDays`. Raw totals from unequal calendar windows are not comparable.
-2. Read `dataStatus`, `window`, `source`, `warnings`, and `caveats` before interpreting metrics.
-3. Confirm `window.effectiveDays` equals `window.requestedDays`. If `afterWindowTruncated` is true, the tool uses an equal shortened baseline, returns `partial`, and withholds a directional verdict.
-4. Require at least 7 finalized days in each window for a directional verdict. Shorter complete windows remain useful observations but return `not-enough-data`.
-5. Treat GSC clicks, impressions, CTR, and impression-weighted average position as observed before/after evidence. Timing does not prove that the recorded change caused the movement.
-6. For query-scoped tests, treat `retained-query-date-aggregates` as partial. A missing retained window returns null metrics and is not a zero or a loss.
-7. If GA4 is present, check its property timezone and `source.analytics.status`. GA4 day boundaries can differ from GSC Pacific dates; sampling, thresholding, or `(other)` grouping makes GA4 evidence partial.
-8. Use a control only when it represents a credible unaffected comparison. Adjusted deltas use a control-ratio counterfactual, not raw subtraction across differently sized groups.
-9. Investigate query mix, devices, countries, indexability, SERP changes, seasonality, and other releases before recommending a rollout or reversal.
-
-## Interpretation rules
-
-- Never call `not-enough-data` positive, negative, or flat.
-- Never annualize or forecast the observed delta.
-- Do not compare this run with another run that used different effective window lengths.
-- `clickPct: null` means the before value was zero; it is not an infinite percentage gain.
-- A partial GA4 source does not invalidate complete GSC evidence, but it does limit analytics conclusions.
-- Provider, auth, property, and invalid-date errors are failures, not zero movement.

package/skills/measure-change/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Measure SEO Change"
-  short_description: "Measure equal-window GSC and GA4 change evidence"
-  default_prompt: "Use $measure-change to measure this SEO change with equal finalized before and after evidence."

package/skills/monthly-action-plan/SKILL.md

@@ -1,50 +0,0 @@
----
-name: monthly-action-plan
-description: Run a calendar-month reporting workflow with a narrative and explicit actions. Use it for a repeatable review whose caveats remain attached to each measurement.
----
-
-# Monthly workflow
-
-This workflow packages the monthly narrative into a sequenced, agent-friendly
-result with explicit steps and actions. It helps keep recurring reviews
-consistent. It can report measured movement, but it cannot establish a cause,
-promise recovery, or turn incomplete provider evidence into a full-property
-conclusion.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "workflows"` and select `monthly-action-plan`.
-2. Call `seo_describe_report` with `id: "monthly-action-plan"`; confirm its current parameters.
-3. Call `seo_run_report` with that id and only schema-valid parameters.
-
-CLI parity:
-
-```sh
-seo reports describe monthly-action-plan --json
-seo reports run monthly-action-plan --params '{"site":"sc-domain:example.com","month":"2026-05","limit":10,"includeBrand":false}' --json
-```
-
-Supply `month` as `YYYY-MM`. `limit` controls retained output, not the provider's
-underlying completeness. Keep `includeBrand` explicit when comparisons must be
-reproducible across months.
-
-## Interpret and act
-
-Inspect the workflow envelope: `summary`, each entry in `steps`, `actions`, and
-the nested `output`. Confirm the requested month, final-data window, provider
-status, skipped sections, warnings, caveats, and retained caps. Follow narrative
-claims back into their structured diagnosis or measurement. A skipped section
-is not a zero, and a top-level successful workflow does not make every nested
-source complete.
-
-Use actions as a review queue, not automatic edit instructions. Verify affected
-URLs and intentional controls, reproduce technical defects, and record any
-approved changes for future measurement. Keep month-over-month movement
-separate from explanations. Do not invent click, traffic, ranking, or revenue
-forecasts, and do not attribute movement to an algorithm update or deployment
-from timing alone.
-
-Read MCP `structuredContent` as the machine contract. The rendered Markdown is
-the human brief, not an alternative data source for agents.

package/skills/monthly-action-plan/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Monthly workflow"
-  short_description: "Run the monthly reporting workflow"
-  default_prompt: "Use $monthly-action-plan to run the monthly-action-plan report and explain its evidence and limits."

package/skills/monthly-report/SKILL.md

@@ -1,50 +0,0 @@
----
-name: monthly-report
-description: Generate a calendar-month SEO narrative from finalized first-party evidence. Use it to brief humans while preserving source status, caveats, and measured next actions.
----
-
-# Monthly report
-
-Monthly reporting matters because it fixes the analysis to a named calendar
-period and turns several measurements into one reviewable brief. The report can
-show observed movement and prioritized investigations. It cannot establish why
-traffic changed, guarantee that a recommended edit will help, or forecast
-clicks, rankings, revenue, or future performance.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "reporting"` and select `monthly-report`.
-2. Call `seo_describe_report` with `id: "monthly-report"` and inspect the current schema.
-3. Call `seo_run_report` with `id: "monthly-report"` and only described parameters.
-
-The CLI exposes the same report:
-
-```sh
-seo reports describe monthly-report --json
-seo reports run monthly-report --params '{"site":"sc-domain:example.com","month":"2026-05","limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json
-```
-
-Use `YYYY-MM` for `month`. `limit` bounds retained findings, not provider row
-retrieval. `verifyContent` fetches a bounded subset, so `verifyLimit` must not
-be interpreted as full-site validation.
-
-## Interpret and act
-
-Confirm `month`, the underlying date windows, `dataStatus`, source completeness,
-skipped sections, warnings, and caveats before reading the headline. Treat the
-narrative as a rendering of structured evidence. Follow its references into
-the diagnosis, measured changes, priorities, and monitoring results when a
-claim needs verification. A zero from a complete source differs from an
-unavailable, partial, filtered, or capped section.
-
-Safe actions start with the highest-evidence priorities: validate affected URLs,
-compare relevant templates, inspect confirmed technical regressions, and assign
-owners to bounded tests. Keep brand filtering and content-verification status
-visible. Record what changed so the next month can measure it. Do not rewrite a
-page merely because it appears in a heuristic opportunity list, and do not
-present update overlap or timing as causation.
-
-Read MCP `structuredContent` as the machine contract. Use returned Markdown for
-the human brief, but never parse it to recover data already present in JSON.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Monthly report"
-  short_description: "Generate one monthly SEO narrative"
-  default_prompt: "Use $monthly-report to run the monthly-report report and explain its evidence and limits."

package/skills/narrative-report/SKILL.md

@@ -1,51 +0,0 @@
----
-name: narrative-report
-description: Assemble diagnosis, change measurement, and monitoring evidence into a readable SEO narrative. Use it for an evidence-linked briefing rather than a new source of truth.
----
-
-# Report narrative
-
-This report turns several structured analyses into a coherent explanation. It
-is useful when a person needs the important findings, caveats, and next actions
-without reading every raw section. The narrative summarizes evidence; it does
-not strengthen weak evidence, prove causation, or make missing and partial data
-complete.
-
-## Run it
-
-Use the exact MCP discovery flow:
-
-1. Call `seo_list_reports` with `category: "reporting"` and select `narrative-report`.
-2. Call `seo_describe_report` with `id: "narrative-report"` before constructing parameters.
-3. Call `seo_run_report` with `id: "narrative-report"` and schema-valid parameters.
-
-CLI parity:
-
-```sh
-seo reports describe narrative-report --json
-seo reports run narrative-report --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"changeLimit":5}' --json
-```
-
-Use explicit date bounds only when the described schema supports the intended
-window; otherwise `days` and `recentDays` keep comparisons consistent.
-`changeLimit` bounds attempted change measurements, while `limit` bounds
-retained report items.
-
-## Interpret and act
-
-Read `headline` only after checking top-level caveats. Then inspect `sections`,
-`priorities`, `diagnosis`, `changeMeasurements`,
-`changeMeasurementAttempts`, and `monitoring`. A failed or skipped measurement
-must stay visible; it is not a zero. Preserve each section's dates,
-completeness, thresholds, limits, and evidence references. Treat update timing,
-template groupings, and opportunity scores as investigation context, not
-ranking causes.
-
-Safe actions should trace back to observed evidence: reproduce a technical
-failure, inspect the affected URLs, validate an intentional control, or run a
-bounded content change with a recorded date. Keep recommended verification
-steps separate from asserted defects. Do not invent traffic lift, rank gains,
-revenue impact, or certainty that the source does not provide.
-
-MCP `structuredContent` is the machine contract. Returned Markdown is for human
-communication and should not replace the underlying JSON evidence.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Report narrative"
-  short_description: "Generate a readable SEO narrative from diagnosis, changes, and monitoring evi..."
-  default_prompt: "Use $narrative-report to run the narrative-report report and explain its evidence and limits."

package/skills/okf-build/SKILL.md

@@ -1,39 +0,0 @@
----
-name: okf-build
-description: Build a deterministic OKF Markdown knowledge bundle from a bounded crawl and validate its file contract. Use when an agent needs portable site evidence with explicit source selection and caveats.
----
-
-# Build an OKF bundle
-
-An OKF bundle packages crawl-derived concepts, page inventory, link relationships, provenance, and caveats as portable Markdown. The builder ranks eligible pages deterministically and limits the selected concepts. This makes the artifact reproducible, but it does not make extracted claims true or current.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` only when discovery is needed. Call `seo_describe_report` with `{ "id": "okf-build" }`, then `seo_run_report` with:
-
-```json
-{
-  "id": "okf-build",
-  "params": {
-    "reportId": "crawl_example_20260710",
-    "maxConcepts": 25,
-    "includeFiles": true,
-    "title": "Example site knowledge"
-  }
-}
-```
-
-Check `isError`, then use `structuredContent`. CLI parity is:
-
-```sh
-seo reports describe okf-build --json
-seo reports run okf-build --params '{"reportId":"crawl_example_20260710","maxConcepts":25,"includeFiles":true,"title":"Example site knowledge"}' --json
-```
-
-`includeFiles` is opt-in because file bodies can be large. Request only the manifest when discovering scope.
-
-## Inspect the bundle
-
-Read the manifest's schema version, report id, source URL, generation time, crawl status, title, concept count, file paths, warnings, and caveats. The `selection` block distinguishes source, eligible, duplicate-final, selected, and limited page counts and records the deterministic ordering. If selected pages equal the limit, treat the bundle as bounded rather than exhaustive.
-
-Review the returned validation before using files. Then inspect citations, canonical URLs, titles, summaries, and relationships against source pages, especially for sensitive or time-dependent claims. The generated log and caveat files should travel with the bundle. A successful structural validation does not establish ownership, freshness, factual accuracy, completeness, or safe downstream use. Rebuild from a comparable fresh crawl when the site changes; do not silently merge snapshots with different scope.

package/skills/okf-build/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Build OKF"
-  short_description: "Build a compact OKF site knowledge bundle"
-  default_prompt: "Use $okf-build to run the okf-build report and explain its evidence and limits."

package/skills/okf-validate/SKILL.md

@@ -1,43 +0,0 @@
----
-name: okf-validate
-description: Validate OKF paths, frontmatter, required files, concept links, and citation structure deterministically. Use before consuming or distributing a bundle, while checking factual quality separately.
----
-
-# Validate an OKF bundle
-
-Validation protects the file contract an agent depends on: required paths, unique files, root metadata, Markdown content, concept frontmatter, links, and citation sections. It does not browse cited sources or determine whether the knowledge is true, current, owned, complete, or safe.
-
-## Run it
-
-For MCP, call `seo_list_reports` with category `crawl` only if discovery is needed. Call `seo_describe_report` with `{ "id": "okf-validate" }`, then call `seo_run_report` with:
-
-```json
-{
-  "id": "okf-validate",
-  "params": {
-    "files": [
-      { "path": "index.md", "content": "---\nokf: \"0.1\"\ntype: \"index\"\n---\n# Example" },
-      { "path": "log.md", "content": "# Log" },
-      { "path": "concepts/index.md", "content": "# Concepts" },
-      { "path": "inventory/pages.md", "content": "---\ntype: \"inventory\"\n---\n# Pages\n\n# Citations" },
-      { "path": "graph/links.md", "content": "---\ntype: \"graph\"\n---\n# Links\n\n# Citations" },
-      { "path": "caveats.md", "content": "---\ntype: \"caveats\"\n---\n# Caveats\n\n# Citations" }
-    ]
-  }
-}
-```
-
-Check `isError`, then consume `structuredContent`.
-
-The CLI uses the same strict schema. This minimal six-file bundle is structurally valid:
-
-```sh
-seo reports describe okf-validate --json
-seo reports run okf-validate --params '{"files":[{"path":"index.md","content":"---\nokf: \"0.1\"\ntype: \"index\"\n---\n# Example"},{"path":"log.md","content":"# Log"},{"path":"concepts/index.md","content":"# Concepts"},{"path":"inventory/pages.md","content":"---\ntype: \"inventory\"\n---\n# Pages\n\n# Citations"},{"path":"graph/links.md","content":"---\ntype: \"graph\"\n---\n# Links\n\n# Citations"},{"path":"caveats.md","content":"---\ntype: \"caveats\"\n---\n# Caveats\n\n# Citations"}]}' --json
-```
-
-## Resolve findings
-
-Read `validation.valid`, file and concept counts, then every issue's level, path, and message. Errors invalidate the supported contract and should be fixed file by file. Warnings identify weaker portability or provenance, such as missing citation sections, and still require review even when `valid` is true. Use `explanation.nextActions` as ordering guidance, not as evidence that automated edits are safe.
-
-Preserve the original bundle while correcting a copy, rerun validation, and compare issue sets deterministically. After structural success, separately verify cited URLs, claims, dates, access restrictions, publisher intent, and the crawl snapshot recorded by the bundle. Never report `valid: true` as "fact checked."

package/skills/okf-validate/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Validate OKF"
-  short_description: "Validate supplied OKF Markdown files"
-  default_prompt: "Use $okf-validate to run the okf-validate report and explain its evidence and limits."

package/skills/page-opportunities/SKILL.md

@@ -1,31 +0,0 @@
----
-name: page-opportunities
-description: Review one URL against retained GSC demand, peer CTR evidence, and live page content; use when an agent needs query-level opportunities with verification and source limits intact.
----
-
-# Page opportunities
-
-Use this report to investigate how one page performs for the query/page rows retained by Search Console. It compares the target rows with a bounded site-wide peer sample and can fetch the live page to distinguish covered, unverified, technical, framing, ranking, and possible content-gap observations. It does not expose anonymized queries, explain ranking causes, or prove that a benchmark shortfall is recoverable 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":"page-opportunities"}`.
-3. Call `seo_run_report` with `{"id":"page-opportunities","params":{"site":"sc-domain:example.com","url":"https://example.com/pricing","days":90,"limit":15,"minImpressions":40,"verifyContent":true}}`.
-
-The CLI shares that schema and implementation:
-
-```sh
-seo reports describe page-opportunities --json
-seo reports run page-opportunities --params '{"site":"sc-domain:example.com","url":"https://example.com/pricing","days":90,"limit":15,"minImpressions":40,"verifyContent":true}' --json
-```
-
-`site` and `url` are required. Use `includeBrand:true` only when branded demand belongs in the decision. `verifyContent:false` saves a fetch but makes content-specific conclusions unavailable.
-
-## Interpret and act
-
-Check `dataStatus`, `range`, `source.targetRowsFetched`, `selection`, and `benchmark` first. A `benchmark.possiblyTruncated` value of true means the peer sample reached its cap. Read `verification.status` and `reason`; only `verified` results support live-page coverage observations. For each `item`, retain the query metrics, opportunity type, benchmark evidence, verification evidence, and recommendation together. `estimatedCtrClickShortfall` is a directional calculation, not a click forecast, and `summary.opportunities` is a review queue rather than a defect count.
-
-Safe actions include inspecting the live SERP, resolving status/indexability contradictions, testing title or description framing when the page already answers the query, strengthening a relevant answer, and adding a contextual internal link. Do not rewrite a page from query wording alone, infer an all-clear from partial data, or merge and delete pages without separate intent, canonical, and internal-link evidence.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Page opportunities"
-  short_description: "Find first-party opportunities for one URL"
-  default_prompt: "Use $page-opportunities to run the page-opportunities report and explain its evidence and limits."

package/skills/performance/SKILL.md

@@ -1,50 +0,0 @@
----
-name: performance
-description: Audit and interpret one URL's Lighthouse lab performance and device-specific CrUX field Core Web Vitals with the local seo CLI or MCP server. Use when an agent needs to investigate LCP, INP, CLS, TBT, page-speed diagnostics, mobile-versus-desktop evidence, or performance remediation without confusing lab, field, and fallback measurements.
----
-
-# Performance
-
-Run report id `performance-audit` through `seo_run_report` for structured agent
-output. Call `seo_describe_report` first when its parameters are not already
-known. Pass `url`, choose `strategy` as `mobile` or `desktop`, and use
-`refresh: true` only when a fresh measurement is required.
-
-CLI equivalents:
-
-```bash
-seo perf audit --url https://example.com/page --json
-seo perf audit --url https://example.com/page --strategy desktop --refresh --json
-```
-
-Set `SEO_CRUX_API_KEY` to request Chrome UX Report field data. The packaged
-Lighthouse runtime needs a compatible local Chrome installation.
-
-## Interpret the report
-
-1. Check `dataStatus`, `labDataStatus`, `fieldDataStatus`, and `caveats` first.
-2. Treat CrUX as rolling, device-specific field evidence. Check whether its
-   `scope` is the exact URL or the origin and quote the `collectionPeriod`.
-3. Treat Lighthouse as one controlled navigation lab run. Use its compact
-   `labInsights` and metric evidence for diagnosis, not as field experience.
-4. Treat Lighthouse TBT as a lab responsiveness diagnostic. Never rename it
-   INP. Field INP comes from CrUX.
-5. Use the field p75 thresholds encoded by the report: LCP good at 2,500ms or
-   less, INP good at 200ms or less, and CLS good at 0.1 or less. All three must
-   be available and good for the field assessment to be good.
-6. Prefer field findings when field and lab disagree. Explain that their
-   populations and measurement conditions differ.
-7. Keep recommendations tied to returned metrics or insights. Do not infer
-   sitewide performance from one URL, device, or run.
-
-## Guardrails
-
-- `source: fetch-fallback` is unscored transport evidence. Its duration is the
-  complete local fetch workflow, not TTFB, Lighthouse, or Core Web Vitals.
-- Stop performance conclusions when fallback evidence is blocked or non-2xx.
-- `unavailable_no_coverage` means CrUX lacks enough data; it does not mean the
-  page passed or failed Core Web Vitals.
-- `request_failed` is an operational provider problem, not a page finding.
-- Missing field metrics make the Core Web Vitals assessment incomplete.
-- Do not request or paste raw Lighthouse output unless a human explicitly
-  needs the underlying artifact; compact output is the stable agent contract.

package/skills/performance/agents/openai.yaml

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

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

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

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

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

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

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