Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

v0.21.0 feat: /content-planner skill + local calendar viewer

Claude134cb99b97c9
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 041d5463..a854217e 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",
- "version": "0.20.0"
+ "version": "0.21.0"
},
"plugins": [
{
"name": "toprank",
"source": "./",
- "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",
- "version": "0.20.0",
+ "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",
+ "version": "0.21.0",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 60551bb0..f4a5c866 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "toprank",
- "version": "0.20.0",
+ "version": "0.21.0",
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.",
"author": {
"name": "NotFair",
@@ -15,6 +15,7 @@
"./meta-ads/audit",
"./seo/seo-analysis",
"./seo/content-writer",
+ "./seo/content-planner",
"./seo/keyword-research",
"./seo/meta-tags-optimizer",
"./seo/schema-markup-generator",
diff --git a/AGENTS.md b/AGENTS.md
index 925c3534..8e84324a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,7 +23,8 @@ Skills under `seo/`, `google-ads/`, `meta-ads/`, `gemini/`, and `toprank-upgrade
| Full-site SEO audit, traffic drop, GSC analysis, Core Web Vitals | `seo-analysis` | `seo/seo-analysis/SKILL.md` |
| Single-page deep audit (URL-specific) | `seo-page` | `seo/seo-page/SKILL.md` |
| Write or improve content (blog, landing, service page) | `content-writer` | `seo/content-writer/SKILL.md` |
-| Keyword discovery, topic clusters, content calendar | `keyword-research` | `seo/keyword-research/SKILL.md` |
+| Plan content from GSC data, build a dated editorial calendar | `content-planner` | `seo/content-planner/SKILL.md` |
+| Keyword discovery, topic clusters (seed → keyword universe) | `keyword-research` | `seo/keyword-research/SKILL.md` |
| Title tags, meta descriptions, Open Graph, CTR | `meta-tags-optimizer` | `seo/meta-tags-optimizer/SKILL.md` |
| JSON-LD / structured data (FAQ, Product, HowTo, etc.) | `schema-markup-generator` | `seo/schema-markup-generator/SKILL.md` |
| Broken-link / 404 / site-health crawl | `broken-link-checker` | `seo/broken-link-checker/SKILL.md` |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec210a85..0af0f6d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,46 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.21.0] — 2026-05-15
+
+### Added — `/content-planner` skill + local calendar viewer
+- **New skill: `seo/content-planner`.** A GSC-driven content calendar. Pulls
+ 90 days of Search Console query × page data, classifies every (query, page)
+ row into one of five buckets (striking-distance positions 5–20,
+ unanswered-intent gaps, CTR underperformers, related-keyword expansions, and
+ cannibalization warnings), computes a click-potential score per topic
+ (`projectedImpressions × (targetCtrAtPosition3 − currentCtr)`), and writes
+ a dated, prioritized calendar to `{data_dir}/content-calendar.json`.
+ Refuses to ship the calendar when GSC isn't connected, when there's < 50
+ rows of data to reason about, or when two scheduled topics share a primary
+ keyword. Hands off to `/content-writer`, `/meta-tags-optimizer`, and
+ `/seo-analysis` based on bucket.
+- **New binary: `bin/toprank-content-calendar`.** Stdlib-only Python HTTP
+ server that reads `content-calendar.json` and renders a read-only calendar
+ view on `localhost:8323` (configurable). Auto-discovers the calendar at
+ `./.notfair/content-calendar.json` then `~/.notfair/content-calendar.json`,
+ falls forward through the next 9 ports if the default is in use, exits
+ cleanly on Ctrl+C. No pip install, no framework, no auth — loopback-only.
+- **Methodology reference: `seo/content-planner/references/planning-methodology.md`.**
+ Codifies the CTR-by-position curve, the five-bucket classification rubric,
+ the click-potential formula with seasonality factors, scheduling rules
+ (one post per week by default, P0s first, refreshes parallel to new posts),
+ and explicit failure modes (calendar padding, intent mismatch, treating GSC
+ impressions as third-party volume).
+
+### Changed — boundary cleanup against `/keyword-research`
+- `/keyword-research` description now scopes it explicitly to seed-driven
+ keyword discovery and points users at `/content-planner` for editorial
+ calendars built from their own GSC data. AGENTS.md row updated to match.
+
+### Notes
+- The calendar viewer is read-only by design — editing happens in the JSON
+ file, the viewer re-reads on every request. Loop: edit JSON → reload page.
+- The viewer auto-opens the browser on macOS/Windows and on Linux with
+ `$DISPLAY` set; pass `--no-open` to disable.
+
+---
+
## [0.20.0] — 2026-05-15
### Changed — `/content-writer` blog-post bar raised
diff --git a/VERSION b/VERSION
index 5a03fb73..88541566 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.20.0
+0.21.0
diff --git a/bin/toprank-content-calendar b/bin/toprank-content-calendar
new file mode 100755
index 00000000..7bdd2964
--- /dev/null
+++ b/bin/toprank-content-calendar
@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""toprank-content-calendar — local viewer for the NotFair content calendar.
+
+Reads {data_dir}/content-calendar.json (produced by the /content-planner skill)
+and serves a read-only HTML view on localhost. Stdlib only — no pip install.
+
+Usage:
+ toprank-content-calendar # auto-resolve calendar, port 8323
+ toprank-content-calendar --port 9000 # custom port
+ toprank-content-calendar --calendar PATH # explicit calendar JSON
+ toprank-content-calendar --no-open # don't auto-open the browser
+
+Stop with Ctrl+C.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import html
+import json
+import os
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+DEFAULT_PORT = 8323
+
+
+def resolve_calendar_path(explicit: str | None) -> Path:
+ """Find the calendar JSON. Explicit path wins; else project-local then global."""
+ if explicit:
+ return Path(explicit).expanduser().resolve()
+
+ project = Path.cwd() / ".notfair" / "content-calendar.json"
+ if project.is_file():
+ return project
+
+ home = Path.home() / ".notfair" / "content-calendar.json"
+ return home
+
+
+def load_calendar(path: Path) -> dict:
+ if not path.is_file():
+ return {
+ "_missing": True,
+ "_path": str(path),
+ }
+ try:
+ with path.open(encoding="utf-8") as fh:
+ data = json.load(fh)
+ except json.JSONDecodeError as exc:
+ return {"_error": f"Invalid JSON: {exc}", "_path": str(path)}
+ data["_path"] = str(path)
+ data["_loaded_at"] = _dt.datetime.utcnow().isoformat(timespec="seconds") + "Z"
+ return data
+
+
+def render_page(cal: dict) -> str:
+ if cal.get("_missing"):
+ return _page(
+ "Calendar not found",
+ f"""
+ <div class="empty">
+ <h1>No calendar yet</h1>
+ <p>Looked for <code>{html.escape(cal['_path'])}</code> and didn't find it.</p>
+ <p>Run the <code>/content-planner</code> skill in your agent to
+ generate one, then reload this page.</p>
+ </div>
+ """,
+ )
+ if cal.get("_error"):
+ return _page(
+ "Calendar error",
+ f"""
+ <div class="empty">
+ <h1>Couldn't read the calendar</h1>
+ <p><strong>File:</strong> <code>{html.escape(cal['_path'])}</code></p>
+ <p><strong>Error:</strong> {html.escape(cal['_error'])}</p>
+ </div>
+ """,
+ )
+
+ topics = cal.get("topics") or []
+ warnings = cal.get("warnings") or []
+ site = cal.get("site") or "(no site set)"
+ generated = cal.get("generated") or cal.get("_loaded_at") or ""
+ horizon = cal.get("horizonWeeks") or "?"
+ lookback = cal.get("lookbackDays") or "?"
+
+ topics_sorted = sorted(
+ topics,
+ key=lambda t: (
+ _date_key(t.get("scheduledDate")),
+ -_safe_num(t.get("gsc", {}).get("clickPotential", 0)),
+ ),
+ )
+
+ warning_html = ""
+ if warnings:
+ items = "".join(
+ f"<li>{html.escape(str(w))}</li>" for w in warnings
+ )
+ warning_html = f"""
+ <section class="warnings">
+ <h2>Warnings ({len(warnings)})</h2>
+ <ul>{items}</ul>
+ </section>
+ """
+
+ rows = "\n".join(_topic_row(t) for t in topics_sorted)
+ if not rows:
+ rows = '<tr><td colspan="7" class="empty-cell">No topics scheduled yet.</td></tr>'
+
+ body = f"""
+ <header>
+ <div class="brand">NotFair · Content Calendar</div>
+ <div class="meta">
+ <span>Site: <strong>{html.escape(str(site))}</strong></span>
+ <span>{lookback}d lookback · {horizon}w horizon</span>
+ <span>Generated: {html.escape(str(generated))}</span>
+ </div>
+ </header>
+
+ {warning_html}
+
+ <main>
+ <table>
+ <thead>
+ <tr>
+ <th>Date</th>
+ <th>Title</th>
+ <th>Primary keyword</th>
+ <th>Opportunity</th>
+ <th>Click potential</th>
+ <th>Priority</th>
+ <th>Status</th>
+ </tr>
+ </thead>
+ <tbody>{rows}</tbody>
+ </table>
+ </main>
+
+ <footer>
+ <code>{html.escape(cal['_path'])}</code>
+ &nbsp;·&nbsp; Read-only viewer. Edit the JSON and reload to update.
+ </footer>
+ """
+ return _page("NotFair Content Calendar", body)
+
+
+def _topic_row(t: dict) -> str:
+ gsc = t.get("gsc") or {}
+ cp = _safe_num(gsc.get("clickPotential"))
+ pri = (t.get("priority") or "").upper()
+ status = t.get("status") or "planned"
+ opp = t.get("opportunity") or "-"
+ return f"""
+ <tr class="row status-{html.escape(status)} priority-{html.escape(pri)}">
+ <td>{html.escape(t.get("scheduledDate", "—"))}</td>
+ <td>
+ <div class="title">{html.escape(t.get("title", "(untitled)"))}</div>
+ <div class="rationale">{html.escape(t.get("rationale", ""))}</div>
+ </td>
+ <td><code>{html.escape(t.get("primaryKeyword", ""))}</code></td>
+ <td><span class="bucket bucket-{html.escape(opp)}">{html.escape(opp)}</span></td>
+ <td class="num">{cp:,.0f}</td>
+ <td><span class="pri pri-{html.escape(pri)}">{html.escape(pri)}</span></td>
+ <td><span class="status status-{html.escape(status)}">{html.escape(status)}</span></td>
+ </tr>
+ """
+
+
+def _safe_num(v) -> float:
+ try:
+ return float(v)
+ except (TypeError, ValueError):
+ return 0.0
+
+
+def _date_key(d):
+ if not d:
+ return "9999-12-31"
+ return str(d)
+
+
+def _page(title: str, inner: str) -> str:
+ return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{html.escape(title)}</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+ :root {{
+ --bg: #fafaf7;
+ --ink: #1a1a1a;
+ --muted: #6b6b6b;
+ --accent: #ff6b35;
+ --line: #e5e3dd;
+ --row-alt: #f4f3ee;
+ }}
+ * {{ box-sizing: border-box; }}
+ body {{
+ margin: 0;
+ font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+ color: var(--ink);
+ background: var(--bg);
+ }}
+ header {{
+ padding: 20px 32px;
+ border-bottom: 1px solid var(--line);
+ background: white;
+ }}
+ .brand {{
+ font-size: 18px;
+ font-weight: 600;
+ letter-spacing: -0.01em;
+ }}
+ .brand::before {{
+ content: "";
+ display: inline-block;
+ width: 10px; height: 10px;
+ background: var(--accent);
+ border-radius: 50%;
+ margin-right: 8px;
+ transform: translateY(-1px);
+ }}
+ .meta {{
+ margin-top: 6px;
+ color: var(--muted);
+ font-size: 12px;
+ display: flex;
+ gap: 18px;
+ flex-wrap: wrap;
+ }}
+ main {{ padding: 24px 32px; }}
+ table {{
+ width: 100%;
+ border-collapse: collapse;
+ background: white;
+ border: 1px solid var(--line);
+ }}
+ th, td {{
+ padding: 12px 14px;
+ text-align: left;
+ border-bottom: 1px solid var(--line);
+ vertical-align: top;
+ }}
+ th {{
+ font-size: 11px;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--muted);
+ background: var(--row-alt);
+ }}
+ tbody tr:nth-child(even) {{ background: var(--row-alt); }}
+ .title {{ font-weight: 500; }}
+ .rationale {{ color: var(--muted); font-size: 12px; margin-top: 2px; }}
+ code {{
+ font: 12px/1 SFMono-Regular, Menlo, Consolas, monospace;
+ background: var(--row-alt);
+ padding: 2px 6px;
+ border-radius: 4px;
+ }}
+ .num {{ text-align: right; font-variant-numeric: tabular-nums; font-weight: 500; }}
+ .bucket, .pri, .status {{
+ display: inline-block;
+ padding: 2px 8px;
+ border-radius: 999px;
+ font-size: 11px;
+ font-weight: 500;
+ background: #ececec;
+ color: #444;
+ }}
+ .bucket-striking-distance {{ background: #fff1e6; color: #c4540a; }}
+ .bucket-gap {{ background: #e8f1ff; color: #1a56b8; }}
+ .bucket-ctr-underperformer {{ background: #fff8d6; color: #8a6d00; }}
+ .bucket-refresh {{ background: #ebe5ff; color: #5a3eb5; }}
+ .pri-P0 {{ background: #ffe0d6; color: #b8350f; }}
+ .pri-P1 {{ background: #fff1d6; color: #8a4d00; }}
+ .pri-P2 {{ background: #e8ece8; color: #4a4a4a; }}
+ .status-published {{ background: #d8f1d8; color: #1f6b1f; }}
+ .status-in-progress {{ background: #fff1d6; color: #8a4d00; }}
+ .status-planned {{ background: #e8ece8; color: #4a4a4a; }}
+ .warnings {{
+ margin: 24px 32px 0;
+ padding: 14px 18px;
+ background: #fff5e6;
+ border: 1px solid #f3d6a0;
+ border-radius: 6px;
+ }}
+ .warnings h2 {{ margin: 0 0 6px; font-size: 13px; color: #8a4d00; text-transform: uppercase; letter-spacing: 0.05em; }}
+ .warnings ul {{ margin: 0; padding-left: 20px; }}
+ .empty {{ padding: 60px 32px; text-align: center; color: var(--muted); }}
+ .empty h1 {{ font-size: 22px; color: var(--ink); }}
+ .empty-cell {{ padding: 40px; text-align: center; color: var(--muted); }}
+ footer {{
+ padding: 16px 32px;
+ color: var(--muted);
+ font-size: 12px;
+ border-top: 1px solid var(--line);
+ }}
+</style>
+</head>
+<body>
+{inner}
+</body>
+</html>"""
+
+
+def _build_handler(calendar_path: Path):
+ """Closure over calendar_path so we re-read on every request."""
+
+ class Handler(BaseHTTPRequestHandler):
+ def do_GET(self): # noqa: N802
+ if self.path in ("/", "/index.html"):
+ cal = load_calendar(calendar_path)
+ body = render_page(cal).encode("utf-8")
+ self.send_response(HTTPStatus.OK)
+ self.send_header("Content-Type", "text/html; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.send_header("Cache-Control", "no-store")
+ self.end_headers()
+ self.wfile.write(body)
+ return
+ if self.path == "/calendar.json":
+ cal = load_calendar(calendar_path)
+ body = json.dumps(cal, indent=2).encode("utf-8")
+ self.send_response(HTTPStatus.OK)
+ self.send_header("Content-Type", "application/json; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.send_header("Cache-Control", "no-store")
+ self.end_headers()
+ self.wfile.write(body)
+ return
+ self.send_error(HTTPStatus.NOT_FOUND, "Not Found")
+
+ def log_message(self, fmt, *args): # quieter than the default
+ sys.stderr.write(
+ "[%s] %s\n" % (self.log_date_time_string(), fmt % args)
+ )
+
+ return Handler
+
+
+def _port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+ s.settimeout(0.2)
+ try:
+ s.connect((host, port))
+ return True
+ except OSError:
+ return False
+
+
+def main(argv=None) -> int:
+ parser = argparse.ArgumentParser(prog="toprank-content-calendar")
+ parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+ parser.add_argument("--calendar", default=None,
+ help="Path to content-calendar.json (default: ./.notfair/... → ~/.notfair/...)")
+ parser.add_argument("--host", default="127.0.0.1",
+ help="Bind host (default 127.0.0.1; loopback only)")
+ parser.add_argument("--no-open", action="store_true",
+ help="Don't auto-open the browser")
+ args = parser.parse_args(argv)
+
+ calendar_path = resolve_calendar_path(args.calendar)
+
+ port = args.port
+ if _port_in_use(port, args.host):
+ # Try the next 9 ports rather than failing.
+ for candidate in range(port + 1, port + 10):
+ if not _port_in_use(candidate, args.host):
+ print(f"port {port} is in use; using {candidate}", file=sys.stderr)
+ port = candidate
+ break
+ else:
+ print(f"all ports {args.port}..{args.port + 9} are in use; specify --port", file=sys.stderr)
+ return 2
+
+ handler = _build_handler(calendar_path)
+ try:
+ server = ThreadingHTTPServer((args.host, port), handler)
+ except OSError as exc:
+ print(f"could not bind {args.host}:{port}: {exc}", file=sys.stderr)
+ return 2
+
+ url = f"http://{args.host}:{port}/"
+ print(f"NotFair content calendar — {url}")
+ print(f"Reading: {calendar_path}")
+ print("Ctrl+C to stop.")
+
+ if not args.no_open and os.environ.get("DISPLAY", "") or sys.platform == "darwin" or sys.platform == "win32":
+ # Open in a thread so we don't block startup if the browser command stalls.
+ threading.Thread(target=lambda: (time.sleep(0.2), webbrowser.open(url)), daemon=True).start()
+
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ print("\nstopping.", file=sys.stderr)
+ server.shutdown()
+ finally:
+ server.server_close()
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/seo/content-planner/SKILL.md b/seo/content-planner/SKILL.md
new file mode 100644
index 00000000..7533a25e
--- /dev/null
+++ b/seo/content-planner/SKILL.md
@@ -0,0 +1,223 @@
+---
+name: content-planner
+argument-hint: "<site URL or 'plan from GSC'>"
+description: >
+ GSC-driven content calendar. Pulls real Search Console data, finds the highest
+ click-potential opportunities (striking-distance queries at positions 5-20,
+ unanswered query intent, related-keyword expansions), and produces a dated,
+ prioritized content calendar — ready to hand to /content-writer. Use when the
+ user asks "plan my content", "what should I write next", "content calendar",
+ "content plan", "content roadmap", "editorial calendar", "what topics will
+ rank", "find quick-win SEO topics", "click-potential analysis", or "schedule
+ my SEO content".
+---
+
+# Content Planner
+
+You are NotFair's content strategist for the unfair SEO/Ads agent. Your job is
+**not** to brainstorm topic ideas — that's `keyword-research`. Your job is to
+mine the user's *actual* Search Console data, find the highest-click-potential
+opportunities for *this* site, and produce a dated calendar the user can publish
+against.
+
+The output is a structured `content-calendar.json` plus a Markdown summary. The
+JSON is consumed by the `toprank-content-calendar` viewer (a local server that
+renders the calendar in the browser).
+
+**Boundary with sibling skills:**
+- `keyword-research` — start from a seed, discover the keyword universe
+- `content-planner` (this skill) — start from GSC, prioritize *your* opportunities, schedule them
+- `content-writer` — take one planned topic and write the full post
+
+---
+
+## Step 1 — Setup (config + GSC)
+
+Read and follow `../seo-analysis/SKILL.md` Step 1 for GSC connection. The
+planner cannot run without GSC — if no GSC property is connected, **stop and
+walk the user through OAuth**. Don't invent data.
+
+Resolve `{data_dir}` the same way the Google Ads preamble does (`.notfair/` in
+the repo if `.notfair.json` exists, else `~/.notfair/`). The calendar lives at
+`{data_dir}/content-calendar.json`.
+
+---
+
+## Step 2 — Pull GSC opportunity data
+
+Pull a wide net once, filter in memory. Fewer round-trips, better correlation.
+
+For the chosen GSC property, fetch **last 90 days** of:
+
+1. **Query × Page** report — top 5000 rows. The Cartesian view is the only one
+ that lets you reason about *intent* (page is the answer surface, query is
+ the demand).
+2. **Page-only** report — top 1000 rows. Lets you spot pages that already
+ attract a lot of impressions but underperform CTR.
+3. **Country + device** breakdowns for the top 100 pages — needed for
+ prioritization when traffic concentrates in one segment.
+
+Cache the raw pull at `{data_dir}/gsc-cache.json` with a `fetchedAt` timestamp.
+Re-use the cache for 7 days — opportunities don't shift hourly.
+
+---
+
+## Step 3 — Classify opportunities
+
+For every (query, page) row, classify into one of these buckets. Discard rows
+that don't fit any bucket — noise.
+
+### A. Striking-distance queries (highest priority)
+- Position **5-20**, impressions **≥ 100/90d**, query is informational
+- The page already ranks; a content refresh or net-new post targeting the
+ exact intent can move it into the top 5
+
+### B. Unanswered intent (gaps)
+- Query is informational and **no page on the site ranks** (position > 20)
+- Query has search volume (use GSC impressions × position × 100 as a proxy if
+ you don't have third-party volume)
+- The site sells/operates in the topic area — verify against business context
+ in `{data_dir}/business-context.json` if present
+
+### C. CTR underperformers (refresh, not new content)
+- Position **1-10**, impressions **≥ 500/90d**, CTR **< 50% of expected** for
+ that position (use the standard CTR-by-position curve from
+ `references/planning-methodology.md`)
+- Output a *refresh* task, not a new post. Route to `meta-tags-optimizer` for
+ the title/description rewrite.
+
+### D. Related-keyword expansions
+- For each query in buckets A and B, derive 2-4 related queries (synonyms,
+ long-tails, "vs"/"alternative" variants, question forms). Cluster them with
+ the parent — they become H2 sections of the planned post, not separate
+ calendar entries.
+
+### E. Cannibalization warning (planning blocker)
+- Same query, **multiple pages on the same site rank** with > 20 impressions
+ each. Flag these — *don't* schedule new content until the user picks a
+ canonical winner. Route to `seo-analysis` for cannibalization fix.
+
+See `references/planning-methodology.md` for the full classification rubric
+and the click-potential formula.
+
+---
+
+## Step 4 — Score click potential
+
+For every candidate topic that survives Step 3, compute:
+
+```
+clickPotential = projectedImpressions × (targetCtrAtPosition3 - currentCtr)
+```
+
+Where:
+- `projectedImpressions` = 90d impressions × seasonality factor (default 1.0)
+- `targetCtrAtPosition3` = 0.10 (from the standard CTR curve; informational
+ posts cluster lower than transactional)
+- `currentCtr` = actual GSC CTR for this query, or 0 if the site doesn't rank
+
+Sort by `clickPotential` descending. Cap the calendar at 12 topics for a
+3-month plan unless the user asks for more — too many entries on the calendar
+becomes shelfware.
+
+---
+
+## Step 5 — Build the calendar
+
+Schedule one post per week, P0s first. Format every entry against this schema:
+
+```json
+{
+ "id": "<slug>",
+ "title": "<hook-driven title, ≤ 60 chars>",
+ "primaryKeyword": "<from GSC>",
+ "secondaryKeywords": ["<related cluster from Step 3D>"],
+ "intent": "informational|commercial",
+ "type": "blog|landing|refresh",
+ "opportunity": "striking-distance|gap|ctr-underperformer|related-expansion",
+ "scheduledDate": "<YYYY-MM-DD>",
+ "status": "planned",
+ "priority": "P0|P1|P2",
+ "gsc": {
+ "currentPosition": <number>,
+ "impressions90d": <number>,
+ "currentCtr": <number 0-1>,
+ "clickPotential": <number>
+ },
+ "rationale": "<one sentence: why this topic, why now>",
+ "writerPrompt": "<the exact prompt to paste into /content-writer when it's time to write>",
+ "refreshTarget": "<URL of existing page, only set when type=refresh>"
+}
+```
+
+Every title goes through the same hook-driven rules as `/content-writer` (see
+`seo/content-writer/references/content-writing.md` → "Title Hook Patterns").
+Don't ship a calendar with bare-keyword titles.
+
+Write the full calendar to `{data_dir}/content-calendar.json`:
+
+```json
+{
+ "generated": "<ISO 8601 UTC>",
+ "site": "<GSC property URL>",
+ "lookbackDays": 90,
+ "horizonWeeks": 12,
+ "topics": [ /* one per scheduled post */ ],
+ "warnings": [ /* cannibalization, missing business context, etc. */ ]
+}
+```
+
+Merge with an existing calendar instead of overwriting:
+- Topics already marked `in-progress` or `published` are **preserved as-is**
+- New planned topics are appended; duplicates by `primaryKeyword` are dropped
+ in favor of the existing entry
+
+---
+
+## Step 6 — Present + offer the viewer
+
+Print:
+
+1. A Markdown summary table (top 12 topics by click potential), with columns:
+ `Date | Title | Primary Keyword | Opportunity | Est. Clicks Gained | P`
+2. The path to the JSON: `{data_dir}/content-calendar.json`
+3. The viewer command, with the exact invocation:
+
+```
+toprank-content-calendar [--port 8323] [--calendar {data_dir}/content-calendar.json]
+```
+
+> Open the calendar in your browser:
+>
+> ```bash
+> ~/.claude/plugins/cache/nowork-studio/toprank/<version>/bin/toprank-content-calendar
+> ```
+>
+> (or run it from a clone of the toprank repo: `bin/toprank-content-calendar`.)
+> The viewer is read-only — it reads the JSON, renders a calendar view, and
+> exits cleanly on Ctrl+C. Edit the JSON to change scheduling; reload to see
+> updates.
+
+4. Conditional handoffs:
+ - **Cannibalization flagged** → offer `/seo-analysis` for the canonical-page fix first
+ - **CTR-underperformer entries present** → offer `/meta-tags-optimizer` for the title/description rewrite
+ - **First P0 topic ready to write now** → offer `/content-writer` with the pre-built `writerPrompt`
+
+---
+
+## Step 7 — Quality gate
+
+Refuse to ship the calendar if any of these are true:
+
+- [ ] GSC didn't connect → stop, prompt OAuth
+- [ ] < 50 (query, page) rows pulled → site has too little data, plan would be
+ speculation; tell the user so and stop
+- [ ] Any topic has a bare-keyword title → rewrite with a hook before writing
+ the JSON
+- [ ] Two scheduled topics share the same `primaryKeyword` → cannibalization
+ by your own plan; collapse or de-prioritize one
+- [ ] Cannibalization warning present and ignored in the calendar → block,
+ surface the warning, ask the user to confirm
+
+This skill writes one artifact and one summary. Don't add tangential analysis
+the user didn't ask for.
diff --git a/seo/content-planner/evals/evals.json b/seo/content-planner/evals/evals.json
new file mode 100644
index 00000000..3983c771
--- /dev/null
+++ b/seo/content-planner/evals/evals.json
@@ -0,0 +1,46 @@
+{
+ "skill_name": "content-planner",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Plan my next 90 days of content based on Search Console data. My site is example.com — a small B2B accounting SaaS for freelancers.",
+ "expected_output": "A GSC-driven content calendar with 8–12 prioritized topics, each tagged by opportunity bucket (striking-distance, gap, ctr-underperformer), scheduled across 12 weeks, with click-potential scores. The skill should write content-calendar.json to {data_dir} and tell the user how to launch the toprank-content-calendar viewer.",
+ "files": [],
+ "expectations": [
+ "Skill checks for GSC connection before doing anything else",
+ "Pulls 90-day query × page report, not just query-level",
+ "Classifies opportunities into the 5 buckets (striking-distance, gap, ctr-underperformer, related-expansion, cannibalization)",
+ "Computes clickPotential per topic using the documented formula",
+ "Every scheduled title uses a hook pattern (number, audience, contrarian, or outcome-promise) — no bare keyword titles",
+ "Writes content-calendar.json to {data_dir}/content-calendar.json with the documented schema",
+ "Tells the user the exact command to run the toprank-content-calendar viewer",
+ "Caps at 12 topics for a 90-day horizon unless user asks for more"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "I keep getting impressions for 'invoice software for freelancers' but I'm at position 14. What should I do?",
+ "expected_output": "Recognizes this as a striking-distance opportunity (position 5–20 with impressions), classifies it as bucket A, suggests scheduling a focused post with the related-keyword expansions clustered as H2s, and offers to hand off to /content-writer with the pre-built writerPrompt.",
+ "files": [],
+ "expectations": [
+ "Classifies as Bucket A: striking-distance",
+ "Identifies 2–4 related-keyword expansions (Bucket D) as secondary keywords",
+ "Computes clickPotential and surfaces the estimated additional clicks if the post reaches position 3",
+ "Generates a hook-driven title, not 'Invoice Software For Freelancers'",
+ "Hands off to /content-writer with a complete writerPrompt"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "My GSC shows 3 different pages on my site all ranking for 'time tracking tips' between positions 12 and 18. Should I write a new post?",
+ "expected_output": "Flags cannibalization (Bucket E). Refuses to schedule new content for that query. Routes user to /seo-analysis to pick a canonical page and consolidate.",
+ "files": [],
+ "expectations": [
+ "Identifies cannibalization explicitly",
+ "Does NOT schedule a new post for this query",
+ "Writes a warning entry into warnings[] in content-calendar.json",
+ "Routes user to /seo-analysis as the next step"
+ ]
+ }
+ ]
+}
diff --git a/seo/content-planner/references/planning-methodology.md b/seo/content-planner/references/planning-methodology.md
new file mode 100644
index 00000000..29b968ab
--- /dev/null
+++ b/seo/content-planner/references/planning-methodology.md
@@ -0,0 +1,158 @@
+# Content Planning Methodology
+
+Reference for `/content-planner`. The skill applies these rules; this file is
+the load-bearing logic, kept out of the SKILL.md so the prompt stays focused on
+workflow.
+
+---
+
+## CTR-by-position curve (informational intent)
+
+Use as the baseline for "expected CTR at position P". Numbers reflect ~2024–2026
+median informational CTR; transactional and brand queries skew higher.
+
+| Position | Expected CTR |
+|---|---|
+| 1 | 0.275 |
+| 2 | 0.160 |
+| 3 | 0.110 |
+| 4 | 0.080 |
+| 5 | 0.062 |
+| 6 | 0.050 |
+| 7 | 0.040 |
+| 8 | 0.033 |
+| 9 | 0.028 |
+| 10 | 0.024 |
+| 11–20 | 0.010 |
+| 21+ | < 0.005 |
+
+A query whose actual CTR is < 50% of the expected CTR at its average position
+is a **CTR underperformer** — title/meta rewrite candidate, not new content.
+
+---
+
+## Opportunity buckets — full rubric
+
+### Bucket A: Striking-distance queries
+Condition: average position in **[5.0, 20.0]**, impressions/90d ≥ 100, intent
+is informational (the query has "how", "what", "why", "best", "vs", "guide",
+or is a noun phrase Google answers with content).
+
+Action: schedule a new post or substantial refresh that targets the exact
+query intent.
+
+### Bucket B: Unanswered intent (gaps)
+Condition: query appears in GSC at position > 20 with impressions ≥ 50/90d,
+and no page on the site ranks for it in the top 20 (the query×page report
+shows only one weak page or none).
+
+Action: schedule a new post. Verify it fits the site's topical area against
+`business-context.json` if available — don't plan a gardening post for a SaaS
+analytics site just because GSC saw 200 impressions for "compost ratios".
+
+### Bucket C: CTR underperformers (refresh)
+Condition: position in **[1.0, 10.0]**, impressions/90d ≥ 500, actual CTR <
+0.5 × expected CTR at that position.
+
+Action: emit a **refresh** entry — type = "refresh", `refreshTarget` set to
+the URL. The writerPrompt should point at `/meta-tags-optimizer` first, then
+`/content-writer` for body refresh if needed.
+
+### Bucket D: Related-keyword expansions
+Not its own calendar entry. For each Bucket A/B parent, identify 2–4 related
+queries from the same `query × page` cluster — synonyms, long-tails, question
+forms, "[parent] vs X", "[parent] for [audience]". They become **secondary
+keywords** on the parent's calendar entry → become H2s in the eventual post.
+
+### Bucket E: Cannibalization warning
+Condition: same query appears at position < 20 for **two or more pages on the
+same site**, each with ≥ 20 impressions.
+
+Action: write a warning into `warnings[]`, do NOT schedule new content for
+this query. Route the user to `/seo-analysis` for the canonical-page fix.
+
+---
+
+## Click potential formula
+
+For each candidate topic that survives bucket classification:
+
+```
+projectedImpressions = impressions90d × seasonalityFactor
+targetCtrAtPosition3 = 0.110 # from CTR curve, informational baseline
+currentExpectedClicks = impressions90d × currentCtr
+projectedClicks = projectedImpressions × targetCtrAtPosition3
+clickPotential = projectedClicks − currentExpectedClicks
+```
+
+`seasonalityFactor` defaults to 1.0. If the query is clearly seasonal (e.g.
+"black friday", "tax filing", "summer camp"), adjust the next 90 days:
+
+| Pattern | factor (next 90d) |
+|---|---|
+| Peak season ahead | 2.0 |
+| Mid-season | 1.0 |
+| Off-season trailing | 0.4 |
+
+Tie-breakers when click potential is within 10%:
+1. Lower content-production cost (refresh > new post)
+2. Higher intent-to-revenue alignment (commercial > pure informational)
+3. Closer to topical authority the site already has
+
+---
+
+## Scheduling rules
+
+- **One post per week** by default. The agent should not pack 12 posts into 4
+ weeks just because the data supports it — production capacity is the real
+ bottleneck, and SEO compounds over months.
+- **P0 first** — the top 4 by click potential are P0, the next 4 are P1, the
+ rest P2. Schedule P0s in weeks 1–4.
+- **Refresh entries can run in parallel** with new posts (they're cheaper to
+ ship) — schedule them as same-week siblings, not consuming a weekly slot.
+- **Skip weeks** where the user has external deadlines if they tell you about
+ them — don't fight the user's actual calendar.
+
+---
+
+## Click-potential output (what the JSON has to carry)
+
+For every topic in `content-calendar.json`:
+
+```json
+"gsc": {
+ "currentPosition": 9.4,
+ "impressions90d": 2480,
+ "currentCtr": 0.018,
+ "clickPotential": 228
+}
+```
+
+`clickPotential` is the **estimated additional monthly clicks** if the topic
+hits position 3. It's an upper-bound estimate, not a guarantee — communicate
+that clearly in the rationale field.
+
+---
+
+## Title-hook reuse
+
+Every planned title goes through the four `/content-writer` hook patterns:
+number + specificity, audience-named guide, contrarian myth-break, outcome
+promise + proof. Reject bare-keyword titles ("Facebook SEO Optimization") at
+the planning stage — fixing it post-write costs more.
+
+---
+
+## Failure modes to avoid
+
+- **Padding the calendar** with low-clickPotential topics to hit a count.
+ Better to ship 6 strong topics than 12 mediocre ones.
+- **Ignoring intent mismatch** between bucket A queries and the site's actual
+ business. If GSC sees a query but the site can't credibly answer it,
+ skip it.
+- **Treating impressions as volume** for brand-new queries. GSC impressions
+ reflect what *you* served — a query with 12 impressions could be a 12k/mo
+ query you barely show for. When third-party volume isn't available, note
+ the uncertainty in the rationale.
+- **Scheduling refreshes for pages that are already strong** (position < 3,
+ CTR within 80% of expected). Don't break what works.
diff --git a/seo/keyword-research/SKILL.md b/seo/keyword-research/SKILL.md
index 28d6d474..c408170b 100644
--- a/seo/keyword-research/SKILL.md
+++ b/seo/keyword-research/SKILL.md
@@ -2,12 +2,14 @@
name: keyword-research
argument-hint: "<topic, niche, or seed keyword>"
description: >
- Discover, analyze, and prioritize keywords for SEO and GEO content strategies.
- Identifies high-value opportunities based on search volume, competition,
- intent, and business relevance. Generates topic clusters and content calendars.
- Use when asked to "find keywords", "keyword research", "what should I write
- about", "keyword analysis", "find me topics to write", "search volume",
- "keyword difficulty", "content ideas", or any keyword discovery task.
+ Discover, analyze, and prioritize keywords for SEO and GEO content strategies
+ from a seed keyword or niche. Identifies high-value opportunities based on
+ search volume, competition, intent, and business relevance. Generates topic
+ clusters. For building a dated editorial calendar from your own Search
+ Console data, use `content-planner` instead — this skill is seed-driven
+ keyword discovery, not calendar scheduling. Use when asked to "find
+ keywords", "keyword research", "keyword analysis", "search volume", "keyword
+ difficulty", "content ideas from a seed", or any keyword discovery task.
---
# Keyword Research