How to Set Up Codex for SEO Strategy Planning (Full SKILL.md Included)

---
name: codex-seo-plan
description: Use when the user asks for an SEO strategy, an SEO plan, a content or keyword strategy, a content calendar, a site architecture plan, a phased implementation roadmap, or a baseline+KPI target set for a new or existing website. Recons the site first so every baseline row in the plan comes from evidence rather than guesswork.
---
# Strategic SEO Planning

A plan is only as honest as its baseline. Most SEO plans die at the second
review, and it is usually because the targets were written from imagination
("we will grow organic traffic 3x") instead of from evidence (the site has
187 URLs in five sitemap files, zero security headers, and seven H1s on the
homepage). Every plan this skill produces starts with a measured baseline,
and every projected number is labeled as a projection.

## Commands

```
python3 plan_recon.py <url> [--json]
```

- `plan_recon.py` recons the site and prints what the plan's KPI table can
  legally use from public sources: title length, meta description, H1/H2
  counts, image alt coverage, JSON-LD types on the homepage, security
  headers, robots.txt sitemap/disallow lines, and the sitemap index with
  per-file URL counts and lastmod coverage.
- `--json` prints the same data machine-readable for larger scripts.
- Run it on the live site once. Behind-the-CMS numbers (GSC imports,
  analytics, review counts) are internal; the script prints the exact rows
  that stay empty until you import them.

## The five phases (what the plan walks through)

| Phase | Question it answers | Evidence it needs |
|-------|---------------------|-------------------|
| 1. Discovery | What is this business, who buys, what is the goal? | Business type, audience, goals; recon, GSC CSV |
| 2. Competitive analysis | Who are the 5, and what do they do better? | Top-5 domains, their sitemaps/schema/review footprint |
| 3. Architecture design | What is the URL map and the pillar layout? | Recon sitemap inventory, internal-link plan |
| 4. Content strategy | What is published first, at what cadence? | Gaps vs competitors, page counts, E-E-A-T plan |
| 5. Technical foundation | What has to work before any of the above matters? | Security, CWV, schema plan, AI-search readiness |
| Roadmap | In which order, with which gates? | Phase exits, review samples, batch sizes |

## Recon-first rule

Every row of the KPI table must come from one of two places: the recon
output (public data), or an explicitly labeled manual row. The recon prints
this mapping so the plan author cannot drift:

| KPI row | Where the baseline comes from |
|---------|--------------------------------|
| Indexed pages | Sitemap URL count from recon (proxy; GSC actuals differ - import the CSV) |
| Organic traffic | Internal (GSC CSV per `codex-seo-google`) - no public source |
| Keyword rankings | Internal or paid tool (DataForSEO-style OCI optional) - not invented |
| Core Web Vitals | PSI/CrUX free key or manual; never a guessed score |
| Domain authority | Paid tool or your own link inventory (`codex-seo-backlinks`) |
| Review footprint | G2/Capterra/Trustpilot pages; the numbers on them are the numbers |

If a row has no source, the plan says "manual row - attach source" and
moves on. A plan that gates a quarter on a number nobody measured is a
policy document, not a plan.

## Industry templates (pick zero, then adapt)

| Template | What it changes |
|----------|-----------------|
| SaaS/software | Free tier to paid ladder, comparison pages, changelog as SERP surface |
| Local service | GBP layer, service-area pages (only with real differentiation - see `codex-seo-programmatic`), review volume |
| E-commerce | Product schema ladder, category hubs, UCP-awareness (no invented protocol claims) |
| Publisher/media | Index bloat risk at scale, E-E-A-T for authors, topic clusters with revenue intent |
| Agency/consultancy | Service pages vs case studies, personal-name E-E-A-T, GEO for client niches |
| Generic | Pillars + supporting posts, contact-to-conversion path, review proof |

Default to the generic template when the business type is unclear, and say
so in the output. Template fit is a judgment call the plan must document,
not a rule the plan can hide behind.

## Deliverables (the contract for each)

1. `SEO-STRATEGY.md`: business context, the measured baseline (recon rows),
   goals, the chosen template, phases with owners.
2. `COMPETITOR-ANALYSIS.md`: top-5 with their sitemap sizes, schema types,
   review footprints, content gaps (each gap stated as "they have X, and
   their page is linked from Y"), authority estimate labeled as estimate.
3. `CONTENT-CALENDAR.md`: first 30 days by page type, then a cadence table
   (weekly/fortnightly), each entry tied to a gap, with a publishing
   capacity assumption stated, and staged-rollout batch sizes per the
   programmatic gates (50-100 pages per batch, 2-4 weeks of observation
   before scaling).
4. `IMPLEMENTATION-ROADMAP.md`: the 4 phases below, with exit criteria.
5. `SITE-STRUCTURE.md`: URL hierarchy from the recon sitemap inventory,
   pillar-to-support map, internal-link plan (hub/spoke), breadcrumbs.
6. `KPI-TARGETS.md`: baseline row (evidence), then 3/6/12-month columns
   labeled projected scenario, with the assumptions each projection names.

## Implementation roadmap (4 phases, with gates)

| Phase | Window | Scope | Exit gate |
|-------|--------|-------|-----------|
| 1. Foundation | weeks 1-4 | Server/HTTPS/security headers, core pages (home/about/contact/services), essential schema, analytics + GSC ownership | Recon re-run shows clean headers, H1=1 on home, sitemap live, GSC CSV imported |
| 2. Expansion | weeks 5-12 | Primary page content, blog goes live, internal linking, local layer (if applicable) | 20-30 pages live, linked from hubs, indexed count in GSC growing |
| 3. Scale | weeks 13-24 | Deeper content, links + outreach, GEO optimization, CWV work | First authoritative references; CWV in green; batch rollout after observation |
| 4. Authority | months 7-12 | Thought leadership, media/PR, advanced schema, continuous improvement | Brand queries growing; AI sources referencing the site; review count on plan |

Phase windows are defaults, not laws. The gates are: the plan says what
counts as done, and the phase cannot close without the gate meeting its
evidence.

## Competitive analysis (top-5 method)

1. Pick 5: the sites you lose to on your own head terms, plus one from the
   next tier that has grown recently (the plan should learn from the mover,
   not just the incumbent).
2. For each: run the recon script against their site, and note their
   sitemap size, schema type set, review footprint, and content surface.
3. Gap = intent they own with a page you have no answer for; a gap is not
   "they rank higher"; it is "they have a structured answer and we do not".
4. E-E-A-T pass: author names, bylines, citations, entity mentions in their
   authored content. If theirs repeat a single author's name and yours do
   not, that is a gap.
5. Authority estimate: label it. A paid tool number, or yours from
   `codex-seo-backlinks`; nothing else.

## Content strategy rules

- Publish-order by gap size first, then by closeness to the money intent.
  A popular topic nobody needs is a calendar filler.
- Estimate counts honestly: `content-capacity × weeks` where capacity
  states who writes. Do not leave capacity implicit; it is the single
  biggest cause of phantom roadmaps.
- E-E-A-T plan as first-class: author bios, page-level bylines, dates
  (add one; freshness needs a date visible on the page).
- Cross-link planned pages at planning time, not after publishing - the
  link map is part of architecture, not a content afterthought.

## Error handling

| Scenario | Action |
|----------|--------|
| Unrecognized business type | Use the generic template, state that no industry template matched |
| No live URL provided | New-site planning mode: skip recon rows and mark the baseline column "not yet measurable"; do not invent them |
| Recon fetch fails (403/timeout/SSL) | Report it; the plan starts at Phase 1 (fix the server) and the baseline row stays manual |
| Sitemap missing | Note it as a Phase-1 task; the indexed-pages baseline is "no public sitemap" |
| Competitor analysis with 1-2 competitors found | Run on what exists; state the small sample; the plan avoids claims about "the market" |
| GSC CSV not available | Baseline columns labeled manual; projections keep the assumption line |

#!/usr/bin/env python3
"""Recon a site before writing an SEO plan: what the plan's baseline rows can legally use.

stdlib only. Usage:
  python3 plan_recon.py <url> [--json]
"""
import gzip
import json
import re
import sys
import urllib.request

UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
      "(KHTML, like Gecko) Chrome/126.0 Safari/537.36")
TIMEOUT = 20
CAP = 6 * 1024 * 1024
TODAY = __import__("datetime").date.today().isoformat()
SITEMAP_CAPS = {"children": 8, "urls": 10000, "lastmod_sample": 400}


def fetch(url, _retried=False):
    req = urllib.request.Request(url, headers={
        "User-Agent": UA, "Accept": "text/html,application/xhtml+xml,*/*;q=0.8",
        "Accept-Encoding": "gzip", "Accept-Language": "en-US,en;q=0.9",
    })
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
            body = r.read(CAP + 1)
            if len(body) > CAP:
                return None, None, "body too large (over 6MB)"
            if body[:2] == b"\x1f\x8b" or r.headers.get("Content-Encoding", "").lower() == "gzip":
                body = gzip.decompress(body)
            final = r.geturl()
            hdr = dict((k.lower(), v) for k, v in r.headers.items())
            return body.decode("utf-8", "replace"), hdr, None
    except urllib.error.HTTPError as e:
        return None, None, f"HTTP {e.code}"
    except urllib.error.URLError as e:
        err = re.sub(r"\s+", " ", str(e.reason).strip("<> "))[:60]
        if not _retried and re.search(r"(?i)EOF|ssl|connect|reset|timeout", err):
            return fetch(url, _retried=True)
        return None, None, err
    except Exception as e:
        err = f"{type(e).__name__}: {e}"[:60]
        if not _retried and re.search(r"(?i)EOF|ssl|connect|reset|timeout", err):
            return fetch(url, _retried=True)
        return None, None, err


def metal(html, needle):
    for pat in (r'<meta[^>]+(?:name|property)=["\']' + needle + r'["\'][^>]*content=["\']([^"\']+)',
                r'<meta[^>]+content=["\']([^"\']+)["\'][^>]*(?:name|property)=["\']' + needle +
                r'["\']'):
        m = re.search(pat, html, re.I)
        if m:
            return m.group(1)
    return None


def ld_types(html):
    counts = {}
    stack_objs = []
    for m in re.finditer(r'<script[^>]*type=["\']application/ld\+json["\'][^>]*>(.*?)</script>',
                         html, re.I | re.S):
        try:
            data = json.loads(m.group(1).strip())
        except Exception:
            continue
        stack_objs.append(data)
    while stack_objs:
        node = stack_objs.pop()
        if isinstance(node, dict):
            t = node.get("@type")
            for x in (t if isinstance(t, list) else [t]):
                if isinstance(x, str):
                    counts[x] = counts.get(x, 0) + 1
            stack_objs.extend(v for v in node.values() if isinstance(v, (dict, list)))
        elif isinstance(node, list):
            stack_objs.extend(node)
    return counts


def recon_page(url):
    out = {"url": url}
    html, hdr, err = fetch(url)
    if err or html is None:
        out["status"] = "fetch-error"
        out["errors"] = [err or "no page"]
        return out
    out["status"] = 200
    out["final_url"] = url
    out["scheme"] = url.split(":")[0] + ":"
    txt = re.sub(r"<script.*?</script>|<style.*?</style>", " ", html, flags=re.I | re.S)
    txt = re.sub(r"<[^>]+>", " ", txt)
    txt = re.sub(r"\s+", " ", txt)
    ti = re.search(r"<title[^>]*>(.*?)</title>", html, re.I | re.S)
    out["title"] = {"chars": len(ti.group(1).strip()) if ti else 0}
    md = metal(html, "(?:description|og:description)")
    out["meta_description"] = {"found": md is not None,
                               "chars": (len(md) if md else 0)}
    out["h1"] = len(re.findall(r"<h1[^>]*>", html, re.I))
    out["h2"] = len(re.findall(r"<h2[^>]*>", html, re.I))
    imgs = re.findall(r"<img[^>]*>", html, re.I)
    alt = [i for i in imgs if re.search(r'alt=["\'"][^"\'"]+', i, re.I)]
    out["images"] = {"total": len(imgs), "with_alt": len(alt),
                     "alt_coverage_pct": round(100 * len(alt) / len(imgs), 1) if imgs else 100.0}
    out["jsonld_types"] = dict(sorted(ld_types(html).items(), key=lambda kv: -kv[1]))
    out["headers_report"] = {
        k: "present" for k in ("strict-transport-security", "x-content-type-options",
                               "content-security-policy", "referrer-policy") if hdr and k in hdr}
    out["scheme"] = out.get("scheme")
    canon = re.search(r'<link[^>]+rel=["\']canonical["\'][^>]*href=["\']([^"\']+)', html, re.I) \
        or re.search(r'<link[^>]+href=["\']([^"\']+)["\'][^>]*rel=["\']canonical', html, re.I)
    out["canonical"] = canon.group(1) if canon else None
    return out


def parse_xml_text(body):
    """Namespace-insensitive <loc>/<lastmod> extraction from a sitemap file."""
    locs = re.findall(r"<loc>(.*?)</loc>", body, re.S)
    lastmods = len(re.findall(r"<lastmod>(.*?)</lastmod>", body, re.S))
    return locs, lastmods


def recon_sitemap(base, robots):
    """robots: raw text or None. Returns dict with rows."""
    info = {"found": False}
    sm_url = None
    if robots:
        sm = [l.strip().split(None, 1)[-1] for l in robots.splitlines()
              if re.match(r"(?i)^sitemap\b", l) and ":" in l]
        sm_url = sm[0] if sm else None
        dis = [l for l in robots.splitlines() if re.match(r"(?i)^disallow\b", l)]
        info["robots_sitemap_lines"] = len(sm)
        info["robots_disallows"] = len(dis)
    if not sm_url:
        sm_url = base + "/sitemap.xml"
    body, _, err = fetch(sm_url)
    if err or body is None:
        info["errors"] = [err or "no body"]
        return info
    info["found"] = True
    info["file"] = sm_url
    info["kind"] = "index" if "<sitemap>" in body else "urlset"
    if info["kind"] == "index":
        children = re.findall(r"<loc>(.*?)</loc>", body, re.S)
        kids = []
        total = 0
        for c in children[:SITEMAP_CAPS["children"]]:
            cb, _, cerr = fetch(c)
            if cb is None:
                kids.append({"url": c, "error": cerr or "no body"})
                continue
            locs, lastmods = parse_xml_text(cb)
            n = min(len(locs), SITEMAP_CAPS["urls"])
            lt = min(lastmods, SITEMAP_CAPS["lastmod_sample"])
            kids.append({"url": c, "urls": n,
                         "lastmod_pct": round(100 * lt / min(len(locs), SITEMAP_CAPS["lastmod_sample"]), 1)
                         if locs else None})
            total += n
        info["children"] = kids
        info["urls_total"] = total
    else:
        locs, lastmods = parse_xml_text(body)
        n = min(len(locs), SITEMAP_CAPS["urls"])
        info["urls_total"] = n
        sample = min(len(locs), SITEMAP_CAPS["lastmod_sample"])
        info["lastmod_pct"] = round(100 * min(lastmods, sample) / sample, 1) if sample else 100.0
    return info


def report(page, robots, smap, base):
    out = ["SITE RECON: " + page["url"], "=" * 40]
    if page.get("status") != 200:
        out.append("STATUS: fetch-error - " + "; ".join(page.get("errors", [])))
        out.append("Rule: a plan for an unreachable site starts at Phase 1 (Fix the server), "
                   "not at keyword research.")
        return out
    out.append("final URL: " + page.get("final_url", page["url"]))
    out.append("HTTPS page served over: " + page["scheme"])
    out.append("www → canonical: " + (page.get("canonical") or "no canonical tag"))
    for k in ("strict-transport-security", "x-content-type-options",
              "content-security-policy", "referrer-policy"):
        out.append(f"security header {k}: " + ("present" if k in page.get("headers_report", {})
                                               else "missing"))
    out.append("title chars (ideal 30-60): " + str(page["title"]["chars"]))
    got = page["meta_description"]
    out.append("meta description: " + ("present " + str(got["chars"]) + " chars"
                                       if got["found"] else "MISSING"))
    out.append("H1 count (ideal 1): " + str(page["h1"]) + "   h2 count: " + str(page["h2"]))
    im, alt, cov = page["images"]["total"], page["images"]["with_alt"], page["images"]["alt_coverage_pct"]
    out.append(f"images: {im} total, {alt} with alt = {cov}% covered")
    t = page["jsonld_types"]
    out.append("JSON-LD types: " + (", ".join(f"{k}: {v}" for k, v in t.items()) or "NONE") +
               ("   |   (homepage only; audit per page type with codex-seo-schema)" if t else ""))
    out.append("robots.txt: " + (
        f"{smap.get('robots_sitemap_lines', 0)} sitemap line(s), "
        f"{smap.get('robots_disallows', 0)} disallow rule(s)" if robots is not None else "not fetched"))
    if smap.get("found"):
        line = f"sitemap: {smap['file']}  ({smap['kind']})  URLs: {smap.get('urls_total', 0)}"
        if smap.get("lastmod_pct") is not None:
            line += f"  lastmod: {smap['lastmod_pct']}%"
        out.append(line)
        for k in smap.get("children", []):
            if "error" in k:
                out.append(f"  child file: {k['url']}  ERROR {k['error']}")
            else:
                lt = f"  lastmod {k['lastmod_pct']}%" if k.get("lastmod_pct") is not None else ""
                out.append(f"  child file: {k['url']}  URLs: {k['urls']}{lt}")
    else:
        out.append("sitemap: NOT FOUND (" + "; ".join(smap.get("errors", ["no robots line, /sitemap.xml failed"])) + ")")
    out.append("")
    out.append("KPI-baseline mapping (what this recon can legally feed):")
    out.append("  Indexed pages proxy = sitemap URL count above; GSC actuals differ - import CSV "
               "(codex-seo-google).")
    out.append("  Traffic / keyword rankings = internal data; not on the public web.")
    out.append("  Core Web Vitals = PSI or CrUX key or manual (codex-seo-google).")
    out.append("  Domain authority / review footprint = a paid or 3rd-party tool, or your own ")
    out.append("   link inventory (codex-seo-backlinks).")
    out.append("NOT PUBLISHABLE from this recon: any KPI row not mapped above. Leave it as a "
               "manual row until a real source exists.")
    return out


def main():
    args = [a for a in sys.argv[1:]]
    json_mode = "--json" in args
    urls = [a for a in args if not a.startswith("--")]
    if not urls:
        print("usage: plan_recon.py <url> [--json]", file=sys.stderr)
        return 2
    url = urls[0]
    base = url.split("//")[0] + "//" + url.split("//")[1].split("/", 1)[0] if "//" in url else url
    page = recon_page(url)
    robots, robots_err = None, None
    rb, _, rerr = fetch(base + "/robots.txt")
    if rb is not None and "<html" not in rb.lower()[:400]:
        robots = rb
    else:
        robots_err = rerr or "no robots.txt"
    if robots is None:
        robots = ""
    smap = recon_sitemap(base, robots or None)
    if json_mode:
        print(json.dumps({"page": page, "robots_error": robots_err, "sitemap": smap}, indent=1))
        return 0
    print("\n".join(report(page, robots, smap, base)))
    print("recon run: " + TODAY + " | source URLs are public pages of the target site")
    return 0


if __name__ == "__main__":
    sys.exit(main())

# 1) create the skill directory
mkdir -p ~/.codex/skills/codex-seo-plan/scripts

# 2) save the SKILL.md (paste the first code block above into the file below)
nano ~/.codex/skills/codex-seo-plan/SKILL.md

# 3) save the script (paste the second code block above)
nano ~/.codex/skills/codex-seo-plan/scripts/plan_recon.py

# 4) smoke test against a site you can reach
python3 ~/.codex/skills/codex-seo-plan/scripts/plan_recon.py https://your-site.com

python3 ~/.codex/skills/codex-seo-plan/scripts/plan_recon.py https://your-site.com

<PASTE_TO_CODEX>
You will install a Codex skill. Read the two code blocks in the page you were pasted from: the block that starts with the YAML frontmatter `name: codex-seo-plan` and the block that starts with `#!/usr/bin/env python3` (which contains the string `plan_recon.py`).

1. Create the directory ~/.codex/skills/codex-seo-plan/scripts.
2. Save the YAML block to ~/.codex/skills/codex-seo-plan/SKILL.md (only the frontmatter and body; do not include the fence lines).
3. Save the Python block to ~/.codex/skills/codex-seo-plan/scripts/plan_recon.py (keep the shebang and everything after it).
4. Run: python3 ~/.codex/skills/codex-seo-plan/scripts/plan_recon.py https://example.com
5. If example.com fails to fetch, try the user's real site when they provide its URL.
6. Report back: the H1 count row, the sitemap URL count, and whether the KPI-baseline mapping block printed.

Do not modify any existing skill directories. Do not touch ~/.codex/skills/ outside the codex-seo-plan directory. Timebox the smoke test to one run unless the user asks for more.
</PASTE_TO_CODEX>