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.jsonindex 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.jsonindex 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.mdindex 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.mdindex 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 raiseddiff --git a/VERSION b/VERSIONindex 5a03fb73..88541566 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.20.0+0.21.0diff --git a/bin/toprank-content-calendar b/bin/toprank-content-calendarnew file mode 100755index 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>+ · 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 28d6d474..c408170b 100644--- a/seo/keyword-research/SKILL.md+++ b/seo/keyword-research/SKILL.md@@ -2,12 +2,14 @@name: keyword-researchargument-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