seo 0.0.15 → 0.1.0

package/package.json

@@ -1,36 +1,114 @@
 {
   "name": "seo",
-  "version": "0.0.15",
-  "description": "A connect middleware that serves html snapshots of single page apps",
-  "main": "index.js",
-  "scripts": {
-    "test": "make test"
-  },
+  "version": "0.1.0",
+  "description": "SEO Skills CLI and MCP for finding technical problems, ranking fixes with search data, and running reports locally.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Ian Nuttall",
+  "homepage": "https://seoskills.dev",
   "repository": {
     "type": "git",
-    "url": "git://github.com/saschagehlich/node-seo.git"
+    "url": "git+https://github.com/iannuttall/seo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iannuttall/seo/issues"
   },
   "keywords": [
-    "snapshot",
-    "phantom",
-    "search",
-    "bots"
+    "seo",
+    "search-console",
+    "google-analytics",
+    "crawler",
+    "cli",
+    "mcp"
   ],
-  "author": "Sascha Gehlich <sascha@gehlich.us>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/saschagehlich/node-seo/issues"
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "seo": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "PRIVACY.md",
+    "SECURITY.md",
+    "TERMS.md",
+    "TRADEMARKS.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "pnpm@11.11.0",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "auth:inject-shared-client": "node scripts/inject-shared-oauth-client.mjs",
+    "build": "turbo run build && pnpm run build:package",
+    "build:package": "tsdown --config tsdown.config.ts",
+    "clean": "turbo run clean && rm -rf dist",
+    "dev": "turbo run dev",
+    "lint": "biome check . && node scripts/check-emdashes.mjs && node scripts/check-report-parity.mjs && pnpm run skills:validate && turbo run lint",
+    "lint:fix": "biome check . --write",
+    "loc:audit": "node scripts/loc-audit.mjs",
+    "pack:check": "pnpm pack --dry-run",
+    "prepack": "pnpm run skills:validate && pnpm run build:package && node --test scripts/package.test.mjs",
+    "security:audit": "pnpm audit --audit-level low",
+    "security:check": "pnpm run security:audit && pnpm run security:secrets",
+    "security:secrets": "node scripts/security-secrets.mjs",
+    "skills:validate": "node scripts/validate-skills.mjs",
+    "test": "turbo run test && pnpm run build:package && node --test scripts/package.test.mjs && pnpm run skills:validate",
+    "test:package-install": "pnpm run build:package && node --test scripts/installed-package.test.mjs",
+    "typecheck": "turbo run typecheck"
   },
-  "homepage": "https://github.com/saschagehlich/node-seo",
   "dependencies": {
-    "underscore": "~1.6.0",
-    "phantom": "~0.6.1",
-    "q": "~1.0.1"
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "^0.6.0",
+    "@napi-rs/keyring": "^1.3.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.20.1",
+    "better-sqlite3": "^12.11.1",
+    "citty": "^0.2.2",
+    "cli-table3": "^0.6.5",
+    "consola": "^3.4.2",
+    "debug": "^4.4.3",
+    "defuddle": "^0.19.1",
+    "jsonc-parser": "^3.3.1",
+    "lighthouse": "13.4.0",
+    "linkedom": "^0.18.13",
+    "open": "^11.0.0",
+    "p-queue": "^9.3.1",
+    "p-retry": "^8.0.0",
+    "picocolors": "^1.1.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "playwright-core": "1.61.1",
+    "proper-lockfile": "^4.1.2",
+    "robots-parser": "^3.0.1",
+    "schema-dts": "^2.0.0",
+    "undici": "^8.7.0",
+    "update-notifier": "^7.3.1",
+    "user-agents": "2.1.117",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "should": "~3.3.1",
-    "mocha": "~1.18.2",
-    "supertest": "~0.12.0",
-    "express": "~4.1.2"
+    "@biomejs/biome": "^2.5.3",
+    "@changesets/cli": "^2.31.0",
+    "tsdown": "^0.22.4",
+    "turbo": "^2.10.4",
+    "typescript": "^6.0.3"
   }
 }

package/skills/README.md

@@ -0,0 +1,81 @@
+# Agent skills
+
+These skills teach an agent how to use `seo` without reading the whole repo.
+
+They work best with the MCP server installed. This command is an interactive
+setup flow for a human:
+
+```bash
+seo mcp install
+```
+
+They can also call the CLI directly when MCP tools are not available. The npm
+package and repository contain the same skill folders. Install the collection
+with the standard agent skills installer:
+
+```bash
+npx skills add iannuttall/seo --all
+```
+
+Use `seo skills list` or `seo skills path <name>` to inspect the copies bundled
+with the npm package.
+
+The MCP path is deliberately small: discover ids with `seo_list_reports`, load
+one schema with `seo_describe_report`, then execute it with `seo_run_report`.
+The skills name the report ids for their workflow.
+
+The same catalog is available without MCP:
+
+```bash
+seo reports list --json
+seo reports describe <report-id> --json
+seo reports run <report-id> --params '<json>' --json
+```
+
+## Adding a report skill
+
+Register a structured report once in `packages/mcp/src/report-registry.ts`.
+CLI and MCP discovery will then share its id, description, input schema, and
+handler. Add the same-name skill only after that contract exists.
+
+Every report skill must:
+
+- explain the technical SEO question and why it is useful;
+- show `seo_list_reports`, `seo_describe_report`, and `seo_run_report` usage;
+- show schema discovery and one valid `seo reports run` CLI example;
+- explain the evidence fields, partial-data states, and important caveats;
+- turn findings into bounded actions and verification steps; and
+- avoid turning estimates, conventions, or samples into search-engine rules.
+
+Run `pnpm skills:validate` after adding or changing a skill. The validator
+checks registry parity, command and tool names, frontmatter, package metadata,
+and minimum report guidance depth.
+
+## Curated workflow skills
+
+- `seo-site-audit`: start with the main report, then add bounded technical evidence.
+- `seo-geo-readiness`: check AI-search readiness and citation gaps.
+- `seo-fix-queue`: turn crawl results into an implementation queue.
+- `pseo-audit`: audit repeated URL templates with GSC, crawl, and URL Inspection evidence.
+- `index-watch`: monitor exact indexed-state evidence, transitions, failures, and quota-deferred checks.
+- `performance`: separate Lighthouse lab diagnostics, CrUX field Core Web Vitals, and unscored fallback evidence.
+- `community-intent`: review explicit intent language in retained GSC queries without claiming a page gap.
+- `seo-to-ai-query`: create deterministic monitoring-prompt suggestions from retained GSC queries.
+- `measure-change`: compare equal finalized GSC windows without turning an incomplete after-period into a directional verdict.
+
+The `seo` skill routes requests that span several focused workflows.
+
+## Report skills
+
+Every compact MCP report id has a same-name skill. Each skill teaches the
+discovery flow and the evidence limits that matter for that report.
+
+- Setup: `setup-check`.
+- Diagnosis: `search-performance-overview`, `segment-impact`, `striking-distance`, `traffic-anomaly`, `update-correlation`.
+- Opportunities: `cannibalisation`, `ctr-underperformers`, `decaying-pages`, `internal-links`, `query-clusters`, `quick-wins`.
+- AI search: `ai-referrals`, `community-intent`, `content-optimization`, `page-opportunities`, `performance-audit`, `seo-to-ai-query`.
+- Crawl: `affected-urls`, `ai-readiness`, `audit-urls`, `compare-crawls`, `site-crawl`, `entity-readiness`, `explain-crawl-issue`, `geo-gaps`, `crawl-report`, `crawl-history`, `crawler-rules`, `llms-txt-audit`, `generate-llms-txt`, `okf-build`, `okf-validate`, `top-fixes`.
+- Monitoring: `crawl-diff`, `index-coverage`, `index-coverage-plan`, `index-monitor`, `index-watch`, `link-recovery`, `redirect-trace`.
+- Reporting: `audit-page`, `monthly-report`, `pseo-audit`, `narrative-report`, `second-page`.
+- Experiments: `measure-change`.
+- Workflows: `monthly-action-plan`, `refresh-priorities`, `technical-watch`, `update-postmortem`.

package/skills/affected-urls/SKILL.md

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

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

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

package/skills/ai-readiness/SKILL.md

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

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

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

package/skills/ai-referrals/SKILL.md

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

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

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

package/skills/audit-page/SKILL.md

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

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

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

package/skills/audit-urls/SKILL.md

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

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

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

package/skills/cannibalisation/SKILL.md

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

package/skills/cannibalisation/agents/openai.yaml

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

package/skills/community-intent/SKILL.md

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

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

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

package/skills/compare-crawls/SKILL.md

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

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

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

package/skills/content-optimization/SKILL.md

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

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

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