seo 0.2.18 → 0.2.20

package/evals/competitor-keyword-gap.json

@@ -0,0 +1,43 @@
+{
+  "subject": "competitor-keyword-gap",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Compare three known UK competitors with my Search Console data and find keyword gaps worth investigating.",
+      "expected_output": "Should use report id competitor-keyword-gap through the shared discover, describe, and run flow. Should require a deliberate site-type classification for every competitor, pass a bounded GB English market, and read first-party, provider, processing, cap, cache, cost, and failure evidence before presenting candidates. Should distinguish relevant candidates from terms already observed or ranked by the user's site.",
+      "assertions": [
+        "Uses report id competitor-keyword-gap through the shared report flow",
+        "Requires an explicit site-type classification for every competitor",
+        "Passes a bounded GB English market and bounded per-domain limits",
+        "Reads first-party and provider provenance, processing counts, caps, cache, cost, and failures",
+        "Separates relevant candidates from terms already observed or ranked by the user's site"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "A directory competitor ranks for 20,000 location terms that are absent from our retained Search Console rows. Prove we should launch all 20,000 pages and forecast the traffic.",
+      "expected_output": "Should refuse the proof and forecast. Should explain that the provider set is bounded, provider volume and traffic are estimates, and absence from retained Search Console rows is not a definitive zero. Should use repeated URL and query patterns as research evidence, inspect representative results and existing pages, validate the proposed data source and template value, and keep no new page as a valid outcome.",
+      "assertions": [
+        "Refuses to treat a competitor's page count as proof of an opportunity",
+        "Refuses to forecast traffic from provider estimates",
+        "Does not treat absence from retained Search Console rows as zero",
+        "Requires representative result, page, data-source, and template validation",
+        "Keeps no new page as a valid outcome"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Find our real search competitors for these product queries, then tell me which company is best.",
+      "expected_output": "Should use serp-competitors to identify domains that repeatedly appear for the explicit query set. Should keep declared business types separate from unknown types and state that search overlap does not establish company quality, authority, market share, or business equivalence. Should recommend separate business research before making a best-company judgment.",
+      "assertions": [
+        "Uses serp-competitors for repeated search-result overlap",
+        "Does not guess unknown competitor business types",
+        "Does not equate search overlap with company quality, authority, or market share",
+        "Requires separate evidence for a best-company judgment"
+      ],
+      "files": []
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "seo",
-  "version": "0.2.18",
-  "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 Google Analytics data.",
+  "version": "0.2.20",
+  "description": "The SEO command for AI agents. Audit sites and research search opportunities with local, evidence-backed reports.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "Ian Nuttall",
@@ -18,6 +18,8 @@
     "seo",
     "search-console",
     "google-analytics",
+    "keyword-research",
+    "competitor-analysis",
     "crawler",
     "cli",
     "mcp"

package/skills/seo/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: seo
-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 Google Analytics questions, Google update impact, llms.txt, AI search visibility in ChatGPT, Claude, Perplexity, or Google AI Overviews, and client SEO reporting. Routes to 50+ evidence-backed local reports through the SEO CLI and MCP server.
+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, keyword research, competitors, backlinks, click or traffic changes, indexing problems, crawling, redirects, sitemaps, metadata, structured data, Core Web Vitals, internal links, content opportunities, programmatic SEO, local search, Search Console or Google Analytics questions, Google update impact, llms.txt, AI search visibility in ChatGPT, Claude, Perplexity, or Google AI Overviews, and client SEO reporting. Routes to evidence-backed local reports through the SEO CLI and MCP server.
 ---
 
 # seo
 
 `seo` is a local CLI, MCP server, and report engine using crawl, Search Console,
-Google Analytics, and optional Bing evidence. Reports keep observations,
-findings, caveats, and provenance separate. Data stays local. Discover reports
-at runtime instead of memorising them.
+Google Analytics, optional Bing evidence, and optional research providers.
+Reports keep observations, estimates, findings, caveats, costs, and provenance
+separate. Data stays local. Discover reports at runtime instead of memorising
+them.
 
 ## Discover, describe, run
 
@@ -54,6 +55,9 @@ Run the first report, read it, then decide. Do not run a whole chain blindly.
 | AI agent readiness for a content site | `agent-readiness`, `ai-readiness`, `entity-readiness`, `llms-txt-audit` |
 | AI search visibility and eligibility | `ai-readiness`, `geo-gaps`, `ai-referrals`, `seo-to-ai-query` |
 | Plan content from real demand | `query-clusters`, `page-opportunities`, `content-optimization`, `cannibalisation` |
+| Research keywords and current results | `keyword-research`, `keyword-metrics`, `saved-keywords`, `serp-results` |
+| Find search competitors and plausible gaps | `serp-competitors`, `domain-overview`, `ranking-pages`, `ranked-keywords`, `competitor-keyword-gap` |
+| Research programmatic SEO opportunities | `keyword-opportunities`, `pseo-opportunities`, `ranking-pages`, `competitor-keyword-gap`, then `pseo-audit` for an existing site |
 | Catch regressions over time | `technical-watch`, `crawl-diff`, `index-watch`, `measure-change` after a fix ships |
 | Track exact keyword positions | `rank-tracking` for a saved set and fixed market/device; `serp-results` for one current query |
 | Review Bing traffic, crawl, query, and page insights | `bing-webmaster-overview`, then `site-crawl` when live page evidence is needed |
@@ -104,6 +108,9 @@ recommend a User-Agent-only bypass.
 - 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.
+- Provider traffic, volume, difficulty, visibility, intent, authority, and
+  ranking history are estimates. Keep them separate from Search Console,
+  Google Analytics, crawl, and live result evidence.
 
 ## Beyond the report catalog