seo 0.0.15 → 0.1.0

package/skills/index-watch/SKILL.md

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

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

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

package/skills/internal-links/SKILL.md

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

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

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

package/skills/link-recovery/SKILL.md

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

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

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

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

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

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

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

package/skills/measure-change/SKILL.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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