How to Set Up Codex SEO Skills: A Beginner's Guide (Full SKILL.md Included)

codex-seo environment: READY
  [ok] python3      3.9.6
  [ok] network      https://example.com reachable
  [ok] curl         found on PATH
  [ok] skills_dir   /Users/me/.codex/skills (writable)

series progress: 1/20 skills installed
  x codex-seo-ready            installed
  - codex-seo-technical        planned

mkdir -p ~/.codex/skills/codex-seo-ready/scripts

---
name: codex-seo-ready
description: Use when the user is about to start the Codex SEO Skills series work, or when any codex-seo-* skill fails with a python/network/path error, or when the user asks "is my environment ready for the SEO skills", "why can't the audit script run", "which codex-seo skills do I still need to install", or wants to see series install progress.
---

# Environment Readiness Check

One-time check that the machine can run every skill in the series and a
progress report on which codex-seo-* skills are already installed.

## Run

```bash
python3 ~/.codex/skills/codex-seo-ready/scripts/check_env.py
```

Add `--json` for machine-readable output.

## What the checks mean

| Check | Fail means | Fix |
|-------|------------|-----|
| python3 | No Python 3 on PATH, or version unreadable | Install Python 3 from python.org (macOS) or python.org/apt (Linux), then restart Codex |
| network | https://example.com unreachable | Check VPN/proxy or firewall; audits fetch live pages |
| curl | Not found even though python3 works | Install curl (macOS: `brew install curl`; Debian/Ubuntu: `sudo apt install curl`) |
| skills_dir | Target skills directory missing or read-only | Run `mkdir -p ~/.codex/skills && chmod u+w ~/.codex/skills` |

## Interpreting progress

The bottom of the output lists all 20 skills in the series. `-` means the
skill is not installed yet, `x` means it is (the preflight tool itself
shows as installed). The total `series progress: N/20` counts installed
skills only.

## Errors

The script never needs third-party packages and exits 0 on ready, 1 on any
unfixable check. If it prints `fatal`, report that line verbatim — it is a
bug in the script, not in your environment.

#!/usr/bin/env python3
"""Preflight check for the Codex SEO Skills series."""

import json
import os
import shutil
import subprocess
import sys
import urllib.error
import urllib.request

SERIES = [
    "codex-seo-ready", "codex-seo-technical", "codex-seo-page",
    "codex-seo-content", "codex-seo-content-brief", "codex-seo-schema",
    "codex-seo-images", "codex-seo-sitemap", "codex-seo-geo",
    "codex-seo-backlinks", "codex-seo-local", "codex-seo-google",
    "codex-seo-cluster", "codex-seo-hreflang", "codex-seo-ecommerce",
    "codex-seo-sxo", "codex-seo-programmatic", "codex-seo-competitor-pages",
    "codex-seo-plan", "codex-seo-audit",
]

SKILLS_DIR = os.environ.get("CODEX_SKILLS_DIR") or os.path.expanduser("~/.codex/skills")


def net_reachable(url, timeout=8):
    req = urllib.request.Request(url, method="HEAD",
                                 headers={"User-Agent": "codex-seo-ready/1.0"})
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            return resp.status < 500
    except urllib.error.HTTPError as e:
        return e.code < 500
    except Exception:
        return False


def get_python():
    py = shutil.which("python3") or shutil.which("python")
    if not py:
        return None, None
    try:
        out = subprocess.run([py, "--version"], capture_output=True,
                             text=True, timeout=10).stdout or ""
        out = out.strip().lower().replace("python", "").strip()
        return py, out
    except Exception:
        return py, None


def main():
    checks = []
    ok = True

    py, ver = get_python()
    if py:
        major = int(ver.split(".")[0]) if ver and ver.split(".")[0].isdigit() else 0
        good = major >= 3
        checks.append({"name": "python3", "ok": good,
                       "detail": ver or "version unreadable"})
        ok = ok and good
    else:
        checks.append({"name": "python3", "ok": False,
                       "detail": "not found on PATH"})
        ok = False

    curl = bool(shutil.which("curl"))
    net = net_reachable("https://example.com")
    checks.append({"name": "network", "ok": net,
                   "detail": ("https://example.com reachable" if net
                              else "outbound HTTPS failed - audits need network")})
    checks.append({"name": "curl", "ok": curl,
                   "detail": "found on PATH" if curl else "not found - some skills use curl"})
    ok = ok and net and curl

    exists = os.path.isdir(SKILLS_DIR)
    writable = False
    if not exists:
        try:
            os.makedirs(SKILLS_DIR, exist_ok=True)
            exists = True
        except Exception:
            pass
    if exists:
        writable = os.access(SKILLS_DIR, os.W_OK)
    checks.append({"name": "skills_dir", "ok": exists and writable,
                   "detail": SKILLS_DIR + (" (writable)" if writable else " (not writable)")})
    ok = ok and exists and writable

    installed = [d for d in os.listdir(SKILLS_DIR)
                 if os.path.isdir(os.path.join(SKILLS_DIR, d)) and d in SERIES] if exists else []

    result = {"ready": ok, "checks": checks,
              "progress": {"installed": sorted(installed),
                           "planned": [s for s in SERIES if s != "codex-seo-ready"]}}
    if "--json" in sys.argv:
        print(json.dumps(result, indent=2))
    else:
        print("codex-seo environment: " + ("READY" if ok else "FIX THE RED ROWS"))
        for c in checks:
            print(f"  [{'ok' if c['ok'] else 'FIX'}] {c['name']:<12} {c['detail']}")
        print(f"\nseries progress: {len(installed)}/{len(SERIES)} skills installed")
        for s in SERIES:
            tag = "installed" if s in installed else ("this skill" if s == "codex-seo-ready" else "planned")
            print(f"  {'x' if tag == 'installed' else '-'} {s:<26} {tag}")
    sys.exit(0 if ok else 1)


if __name__ == "__main__":
    try:
        main()
    except SystemExit:
        raise
    except Exception as e:
        print(json.dumps({"ready": False,
                          "checks": [{"name": "fatal", "ok": False, "detail": str(e)}]}))
        sys.exit(1)

python3 ~/.codex/skills/codex-seo-ready/scripts/check_env.py

codex-seo environment: READY
  [ok] python3      3.9.6
  [ok] network      https://example.com reachable
  [ok] curl         found on PATH
  [ok] skills_dir   /Users/you/.codex/skills (writable)

series progress: 1/20 skills installed