rsc-universal 0.1.1

package/skills/marketing/scripts/seo_audit.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+SEO audit script (no API required) — free companion to references/seo-geo.md.
+
+Fetches a URL with the Python 3 standard library only (no pip install, no API key) and reports:
+title + length, meta description + length, OG-tag presence, the <h1>, JSON-LD block count, load
+time, whether robots.txt exists and which AI bots it names, and whether sitemap.xml is served.
+
+Usage: python3 scripts/seo_audit.py "https://example.com"
+
+This is the free, no-API auditor. For keyword research, SERP analysis, backlinks, domain
+overview, and competitor gaps you need a paid data provider (e.g. DataForSEO) — see
+references/seo-geo.md for when to reach for those.
+"""
+import argparse
+import urllib.request
+import urllib.parse
+import re
+import time
+import sys
+
+
+def fetch_url(url: str, timeout: int = 30) -> tuple:
+    """Fetch URL and return (content, headers, load_time)"""
+    try:
+        start = time.time()
+        req = urllib.request.Request(url, headers={"User-Agent": "SEO-Audit/1.0"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            content = resp.read().decode("utf-8", errors="ignore")
+            headers = dict(resp.headers)
+            load_time = time.time() - start
+            return content, headers, load_time
+    except Exception as e:
+        return None, None, None
+
+
+def extract_meta(html: str) -> dict:
+    """Extract meta tags from HTML"""
+    result = {}
+    
+    # Title
+    title_match = re.search(r"<title[^>]*>([^<]+)</title>", html, re.I)
+    result["title"] = title_match.group(1).strip() if title_match else None
+    
+    # Meta description
+    desc_match = re.search(r'<meta[^>]+name=["\']description["\'][^>]+content=["\']([^"\']+)["\']', html, re.I)
+    if not desc_match:
+        desc_match = re.search(r'<meta[^>]+content=["\']([^"\']+)["\'][^>]+name=["\']description["\']', html, re.I)
+    result["description"] = desc_match.group(1).strip() if desc_match else None
+    
+    # OG tags
+    og_match = re.search(r'<meta[^>]+property=["\']og:title["\']', html, re.I)
+    result["og_tags"] = bool(og_match)
+    
+    # JSON-LD
+    jsonld_count = len(re.findall(r'application/ld\+json', html, re.I))
+    result["jsonld_count"] = jsonld_count
+    
+    # H1 (handle inline tags like <br>)
+    h1_match = re.search(r"<h1[^>]*>(.*?)</h1>", html, re.I | re.DOTALL)
+    if h1_match:
+        h1_text = re.sub(r"<[^>]+>", " ", h1_match.group(1))  # Remove inner tags
+        h1_text = re.sub(r"\s+", " ", h1_text).strip()  # Normalize whitespace
+        result["h1"] = h1_text[:100]
+    else:
+        result["h1"] = None
+    
+    return result
+
+
+def check_robots(url: str) -> dict:
+    """Check robots.txt"""
+    parsed = urllib.parse.urlparse(url)
+    robots_url = f"{parsed.scheme}://{parsed.netloc}/robots.txt"
+    content, _, _ = fetch_url(robots_url)
+    
+    result = {"exists": False, "ai_bots": []}
+    if content:
+        result["exists"] = True
+        # 2026 landscape: retrieval/user bots earn citations; GPTBot/ClaudeBot are training crawlers.
+        ai_bots = [
+            "OAI-SearchBot", "ChatGPT-User", "GPTBot",
+            "PerplexityBot", "Perplexity-User",
+            "Claude-SearchBot", "Claude-User", "ClaudeBot", "anthropic-ai",
+            "Google-Extended",
+        ]
+        for bot in ai_bots:
+            if bot.lower() in content.lower():
+                result["ai_bots"].append(bot)
+    return result
+
+
+def check_sitemap(url: str) -> bool:
+    """Check if sitemap.xml exists"""
+    parsed = urllib.parse.urlparse(url)
+    sitemap_url = f"{parsed.scheme}://{parsed.netloc}/sitemap.xml"
+    content, _, _ = fetch_url(sitemap_url)
+    if not content:
+        return False
+    # Check for common sitemap indicators
+    return "<urlset" in content.lower() or "<sitemapindex" in content.lower() or "<?xml" in content.lower()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="SEO audit")
+    parser.add_argument("url", help="URL to audit")
+    args = parser.parse_args()
+    
+    url = args.url
+    if not url.startswith("http"):
+        url = f"https://{url}"
+    
+    print(f"=== SEO Audit: {url} ===")
+    print()
+    
+    # Fetch page
+    content, headers, load_time = fetch_url(url)
+    if not content:
+        print("error: Could not fetch URL")
+        sys.exit(1)
+    
+    # Meta tags
+    print("## Meta Tags")
+    meta = extract_meta(content)
+    title = meta["title"]
+    print(f"title: {title[:60] if title else 'MISSING'}{'...' if title and len(title) > 60 else ''}")
+    print(f"title_length: {len(title) if title else 0} chars")
+    desc = meta["description"]
+    print(f"description: {desc[:80] if desc else 'MISSING'}{'...' if desc and len(desc) > 80 else ''}")
+    print(f"description_length: {len(desc) if desc else 0} chars")
+    print(f"og_tags: {'yes' if meta['og_tags'] else 'no'}")
+    print(f"h1: {meta['h1'] if meta['h1'] else 'MISSING'}")
+    print()
+    
+    # Schema
+    print("## Schema Markup")
+    print(f"json_ld_blocks: {meta['jsonld_count']}")
+    print()
+    
+    # Performance
+    print("## Performance")
+    print(f"load_time: {load_time:.2f}s")
+    print(f"status: {'good' if load_time < 3 else 'slow'}")
+    print()
+    
+    # robots.txt
+    print("## robots.txt")
+    robots = check_robots(url)
+    print(f"exists: {'yes' if robots['exists'] else 'no'}")
+    if robots["ai_bots"]:
+        print(f"ai_bots_mentioned: {', '.join(robots['ai_bots'])}")
+    else:
+        print("ai_bots_mentioned: none")
+    print()
+    
+    # Sitemap
+    print("## Sitemap")
+    has_sitemap = check_sitemap(url)
+    print(f"sitemap_xml: {'yes' if has_sitemap else 'no'}")
+    print()
+    
+    print("=== Audit Complete ===")
+
+
+if __name__ == "__main__":
+    main()

package/skills/marketing/scripts/verify.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+#
+# verify.sh — copy QA gate for the `marketing` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free grep checks over the copy in your project:
+#     1. Ban-list hype words (revolutionary, game-changer, cutting-edge, world-class,
+#        seamless, unlock, supercharge, "Excited to share", "not just X", "In today's …").
+#     2. Generic / un-earned CTAs ("Learn more", "Click here", "Submit").
+#     3. Weasel words / vague benefits (very, really, world-class, "best-in-class",
+#        "thousands trust", "industry-leading", "robust solution").
+#     4. Passive-voice flags (heuristic: "is/are/was/were/be/been + past participle").
+#     5. Structure heuristics on HTML/JSX/MD pages: missing <h1>, more than one <h1>,
+#        no obvious CTA verb.
+#     5b. JSON-LD/schema presence: landing-style pages (<section>) with no
+#         application/ld+json get a GEO/SEO warning (detect-or-skip; see seo-geo.md).
+#     6. Brand-grounding presence: warns if no 02-DOCS/wiki/brand/ study is found.
+#
+#   Every finding is a WARNING by default (copy is judgement, not pass/fail).
+#   Use --strict to turn warnings into a failure (exit 1) so CI can gate on it.
+#   A missing tool is reported yellow and SKIPPED — never a failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for copy in *.{md,mdx,html,tsx,jsx,vue,svelte,txt}
+#   ./verify.sh --path src      # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict
+#   1  a real failure, or --strict with any warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, arrays are
+# initialised and only expanded when non-empty under `set -u`.
+
+set -euo pipefail
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..34), stripping the leading "# "
+  sed -n '2,34p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# count_lines <file>: number of non-empty-aware lines in a file; 0 if missing/empty.
+# Robust across BSD/GNU: wc -l can print leading spaces, so strip non-digits.
+count_lines() {
+  if [ -s "$1" ]; then
+    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
+  else
+    printf '0'
+  fi
+}
+
+# Copy-bearing extensions are restricted via glob flags in search() below.
+# JSX/TSX/Vue/Svelte/HTML carry on-page copy; md/mdx/txt carry content + references.
+
+# search <pattern>: case-insensitive, whole-tree, copy files only. Prints file:line:match.
+# Uses ripgrep if present (faster, respects .gitignore), else portable grep -rnE.
+# Never errors out the script: a no-match grep returns 1, which we swallow.
+search() {
+  pattern="$1"
+  if have rg; then
+    rg -n --no-heading -i -e "$pattern" \
+       -g '*.md' -g '*.mdx' -g '*.html' -g '*.htm' \
+       -g '*.tsx' -g '*.jsx' -g '*.vue' -g '*.svelte' -g '*.txt' \
+       "$SCAN_PATH" 2>/dev/null || true
+  else
+    # --include globs restrict to copy files by filename (BSD + GNU grep);
+    # this avoids matching the extension against the file:line:content output.
+    grep -rniE \
+      --include='*.md' --include='*.mdx' --include='*.html' --include='*.htm' \
+      --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
+      --include='*.txt' \
+      -e "$pattern" "$SCAN_PATH" 2>/dev/null || true
+  fi
+}
+
+# report <label> <pattern>: warn (with up to 5 example lines) if the pattern is found.
+report() {
+  label="$1"; pattern="$2"
+  hits="$(search "$pattern")"
+  if [ -n "$hits" ]; then
+    warn "$label:"
+    printf '%s\n' "$hits" | head -n 5 | sed 's/^/        /'
+  else
+    ok "no $label"
+  fi
+}
+
+# --- ensure we have a searcher ----------------------------------------------
+if ! have rg && ! have grep; then
+  skip "neither ripgrep nor grep found — cannot scan; install ripgrep or grep"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Scanning copy under: %s\n\n' "$SCAN_PATH"
+
+# --- 1. ban-list hype words -------------------------------------------------
+report "ban-list hype words" \
+  'revolutionary|game.?changer|cutting.edge|world.class|next.level|seamless|supercharge|elevate|unlock|excited to share|not just |in today.?s (landscape|fast.paced|competitive|digital)'
+
+# --- 2. generic / un-earned CTAs --------------------------------------------
+report "generic CTAs (use a value verb instead)" \
+  '>[[:space:]]*(learn more|click here|submit|read more|find out more)[[:space:]]*<|"(learn more|click here|submit)"'
+
+# --- 3. weasel words / vague benefits ---------------------------------------
+report "weasel words / vague benefits (replace with a number or mechanism)" \
+  'industry.leading|best.in.class|robust solution|powerful (platform|solution|tool)|thousands (of teams )?(trust|use)|trusted by thousands|very (fast|easy|powerful|simple)|really (fast|easy|good)'
+
+# --- 4. passive-voice flags (heuristic) -------------------------------------
+report "possible passive voice (prefer active: who does what)" \
+  '\b(is|are|was|were|be|been|being)\b +([a-z]+ed|built|made|done|driven|shipped|run|known|seen|given)\b'
+
+# --- 5. structure heuristics (per page) -------------------------------------
+# Subshells in a pipe can't mutate warn_count under bash 3.2, so each per-file
+# loop appends one line per finding to a temp file, then we add the line count
+# to warn_count in the parent shell. Each scan runs exactly once.
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+H1_HITS="$TMPDIR_V/h1"; CTA_HITS="$TMPDIR_V/cta"
+: > "$H1_HITS"; : > "$CTA_HITS"
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# Duplicate <h1> in HTML/JSX-ish pages (should be exactly one per page).
+h1_files="$(search '<h1' | sed 's/:.*//' | sort -u)"
+if [ -z "$h1_files" ]; then
+  ok "h1 check: no HTML/JSX pages with <h1> to inspect"
+else
+  printf '%s\n' "$h1_files" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    case "$f" in *.tsx|*.jsx|*.html|*.htm|*.vue|*.svelte) : ;; *) continue ;; esac
+    # count occurrences, not matching lines: two <h1> on one line must still trip this.
+    n="$(grep -o '<h1' "$f" 2>/dev/null | wc -l | tr -dc '0-9')"
+    [ -z "$n" ] && n=0
+    if [ "$n" -gt 1 ]; then
+      printf '%s[warn]%s multiple <h1> in one page (should be exactly one): %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$H1_HITS"
+    fi
+  done
+  n_h1="$(count_lines "$H1_HITS")"
+  if [ "$n_h1" -gt 0 ]; then warn_count=$((warn_count + n_h1)); else ok "h1 check: exactly one <h1> per page"; fi
+fi
+
+# Landing-style pages (have <section>) with no clear CTA verb anywhere.
+cta_verbs='start free|get started|book a demo|see (it|a) (live|demo)|get my|try it|sign up|join the'
+pages="$(search '<section' | sed 's/:.*//' | sort -u)"
+if [ -z "$pages" ]; then
+  ok "CTA check: no landing-style pages (<section>) to inspect"
+else
+  printf '%s\n' "$pages" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if ! grep -iE "$cta_verbs" "$f" >/dev/null 2>&1; then
+      printf '%s[warn]%s page has <section> markup but no clear CTA verb: %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$CTA_HITS"
+    fi
+  done
+  n_cta="$(count_lines "$CTA_HITS")"
+  if [ "$n_cta" -gt 0 ]; then warn_count=$((warn_count + n_cta)); else ok "CTA check: every landing page has a CTA verb"; fi
+fi
+
+# --- 5b. JSON-LD / schema presence on landing-style pages (GEO signal) -------
+# Detect-or-skip: only judges pages that already look like landing pages (<section>).
+# A landing page with no application/ld+json is a missed GEO/SEO opportunity (warn),
+# not a failure. Pages without <section> are not inspected (skip), so non-web repos
+# never trip this. See references/seo-geo.md for the schema templates.
+SCHEMA_HITS="$TMPDIR_V/schema"; : > "$SCHEMA_HITS"
+schema_pages="$(search '<section' | sed 's/:.*//' | sort -u)"
+if [ -z "$schema_pages" ]; then
+  skip "JSON-LD check: no landing-style pages (<section>) to inspect"
+else
+  printf '%s\n' "$schema_pages" | while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if ! grep -iE 'application/ld\+json' "$f" >/dev/null 2>&1; then
+      printf '%s[warn]%s landing page has no JSON-LD schema (add FAQPage/Article — see seo-geo.md): %s\n' "$YELLOW" "$NC" "$f"
+      printf '%s\n' "$f" >> "$SCHEMA_HITS"
+    fi
+  done
+  n_schema="$(count_lines "$SCHEMA_HITS")"
+  if [ "$n_schema" -gt 0 ]; then warn_count=$((warn_count + n_schema)); else ok "JSON-LD check: every landing page carries schema markup"; fi
+fi
+
+# --- 6. brand-grounding presence --------------------------------------------
+if [ -d "$SCAN_PATH/02-DOCS/wiki/brand" ] || [ -d "02-DOCS/wiki/brand" ]; then
+  ok "brand study found under 02-DOCS/wiki/brand/"
+else
+  warn "no brand study at 02-DOCS/wiki/brand/ — run the brand-grounding gate before shipping copy"
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: every finding above is a heuristic WARNING — copy is judgement, not pass/fail.
+Review each, then fix or justify. Re-run with --strict to gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/medium-publishing/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: medium-publishing
+description: "Use when getting a finished article onto Medium correctly — choosing profile vs publication, cross-posting from your own site without an SEO duplicate-content hit, the import tool, the 5-tag limit, and Medium's pseudo-Markdown formatting gotchas. Triggers: 'cross-post to Medium', 'republish on Medium with a canonical link', 'submit my draft to a Medium publication', 'why are my code blocks broken on Medium', 'can I still automate Medium via the API', 'the Medium import tool failed with a 403', 'importar mi artículo a Medium sin penalización SEO', 'publicar a Medium amb enllaç canònic'. NOT drafting, structuring, or headlining the article itself (that is medium-writing)."
+tags: [medium, publishing, cross-posting, canonical-url, seo, import-tool]
+recommends: [medium-writing, medium-strategy, seo-geo, social-publisher]
+origin: risco
+---
+
+# Medium publishing
+
+Land a finished article on Medium with correct metadata: right destination, no duplicate-content penalty, valid tags, intact formatting. Writing the article is `../medium-writing/SKILL.md`; deciding when/where/how-often to publish and how it grows is `../medium-strategy/SKILL.md`. This skill is only the mechanics of getting bytes onto the platform with the right metadata attached.
+
+## Reality check — read this first (2025-2026)
+
+**The Medium API is closed to new integrations.** As of 2025-01-01 Medium issues no new integration tokens and accepts no new integrations; only tokens minted before that date still work. Why it matters: any plan that starts with "register a Medium API token and automate it" is dead on arrival for anyone who didn't already have one. Integration platforms confirm this — the Medium app in Make is marked legacy, and n8n's Medium credentials can no longer be newly configured.
+
+So the default publishing path is **web editor + import tool + canonical link**, done through the UI. Treat the API as a legacy escape hatch (last section), not the plan.
+
+Do not promise API automation. If the user asks "can I get a token and automate this?", the honest answer is almost always no — explain why and route them to the import path below.
+
+## Decision table — pick your path
+
+Branch on where the article already lives and what you control:
+
+| Situation | Path | Canonical handling |
+|---|---|---|
+| Article only ever lives on Medium | Write or paste natively in the web editor, publish | None needed — Medium *is* the original |
+| Article already published on your own site/blog | **Import tool**: paste the original URL | Auto-set to that URL + auto-backdated |
+| Import tool fails (403/404/timeout) | Native paste, then set canonical by hand | Manual: Story settings -> Customize canonical link |
+| You hold a pre-2025 API token and want automation | Legacy `POST /v1/users/{id}/posts` | `canonicalUrl` field in the request body |
+| Destination is a publication you write for | Submit draft to the publication | Same as above; submission is separate from canonical |
+
+When in doubt and the piece exists elsewhere, prefer the import tool — it gets canonical *and* backdate right in one step.
+
+## Cross-post without an SEO penalty (the core job)
+
+When the article already lives on your own site, you must tell search engines the original is canonical, or Google sees two copies and may credit Medium or neither. Two mechanisms, in order of preference:
+
+**1. Import tool (preferred).** Pasting the original URL into Medium's import field does three things at once:
+- imports the rendered content into a new draft,
+- sets the story's canonical link to that original URL (search engines keep crediting your site),
+- backdates the Medium post to your original publish date by reading the page's `article:published_time` meta tag.
+
+Path: New story -> import icon (or `medium.com/p/import`) -> paste the original URL -> Import. Review the draft, then publish.
+
+**2. Manual canonical (fallback).** If you drafted natively or the import failed, set it per story: **More options (•••) -> Story settings -> advanced/edit -> "Customize canonical link"**, paste the origin URL, then publish. This is per-story; there is no global default.
+
+```text
+Bad:  Open a new Medium story, paste the article body, hit Publish.
+      -> Duplicate content, no canonical, wrong date. Your own page now
+         competes with Medium for its own ranking.
+Good: Use the import tool (canonical + backdate set automatically), or if
+      you paste natively, set "Customize canonical link" to the origin URL
+      BEFORE publishing.
+```
+
+The canonical must point to the **origin** (your site), not to the Medium URL. The whole point is that your site keeps the SEO credit.
+
+## When the import fails
+
+The importer is an HTTP crawler hitting your URL; failures are crawl failures, not Medium bugs. Map the symptom to the cause:
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| 400 / 404 | URL unreachable, redirected, or page metadata missing | Verify the URL loads anonymously; ensure `<link rel="canonical">` and `article:published_time` exist |
+| 403 | Bot-blocking (WAF, Cloudflare challenge, login wall) | Serve a clean static copy the crawler can reach, or paste natively + set canonical manually |
+| 500 / 504 | Crawl timeout — heavy JS, slow page | Provide a lightweight static HTML version of the article |
+| Imports but body is empty/garbled | Content rendered client-side only (JS) | Same: static HTML with the content in the initial markup |
+
+The reliable workaround for stubborn pages: publish a minimal static HTML page of the article carrying `<link rel="canonical">` and `<meta property="article:published_time">`, import *that*, then you can take it down. Full recipe and the complete error -> cause -> fix matrix are in `references/cross-post-and-canonical.md`.
+
+## Tags & formatting at publish time
+
+**Five tags, exactly.** Medium allows up to 5 tags per story; they drive topic distribution and discovery, so they are functional metadata, not decoration. Pick 5 real topics readers browse, not keyword-stuffed variants.
+
+```text
+Bad:  tags: react, reactjs, react.js, react-hooks, javascript, frontend, webdev  (7, redundant)
+Good: tags: react, javascript, web-development, frontend, programming           (5, distinct surfaces)
+```
+
+**Medium is NOT a full Markdown editor.** The web editor interprets a *subset* of Markdown shortcuts as you type, and silently ignores the rest. Know the gotchas:
+
+- Headings (`#`, `##`), blockquote (`>`), emphasis (`*`/`_`), ordered/bulleted lists (`1.`, `*`), and the `---` separator work as you type.
+- **No Markdown tables.** Pasting a `| col | col |` table renders as plain text. Restructure into a list, or insert the table as an image.
+- **Code blocks**: type triple-backtick then content, or `Cmd/Ctrl + Option + 6`. Do not rely on indentation-based code.
+- **Embeds**: paste a bare URL on its own line (YouTube, gist, tweet) and Medium expands it. A URL inside a sentence stays a plain link.
+
+```text
+Bad:  Paste a raw Markdown table and assume it renders as a table.
+Good: Convert the table to a labeled list, or screenshot/export it as an
+      image and insert the image. Reserve real tables for the original site.
+```
+
+(The legacy API's `contentFormat: markdown` is more permissive than the web editor — but that path is closed to new users.)
+
+## Publications
+
+Two outcomes, often confused:
+
+- **Self-publish** puts the story on your own profile immediately.
+- **Submit to a publication** routes the draft to that publication's editors. It stays **pending** — not live — until an editor publishes it, and you must already be an accepted writer for that publication. Submitting does not auto-publish.
+
+Why it sits pending: a publication is editorially controlled; submission is a request, not a publish action. If you're not yet a writer there, request access first; submitting otherwise goes nowhere.
+
+## Legacy API — only if you hold a pre-2025 token
+
+Do **not** attempt to register a new token; it will be refused. This applies *only* to tokens minted before 2025-01-01.
+
+```bash
+# 1. Resolve your user id
+curl -s -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  https://api.medium.com/v1/me
+# -> { "data": { "id": "<userId>", ... } }
+
+# 2. Create a post with canonical + publish status
+curl -s -X POST \
+  -H "Authorization: Bearer $MEDIUM_TOKEN" \
+  -H "Content-Type: application/json" \
+  https://api.medium.com/v1/users/<userId>/posts \
+  -d '{
+    "title": "My title",
+    "contentFormat": "markdown",
+    "content": "# My title\n\nBody...",
+    "canonicalUrl": "https://mysite.com/original-post",
+    "tags": ["react", "javascript", "web-development"],
+    "publishStatus": "draft"
+  }'
+```
+
+`publishStatus` is `public` | `draft` | `unlisted`. For a publication, POST to `/v1/publications/{publicationId}/posts`; a `draft` there stays pending an editor. Full field reference and response shapes are in `references/legacy-api.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Paste a copy of your own article, publish with no canonical | Duplicate content; your site loses ranking credit | Import tool, or set canonical to the origin before publishing |
+| Plan an automated pipeline on a freshly registered API token | No new tokens since 2025-01-01; it will never authorize | Use the import tool / web editor; reserve API only for pre-2025 tokens |
+| Cram 6+ tags or keyword-stuff the tag slots | Max is 5; redundant tags waste distribution surface | Pick 5 distinct topics readers actually browse |
+| Paste a raw Markdown table and assume it renders | The web editor has no table support | List or image; keep the table on the origin site |
+| Submit to a publication and assume it goes live | Submission is pending until an editor acts; needs writer access | Self-publish for instant, or submit only as an accepted writer |
+| Set canonical to the Medium URL | Points credit at Medium, defeating the cross-post | Canonical must point to your origin site |
+| Native paste of a backdated piece without checking the date | Manual paste does not backdate; canonical/date mismatch | Use import (auto-backdate) or set the date deliberately |
+
+## Post-publish verify checklist
+
+A correctly cross-posted article passes all of these:
+
+- [ ] Canonical link present **and pointing to the origin** (your site), not the Medium URL.
+- [ ] Publish date matches the original (backdated correctly if cross-posted).
+- [ ] 5 tags or fewer, all distinct real topics.
+- [ ] Code blocks render as code; embeds expanded; no broken Markdown tables.
+- [ ] Correct destination — your profile, or the intended publication (and it actually went live, not stuck pending).

package/skills/medium-publishing/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — medium-publishing
+
+These cases check routing and capability for the `medium-publishing` skill. Run them through the skill-eval harness: each `should_trigger` prompt should fire this skill; each `should_not_trigger` prompt should route to the named sibling instead (`medium-writing` for the article's craft, `medium-strategy` for growth/cadence, `social-publisher` for multi-platform scheduling, `seo-geo` for site-wide SEO). The `capability` case is rubric-graded — feed the scenario to the skill and check the response covers every `must_include` item (closed API, import-tool-first, auto canonical + backdate, manual canonical fallback, 5-tag limit, formatting gotchas, and no false promise of API automation). There is no `verify.sh`: this is a process/operational skill whose output is an article published on a third-party platform via UI steps, so rigor lives in this capability rubric and the post-publish checklist in SKILL.md.

package/skills/medium-publishing/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: medium-publishing
+
+should_trigger:
+  - prompt: "Cross-post my blog post to Medium without hurting my own site's SEO."
+    why: Core canonical/import case — getting a piece that lives on the user's site onto Medium without duplicate-content penalty.
+  - prompt: "The Medium import tool failed with a 403 on my article — how do I get it in?"
+    why: Non-obvious failure-mode trigger; the answer is the bot-block/static-HTML workaround, squarely this skill's mechanics.
+  - prompt: "Can I still get a Medium API token to auto-publish my posts from a script?"
+    why: Must surface the closed-API reality (no new tokens since 2025-01-01) and route to the import path. Non-obvious — the user assumes automation is possible.
+  - prompt: "Submit my draft to the Better Programming publication on Medium."
+    why: Publication submission path — self-publish vs pending-until-editor distinction.
+  - prompt: "Why do my code blocks and tables look broken after I published on Medium?"
+    why: Publish-time formatting gotchas (pseudo-Markdown editor, no tables, code-block method).
+  - prompt: "Importar mi artículo de mi web a Medium con enlace canónico para no duplicar contenido."
+    why: Spanish trigger for the canonical cross-post mechanic.
+  - prompt: "Republish this on Medium with a canonical link pointing back to my original."
+    why: Direct canonical-link request — the manual fallback or import path.
+
+should_not_trigger:
+  - prompt: "Write me a compelling Medium article about distributed systems and fix my intro."
+    route_to: medium-writing
+    why: Drafting, structuring, and headlining the piece is the writing craft, not the publish mechanics.
+  - prompt: "How often should I post on Medium and how do I grow my following and Partner Program earnings?"
+    route_to: medium-strategy
+    why: Cadence, audience growth, and monetization are distribution strategy, not getting one article onto the platform.
+  - prompt: "Schedule this same post across LinkedIn, X, and Medium from one content queue."
+    route_to: social-publisher
+    why: Cross-channel scheduling across many platforms is the multi-platform publisher, not Medium-specific mechanics.
+  - prompt: "Audit my whole site's canonical tags and fix duplicate-content issues across all pages."
+    route_to: seo-geo
+    why: Site-wide canonical/SEO auditing is general SEO; this skill only handles the Medium-side canonical mechanic.
+
+capability:
+  - scenario: "I published this article on my own blog last month. Put it on Medium without an SEO penalty, with the right tags."
+    must_include:
+      - States the Medium API is closed to new integrations (no new tokens since 2025-01-01).
+      - Chooses the import tool as the primary path for a piece that already lives on the user's site.
+      - Confirms the import auto-sets the canonical link to the origin URL and backdates from article:published_time.
+      - Gives the manual canonical fallback location (Story settings -> Customize canonical link) for when import fails.
+      - Enforces the 5-tag maximum and picks distinct topics, not keyword-stuffed variants.
+      - Flags the no-Markdown-tables and code-block formatting gotchas.
+      - Does NOT promise or attempt API automation via a newly registered token.