seo 0.1.0 → 0.2.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "seo",
-  "version": "0.1.0",
-  "description": "SEO Skills CLI and MCP for finding technical problems, ranking fixes with search data, and running reports locally.",
+  "version": "0.2.0",
+  "description": "The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and GA4 data.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "Ian Nuttall",
-  "homepage": "https://seoskills.dev",
+  "homepage": "https://seoskill.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/iannuttall/seo.git"
@@ -13,6 +13,7 @@
   "bugs": {
     "url": "https://github.com/iannuttall/seo/issues"
   },
+  "funding": "https://github.com/iannuttall/seo",
   "keywords": [
     "seo",
     "search-console",
@@ -41,6 +42,7 @@
   "files": [
     "dist",
     "skills",
+    "evals",
     "PRIVACY.md",
     "SECURITY.md",
     "TERMS.md",

package/skills/README.md

@@ -1,30 +1,41 @@
 # Agent skills
 
-These skills teach an agent how to use `seo` without reading the whole repo.
+This package ships one skill: `seo`. It teaches 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:
+The skill is a router, not a manual. It explains the discover, describe, run
+flow, names the report ids for common jobs, and states the evidence rules that
+apply to every report. It does not memorise each report. Per-report depth, when
+to use a report, when to avoid it, its schema, the order to read its output,
+what its evidence cannot support, and one verification step, is fetched at
+runtime with `describe`. This keeps the skill small and always in sync with the
+registry.
+
+## Install
+
+The skill works 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
+The skill also works by calling the CLI directly when MCP tools are not
+available. The npm package and repository contain the same skill. Install it
 with the standard agent skills installer:
 
 ```bash
-npx skills add iannuttall/seo --all
+npx skills add iannuttall/seo
 ```
 
-Use `seo skills list` or `seo skills path <name>` to inspect the copies bundled
-with the npm package.
+Use `seo skill list` or `seo skill path seo` to inspect the copy 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.
+## Discover, describe, run
 
-The same catalog is available without MCP:
+The MCP path is deliberately small: discover ids with `seo_list_reports`, load
+one report's full depth with `seo_describe_report`, then execute it with
+`seo_run_report`. The same catalog is available without MCP:
 
 ```bash
 seo reports list --json
@@ -32,50 +43,26 @@ 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`.
+Always describe a report before its first run. The describe response is the
+per-report manual: its `readOrder`, `doNotClaim` limits, `verify` step, and
+`related` ids come straight from the registry.
+
+## Adding a report
+
+Register the report once in `packages/mcp/src/report-registry.ts`, including its
+depth guidance in `packages/mcp/src/report-guidance.ts` and
+`packages/mcp/src/report-depth.ts` (`readOrder`, `doNotClaim`, `verify`,
+`related`). CLI discovery, MCP discovery, and the skill then share its id,
+description, input schema, handler, and depth automatically. No new skill file
+is needed. The router only lists report ids for common jobs; a report earns a
+mention there when it belongs in one of those chains.
+
+Run `pnpm skills:validate` after changing the skill or the registry. The
+validator checks the skill frontmatter and word count, that every command and
+report id the skill names resolves, that the MCP tool names are real, and that
+every `evals/*.json` is well formed.
+
+## Evals
+
+Behaviour tests for the skill live in the top-level `evals/` directory. See
+[../evals/README.md](../evals/README.md) for the file shape and how to run them.

package/skills/seo/SKILL.md

@@ -1,74 +1,99 @@
 ---
 name: seo
-description: Route SEO work across the local seo CLI and MCP server. Use when an agent needs to choose between technical SEO, Search Console, GA4, crawl, opportunity, monitoring, and reporting workflows or inspect evidence returned by several reports.
+description: Use and read this skill immediately if the user request is in any way related to SEO or a site's organic search or AI search presence. That includes site audits, rankings, click or traffic changes, indexing problems, crawling, redirects, sitemaps, metadata, structured data, Core Web Vitals, internal links, content opportunities, Search Console or GA4 questions, Google update impact, llms.txt, AI search visibility in ChatGPT, Claude, Perplexity, or Google AI Overviews, and client SEO reporting. Routes to 52 evidence-backed local reports through the SEO CLI and MCP server.
 ---
 
 # seo
 
-Use the `seo` MCP server exposed by the repository or installed package.
+`seo` is a local CLI, MCP server, and report engine. It answers SEO questions
+with evidence from three sources: its own crawl of the site, Google Search
+Console, and GA4. Every report returns structured JSON with the observed
+evidence, derived findings, caveats, and provenance kept separate. Nothing is
+hosted; data stays on the machine.
 
-Reason from MCP `structuredContent`. Treat text or Markdown content as the
-display layer. When MCP is unavailable use explicit CLI selectors and `--json`:
+You do not need to memorise reports. Discover them at runtime.
+
+## Discover, describe, run
+
+With the MCP server (preferred):
+
+1. `seo_list_reports` returns every report id with a one-line purpose,
+   optionally by category.
+2. `seo_describe_report` with one id returns when to use it, when to avoid it,
+   its exact JSON Schema, the order to read its output in, what its evidence
+   cannot support, one verification step, and related report ids.
+3. `seo_run_report` with the id and a bounded `params` object. Read
+   `structuredContent`, not the display text.
+
+The same catalog exists without MCP:
 
 ```bash
-seo report --project <project> --json
-seo report --site sc-domain:example.com --json
+seo reports list --json
+seo reports describe <report-id> --json
+seo reports run <report-id> --params '<json>' --json
 ```
 
-Use the default Markdown output from `seo report-narrative` or
-`seo monthly-report` only when the user wants a readable report rather than a
-machine contract.
-
-## MCP flow
-
-The default MCP server exposes three tools:
-
-1. Call `seo_list_reports` to discover compact report ids, optionally by
-   category.
-2. Call `seo_describe_report` once for the selected id to load its exact JSON
-   Schema.
-3. Call `seo_run_report` with that id and a bounded `params` object.
-
-Do not guess parameters or ask for every report schema up front. Reuse a schema
-for repeated runs in the same session.
-
-## Which report id to use
-
-- Diagnosis: `search-performance-overview`,
-  `segment-impact`, `striking-distance`, `traffic-anomaly`, and
-  `update-correlation`.
-- Main follow-ups: `refresh-priorities`, `quick-wins`, `second-page`,
-  `decaying-pages`, `cannibalisation`, `ctr-underperformers`, and `query-clusters`.
-- Page work: `audit-page`, `page-opportunities`, `content-optimization`,
-  `internal-links`, and `performance-audit`.
-- Technical crawling: `site-crawl`, `top-fixes`, `affected-urls`,
-  `explain-crawl-issue`, `crawl-report`, and `compare-crawls`.
-- Indexing and monitoring: `index-coverage`, `index-watch`, `index-monitor`,
-  `index-coverage-plan`, `crawl-diff`, `redirect-trace`, and `link-recovery`.
-- AI-search evidence: `ai-readiness`, `geo-gaps`, `community-intent`,
-  `seo-to-ai-query`, and `ai-referrals`.
-- Reporting and measurement: `narrative-report`, `monthly-report`,
-  `measure-change`, `pseo-audit`, `update-postmortem`, and
-  `technical-watch`.
-- Local setup health: `setup-check`.
-
-Use the CLI for project-profile administration and intentionally raw provider
-queries. Useful commands include `seo projects list --json`, `seo gsc-query`,
-`seo url-inspect`, `seo ga4-properties`, `seo ga4-report`, and `seo updates`.
-
-## Rules
-
-- Treat observations as evidence within the report's methodology and data limits. Do not invent metrics.
-- Check `dataStatus`, source completeness, selection counts, warnings, and caveats before summarising a report.
-- In diagnosis output, check `summary.updateAttributionStatus` first and treat `summary.updateAttribution` as update-correlation context, not the site's overall diagnosis.
-- If `dataStatus` is `partial` or `unavailable`, name the skipped or incomplete evidence before describing findings. Treat capped sources the same way. Never turn unavailable or capped evidence into a zero-result claim.
-- Treat quick-win CTR targets and calculated shortfalls as deterministic prioritisation heuristics, not traffic forecasts.
-- Quote `principle` and `evidenceRef` when explaining recommendations.
-- Do not generate titles, metas, or copy. Keep advice structural and diagnostic.
-- If the tool returns no rows, say that clearly instead of padding the answer.
-- Remember that grouped GSC query totals can undercount due to anonymised rows.
-
-## Refresh behaviour
-
-- Tool output is cached locally.
-- Pass `refresh: true` when the user explicitly wants a fresh fetch.
+Always describe a report before its first run in a session. The describe
+response is the per-report manual: follow its `readOrder`, respect its
+`doNotClaim` limits, and use its `related` ids to decide what to run next.
+Reuse the schema for repeated runs. Do not guess parameters.
+
+## Setup and selection
+
+Run the `setup-check` report (or `seo doctor`) if auth state is unknown.
+Saved project profiles are selected with `--project <id>`; list them with
+`seo projects list --json`. Without a profile, pass `--site sc-domain:example.com`
+for Search Console reports or `--url https://example.com` for crawl-only
+reports. Crawl and page audits work with no Google connection at all. Always
+pass `--json`; JSON mode never prompts.
+
+## Common jobs
+
+Each job lists report ids in a sensible starting order. Run the first, read
+its evidence, then decide; do not run a whole chain blindly.
+
+| Job | Reports |
+|---|---|
+| Page not indexed or missing from Google | `index-coverage`, `index-monitor` (URL Inspection), `audit-page`, `redirect-trace` |
+| Traffic or clicks dropped | `search-performance-overview`, `traffic-anomaly`, `update-correlation`, `segment-impact`, `decaying-pages`, `link-recovery` |
+| Audit a whole site | `report` command (main report), `site-crawl`, `top-fixes`, `ai-search-scorecard` |
+| More clicks from existing pages | `quick-wins`, `ctr-underperformers`, `striking-distance`, `second-page`, `internal-links` |
+| AI search visibility and readiness | `ai-search-scorecard`, `ai-readiness`, `geo-gaps`, `entity-readiness`, `llms-txt-audit`, `ai-referrals` |
+| Plan content from real demand | `query-clusters`, `page-opportunities`, `content-optimization`, `cannibalisation` |
+| Catch regressions over time | `technical-watch`, `crawl-diff`, `index-watch`, `measure-change` after a fix ships |
+| Client-ready reporting | `monthly-report`, `narrative-report`, `monthly-action-plan` |
+| Turn crawl findings into tickets | `top-fixes`, `affected-urls`, `explain-crawl-issue` |
+
+A single page complaint usually needs both angles: the index evidence for that
+URL and an `audit-page` pass for content or technical problems on the page
+itself.
+
+The main human report is the `seo report` command. It is the right first move
+when the user asks a broad "how is my site doing" question; the focused
+reports above are for specific symptoms.
+
+## Evidence rules
+
+- Check `dataStatus`, selection counts, `caveats`, and `warnings` before
+  summarising any report. Name skipped or incomplete evidence first.
+- Partial, capped, filtered, or sampled sources never support a zero or an
+  all-clear. Grouped Search Console totals undercount because anonymised query
+  rows are withheld.
+- Values marked heuristic are prioritisation aids, not forecasts. Never
+  promise clicks, rankings, indexing, or AI citations from any report.
+- Quote `principle` and `evidenceRef` when explaining a recommendation, and
+  give the user the report's verification step alongside any suggested change.
+- If a report returns no rows, say so plainly.
+- Intentional controls such as `noindex`, canonicals, and robots rules are
+  observations until the user confirms they are unintended.
+
+## Beyond the report catalog
+
+The CLI also has direct commands for raw provider access and administration:
+`seo gsc-query`, `seo url-inspect`, `seo ga4-report`, `seo updates`,
+`seo crawl`, `seo export`, and `seo projects`. Use `seo help all` to list
+everything. Prefer a registered report when one covers the question, because
+reports carry provenance and caveats that raw queries do not.
+
+Report output is cached locally. Pass `refresh: true` (or `--refresh`) only
+when the user explicitly wants a fresh fetch.

package/skills/seo/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "seo"
-  short_description: "Route local SEO reports and inspect evidence"
-  default_prompt: "Use $seo to choose the right local SEO report and explain its evidence."
+  short_description: "Use immediately for anything touching SEO, organic search, or AI search: audits, rankings, traffic changes, indexing, crawling, Search Console, GA4, or AI visibility"
+  default_prompt: "Use $seo to discover, describe, and run the right local SEO report and explain its evidence."