[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2459":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":46,"readmeContent":47,"aiSummary":48,"trendingCount":16,"starSnapshotCount":16,"syncStatus":49,"lastSyncTime":50,"discoverSource":51},2459,"codex-seo","AgriciDaniel\u002Fcodex-seo","AgriciDaniel","Codex-first SEO skill suite. 26 workflows, 24 TOML agents, DataForSEO\u002FGemini\u002FGoogle\u002FFirecrawl integrations, GEO\u002FAEO, CWV, schema, backlinks, local\u002Fmaps, and deterministic reports.","https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo",null,"Python",254,41,5,4,0,20,51,150,60,4.87,"Other",false,"main",[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"ai-search","ai-seo","automation","codex","codex-cli","codex-skills","content-strategy","core-web-vitals","dataforseo","ecommerce-seo","generative-engine-optimization","google-search-console","local-seo","marketing-automation","mcp","open-source","python","schema-markup","seo","technical-seo","2026-06-12 02:00:41","\u003Cp align=\"center\">\n  \u003Cimg src=\"screenshots\u002Fcover-image.webp\" alt=\"Codex SEO: SEO audit skill suite for Codex\" width=\"100%\">\n\u003C\u002Fp>\n\n\u003Ch2 align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=39FE6_oRcYY\">Watch on YouTube\u003C\u002Fa>\n\u003C\u002Fh2>\n\n# Codex SEO - SEO Audit Skill Suite for Codex\n\nCodex-first SEO analysis suite with 1 orchestrator skill, 26 specialist workflows, 24 TOML agent profiles, MCP\u002FAPI extensions, deterministic headless runners, and premium audit report generation.\n\n[![CI](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo\u002Factions\u002Fworkflows\u002Frunners-ci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo\u002Factions\u002Fworkflows\u002Frunners-ci.yml)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FAgriciDaniel\u002Fcodex-seo?label=Release)](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo\u002Freleases)\n[![Codex Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-Skill_Suite-blue)](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-blue)](pyproject.toml)\n[![Workflows](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSEO_Workflows-26-orange)](docs\u002FCOMMANDS.md)\n\nCodex SEO is a Codex-native port of [`AgriciDaniel\u002Fclaude-seo`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fclaude-seo), synchronized to upstream `main` at `a9cf338` and adapted for Codex skills, Codex plugins, TOML agents, shared cache artifacts, and repeatable local\u002FAPI execution.\n\nIt covers technical SEO, on-page analysis, content quality, E-E-A-T, schema markup, image optimization, sitemap architecture, Core Web Vitals, GEO\u002FAEO for AI search, backlinks, local SEO, maps intelligence, Google APIs, semantic clustering, SXO, drift monitoring, e-commerce SEO, hreflang, FLOW prompts, DataForSEO, Firecrawl, and Gemini\u002Fnanobanana image workflows.\n\n## Contents\n\n- [Status](#status)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Visual Overview](#visual-overview)\n- [Commands](#commands)\n- [Features](#features)\n- [Extensions](#extensions)\n- [Headless\u002FAPI Usage](#headlessapi-usage)\n- [Architecture](#architecture)\n- [Verification](#verification)\n- [Requirements](#requirements)\n- [Credentials And Cache](#credentials-and-cache)\n- [Security](#security)\n- [Uninstall](#uninstall)\n- [Contributing](#contributing)\n- [Related Projects](#related-projects)\n- [Credits](#credits)\n- [Attribution](#attribution)\n\n## Status\n\n- Repository visibility: public.\n- Current release: [`v1.9.6-codex.5`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo\u002Freleases\u002Ftag\u002Fv1.9.6-codex.5).\n- Installer default ref: `v1.9.6-codex.5`.\n- Latest local validation: 52 tests passing, full installed smoke suite passing, demo readiness passing.\n- Runtime credentials stay outside the repo under Codex\u002Flocal config paths.\n- Discovery topics: `codex`, `codex-cli`, `codex-skills`, `seo`, `ai-seo`, `ai-search`, `technical-seo`, `generative-engine-optimization`, `core-web-vitals`, `schema-markup`, `local-seo`, `ecommerce-seo`, `content-strategy`, `google-search-console`, `dataforseo`, `mcp`, `python`, `automation`, `marketing-automation`, `open-source`.\n\n## Install\n\n### One-Line Install\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FAgriciDaniel\u002Fcodex-seo\u002Fv1.9.6-codex.5\u002Finstall.sh | bash\n```\n\nWindows:\n\n```powershell\nirm https:\u002F\u002Fraw.githubusercontent.com\u002FAgriciDaniel\u002Fcodex-seo\u002Fv1.9.6-codex.5\u002Finstall.ps1 | iex\n```\n\n### Review Before Installing\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo.git\ncd codex-seo\nbash install.sh\n```\n\nWindows:\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo.git\ncd codex-seo\npowershell -ExecutionPolicy Bypass -File .\\install.ps1\n```\n\nThe installer copies the skill suite into `~\u002F.codex\u002Fskills\u002F`, installs TOML agents into `~\u002F.codex\u002Fagents\u002F`, creates a Python virtualenv at `~\u002F.codex\u002Fskills\u002Fseo\u002F.venv\u002F`, installs core runtime dependencies, attempts optional capability groups, and verifies the runtime.\n\n### Installer Overrides\n\n```bash\nCODEX_HOME=~\u002F.codex \\\nCODEX_SEO_REPO=https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fcodex-seo \\\nCODEX_SEO_REF=v1.9.6-codex.5 \\\nbash install.sh\n```\n\n| Variable | Purpose |\n|---|---|\n| `CODEX_HOME` | Alternate Codex home. Defaults to `~\u002F.codex`. |\n| `CODEX_SEO_REPO` | Git URL, fork URL, or local repository path. |\n| `CODEX_SEO_REF` | Branch, tag, or commit. Defaults to `v1.9.6-codex.5`. |\n| `CODEX_SEO_SKIP_PLAYWRIGHT_BROWSER=1` | Skip Chromium install for visual\u002FPDF workflows. |\n| `CODEX_SEO_PLAYWRIGHT_WITH_DEPS=1` | Ask Playwright to install system dependencies where supported. |\n\n## Quick Start\n\nRestart Codex after installation. Then ask naturally; a `\u002Fseo` command is not required:\n\n```text\nDo a full SEO check on https:\u002F\u002Fexample.com following best practices.\n```\n\n```text\nReview this page for schema, Core Web Vitals, image SEO, and AI search readiness.\n```\n\n```text\nCreate an SEO strategy and content roadmap for a local dental clinic.\n```\n\nCommand-style prompts also work:\n\n```text\n\u002Fseo audit https:\u002F\u002Fexample.com\n\u002Fseo technical https:\u002F\u002Fexample.com\n\u002Fseo schema https:\u002F\u002Fexample.com\n\u002Fseo dataforseo serp \"best seo tools\"\n```\n\n## Visual Overview\n\nCodex SEO is designed as a Codex-first routing layer: the user can ask naturally, the orchestrator selects the right specialist workflow, and deterministic runners write repeatable artifacts instead of relying on invisible chat-only output.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"secondaryColor\":\"#06222a\",\"tertiaryColor\":\"#ff9f1c\",\"edgeLabelBackground\":\"#05080d\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nflowchart LR\n  user[\"User prompt\u003Cbr\u002F>natural language or \u002Fseo\"] --> orchestrator[\"skills\u002Fseo\u002FSKILL.md\u003Cbr\u002F>main orchestrator\"]\n  orchestrator --> cache[\".seo-cache\u003Cbr\u002F>shared evidence\"]\n  orchestrator --> skills[\"26 specialist\u003Cbr\u002F>SEO workflows\"]\n  skills --> agents[\"24 TOML agents\u003Cbr\u002F>parallel analysis slices\"]\n  skills --> scripts[\"scripts\u002F\u003Cbr\u002F>deterministic runners\"]\n  scripts --> output[\"output\u002F\u003Cbr\u002F>Markdown, JSON, HTML, PDF\"]\n  cache --> skills\n  class user,orchestrator accent\n  class cache,scripts data\n  class output output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n## Commands\n\n| Prompt | Purpose |\n|---|---|\n| `\u002Fseo audit \u003Curl>` | Full site audit with specialist routing and premium report support |\n| `\u002Fseo page \u003Curl>` | Deep single-page SEO analysis |\n| `\u002Fseo technical \u003Curl>` | Crawlability, indexability, security, JavaScript, CWV |\n| `\u002Fseo content \u003Curl>` | E-E-A-T, helpfulness, readability, AI citation readiness |\n| `\u002Fseo schema \u003Curl>` | Structured data detection, validation, and JSON-LD generation |\n| `\u002Fseo images \u003Curl>` | Alt text, image weight, formats, metadata, image SERP opportunities |\n| `\u002Fseo sitemap \u003Curl>` | XML sitemap discovery, quality gates, generation guidance |\n| `\u002Fseo geo \u003Curl>` | AI Overviews, ChatGPT, Perplexity, llms.txt, citability |\n| `\u002Fseo performance \u003Curl>` | Core Web Vitals, Lighthouse-oriented performance signals |\n| `\u002Fseo visual \u003Curl>` | Screenshots, mobile rendering, above-the-fold analysis |\n| `\u002Fseo plan \u003Cbusiness-type>` | Strategic SEO roadmap and content plan |\n| `\u002Fseo programmatic \u003Curl>` | Programmatic SEO risk and scale planning |\n| `\u002Fseo competitor-pages \u003Curl>` | Comparison and alternatives page opportunities |\n| `\u002Fseo hreflang \u003Curl>` | International SEO, locale validation, content parity |\n| `\u002Fseo local \u003Curl>` | Local SEO, GBP signals, NAP, citations, reviews |\n| `\u002Fseo maps \u003Ccommand>` | Geo-grid, GBP audit, review intelligence, local maps signals |\n| `\u002Fseo google \u003Ccommand>` | GSC, PageSpeed, CrUX, Indexing API, GA4 workflows |\n| `\u002Fseo backlinks \u003Curl>` | Backlink profile summary and source-tier detection |\n| `\u002Fseo cluster \u003Ckeyword>` | SERP-based topic clustering and hub-spoke planning |\n| `\u002Fseo sxo \u003Curl>` | Search Experience Optimization, intent\u002Fpage-type fit |\n| `\u002Fseo drift baseline \u003Curl>` | Capture an SEO baseline before changes |\n| `\u002Fseo drift compare \u003Curl>` | Compare current SEO signals against a baseline |\n| `\u002Fseo ecommerce \u003Curl>` | Product SEO, marketplace visibility, product schema |\n| `\u002Fseo flow \u003Cstage>` | FLOW framework prompts for Find, Leverage, Optimize, Win |\n| `\u002Fseo dataforseo \u003Ccommand>` | Live SERP, keyword, backlink, content, and AI visibility data |\n| `\u002Fseo firecrawl \u003Ccommand>` | JS-rendered crawling and site mapping via Firecrawl |\n| `\u002Fseo image-gen \u003Cuse-case>` | OG images, hero images, product visuals, infographics |\n\nFull command details live in [docs\u002FCOMMANDS.md](docs\u002FCOMMANDS.md).\n\n## Features\n\n### Full Audit Pipeline\n\n- Detects site\u002Fbusiness type.\n- Runs technical, content, schema, sitemap, performance, visual, GEO, image, and on-page analysis.\n- Adds conditional specialists for local, maps, Google APIs, backlinks, clusters, SXO, drift, and e-commerce.\n- Writes markdown reports, JSON summaries, cache artifacts, and optional premium HTML\u002FPDF output.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"secondaryColor\":\"#06222a\",\"tertiaryColor\":\"#ff9f1c\",\"edgeLabelBackground\":\"#05080d\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nflowchart TD\n  request[\"Audit request\"] --> detect[\"Detect site type\u003Cbr\u002F>business model and context\"]\n  detect --> core[\"Core audit specialists\"]\n  core --> technical[\"Technical\"]\n  core --> content[\"Content\"]\n  core --> schema[\"Schema\"]\n  core --> sitemap[\"Sitemap\"]\n  core --> geo[\"GEO \u002F AI search\"]\n  core --> images[\"Images\"]\n  core --> performance[\"Performance\"]\n  core --> visual[\"Visual\"]\n  detect --> conditional[\"Conditional specialists\"]\n  conditional --> local[\"Local \u002F Maps\"]\n  conditional --> backlinks[\"Backlinks\"]\n  conditional --> google[\"Google APIs\"]\n  conditional --> ecommerce[\"E-commerce\"]\n  conditional --> drift[\"Drift\"]\n  technical --> report[\"Unified SEO report\"]\n  content --> report\n  schema --> report\n  sitemap --> report\n  geo --> report\n  images --> report\n  performance --> report\n  visual --> report\n  local --> report\n  backlinks --> report\n  google --> report\n  ecommerce --> report\n  drift --> report\n  report --> artifacts[\"SUMMARY.json\u003Cbr\u002F>FULL-AUDIT-REPORT.md\u003Cbr\u002F>ACTION-PLAN.md\u003Cbr\u002F>optional HTML\u002FPDF\"]\n  class request,detect accent\n  class core,conditional data\n  class report,artifacts output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n### Technical SEO\n\n- Robots.txt, sitemap discovery, canonical checks, indexability, URL hygiene.\n- Security headers, JavaScript rendering risk, mobile basics, IndexNow.\n- Core Web Vitals with INP, LCP, CLS, FCP, TTFB, and PageSpeed\u002FCrUX integrations where available.\n\n### Content, GEO, And SXO\n\n- E-E-A-T and helpful content signals.\n- AI citation readiness, answer-first formatting, entity clarity, llms.txt support.\n- Search experience analysis: page type, user stories, persona fit, intent mismatch.\n\n### Structured Data\n\n- JSON-LD extraction and validation.\n- Schema recommendations for Organization, LocalBusiness, Product, Article, FAQ, Breadcrumb, and related types.\n- Generated schema artifacts for downstream use.\n\n### Local, Maps, And E-Commerce SEO\n\n- Local SEO signals, GBP readiness, citations, reviews, NAP consistency.\n- Maps intelligence via free sources and DataForSEO when configured.\n- Product schema, marketplace endpoints, merchant visibility, and e-commerce template checks.\n\n### Drift Monitoring\n\n- Capture SEO-critical baselines.\n- Compare deployments or page changes.\n- Track title, meta, headings, canonical, schema, robots, links, and content deltas.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"actorBkg\":\"#07131c\",\"actorBorder\":\"#00d7e6\",\"actorTextColor\":\"#f5fbff\",\"actorLineColor\":\"#21e6c1\",\"signalColor\":\"#21e6c1\",\"signalTextColor\":\"#f5fbff\",\"labelBoxBkgColor\":\"#10151a\",\"labelTextColor\":\"#f5fbff\",\"noteBkgColor\":\"#10151a\",\"noteTextColor\":\"#f5fbff\",\"activationBkgColor\":\"#06222a\",\"activationBorderColor\":\"#ff9f1c\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nsequenceDiagram\n  participant Before as Baseline\n  participant Runner as Drift runner\n  participant After as Current page\n  participant Cache as .seo-cache\n  participant Report as Drift report\n  Before->>Runner: Capture titles, metas, canonicals, schema, headings\n  Runner->>Cache: Store baseline snapshot\n  After->>Runner: Re-check current SEO signals\n  Cache->>Runner: Load prior snapshot\n  Runner->>Report: Write changed, missing, and regressed signals\n```\n\n### Deterministic Runners\n\n- `scripts\u002Frun_skill_workflow.py` standardizes output for every user-invokable workflow.\n- `scripts\u002Frun_api_smoke_suite.py` runs all supported workflows in one pass.\n- Setup-required workflows return structured fallback results instead of pretending live data exists.\n\n## Extensions\n\n| Extension | Skill | Setup | Notes |\n|---|---|---|---|\n| DataForSEO | `seo-dataforseo`, `seo-maps`, `seo-ecommerce`, `seo-cluster` | `.\u002Fextensions\u002Fdataforseo\u002Finstall.sh` | Live SERP, keyword, backlinks, on-page, content, business data, AI visibility |\n| Google APIs | `seo-google`, `seo-performance` | `python scripts\u002Fgoogle_auth.py --setup` | PageSpeed, CrUX, GSC, URL Inspection, Indexing API, GA4 |\n| Firecrawl | `seo-firecrawl` | `.\u002Fextensions\u002Ffirecrawl\u002Finstall.sh` | JS-rendered crawl, scrape, site map |\n| Banana \u002F Gemini | `seo-image-gen` | `.\u002Fextensions\u002Fbanana\u002Finstall.sh` | AI image generation through `nanobanana-mcp` |\n\nOptional integrations enrich the same workflow surface. If credentials or MCP servers are missing, wrappers return `setup_required` or `mcp_configured` states with no fabricated live data.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"secondaryColor\":\"#06222a\",\"tertiaryColor\":\"#ff9f1c\",\"edgeLabelBackground\":\"#05080d\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nflowchart LR\n  codex[\"Codex SEO workflows\"] --> local[\"Local evidence\u003Cbr\u002F>HTML, robots, sitemaps, screenshots\"]\n  codex --> dfs[\"DataForSEO MCP\u003Cbr\u002F>SERP, keywords, backlinks, maps\"]\n  codex --> google[\"Google APIs\u003Cbr\u002F>GSC, PageSpeed, CrUX, GA4\"]\n  codex --> firecrawl[\"Firecrawl MCP\u003Cbr\u002F>JS crawl and site maps\"]\n  codex --> banana[\"Gemini \u002F nanobanana\u003Cbr\u002F>SEO image assets\"]\n  local --> artifacts[\"Reports and .seo-cache\"]\n  dfs --> artifacts\n  google --> artifacts\n  firecrawl --> artifacts\n  banana --> artifacts\n  class codex accent\n  class local,dfs,google,firecrawl,banana data\n  class artifacts output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\nDemo readiness:\n\n```bash\npython scripts\u002Fdemo_readiness.py --target https:\u002F\u002Fexample.com --live-apis --workflows --json\n```\n\nOne low-depth DataForSEO proof:\n\n```bash\npython scripts\u002Fdemo_readiness.py --target https:\u002F\u002Fexample.com --live-apis --live-serp --serp-keyword \"seo tools\" --json\n```\n\n## Headless\u002FAPI Usage\n\nRun a single workflow:\n\n```bash\npython scripts\u002Frun_skill_workflow.py --skill seo-technical https:\u002F\u002Fexample.com --json\npython scripts\u002Frun_skill_workflow.py --skill seo-google https:\u002F\u002Fexample.com --json\npython scripts\u002Frun_skill_workflow.py --skill seo-dataforseo https:\u002F\u002Fexample.com --json\n```\n\nRun the full smoke suite:\n\n```bash\npython scripts\u002Frun_api_smoke_suite.py https:\u002F\u002Fexample.com --json\n```\n\nVerify environment:\n\n```bash\npython scripts\u002Fverify_environment.py --target https:\u002F\u002Fexample.com --json\n```\n\nBootstrap a clean runtime:\n\n```bash\npython scripts\u002Fbootstrap_environment.py --venv .venv --json\n```\n\nArtifacts are written to `output\u002F`. Shared project cache is written to `.seo-cache\u002F`. Both are ignored by git.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"secondaryColor\":\"#06222a\",\"tertiaryColor\":\"#ff9f1c\",\"edgeLabelBackground\":\"#05080d\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nflowchart LR\n  cli[\"run_skill_workflow.py\u003Cbr\u002F>single workflow\"] --> json[\"JSON result\"]\n  cli --> markdown[\"Markdown report\"]\n  cli --> cacheWrite[\".seo-cache update\"]\n  suite[\"run_api_smoke_suite.py\u003Cbr\u002F>all workflows\"] --> json\n  suite --> outputRoot[\"output\u002Fapi-smoke-*\"]\n  verify[\"verify_environment.py\"] --> readiness[\"ready \u002F setup_required\u003Cbr\u002F>capability status\"]\n  markdown --> outputRoot\n  json --> outputRoot\n  cacheWrite --> cache[\".seo-cache\"]\n  class cli,suite,verify accent\n  class cacheWrite,readiness data\n  class json,markdown,outputRoot,cache output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n## Architecture\n\nThe repository separates Codex-facing instructions, deterministic runtime code, optional provider setup, and validation contracts. That keeps the skill system usable in chat, installable as a suite, and testable from CI\u002FAPI workflows.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#05080d\",\"primaryColor\":\"#07131c\",\"primaryTextColor\":\"#f5fbff\",\"primaryBorderColor\":\"#00d7e6\",\"lineColor\":\"#00d7e6\",\"secondaryColor\":\"#06222a\",\"tertiaryColor\":\"#ff9f1c\",\"edgeLabelBackground\":\"#05080d\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, sans-serif\"}}}%%\nflowchart TB\n  manifest[\".codex-plugin\u002Fplugin.json\"] --> skillsRoot[\"skills\u002F\"]\n  skillsRoot --> orchestrator[\"seo\u002FSKILL.md\u003Cbr\u002F>routing and orchestration\"]\n  skillsRoot --> specialists[\"seo-*\u002FSKILL.md\u003Cbr\u002F>specialist workflows\"]\n  agentsDir[\"agents\u002Fseo-*.toml\"] --> specialists\n  scriptsDir[\"scripts\u002F\u003Cbr\u002F>deterministic runners\"] --> specialists\n  extensionsDir[\"extensions\u002F\u003Cbr\u002F>optional MCP setup\"] --> specialists\n  references[\"skills\u002Fseo\u002Freferences\u002F\u003Cbr\u002F>thresholds and shared contracts\"] --> specialists\n  specialists --> cacheDir[\".seo-cache\u002F\u003Cbr\u002F>cross-skill memory\"]\n  specialists --> outputDir[\"output\u002F\u003Cbr\u002F>reports and artifacts\"]\n  testsDir[\"tests\u002F\u003Cbr\u002F>contract and smoke coverage\"] --> manifest\n  testsDir --> skillsRoot\n  testsDir --> scriptsDir\n  class manifest,orchestrator accent\n  class skillsRoot,specialists,agentsDir,scriptsDir,extensionsDir,references,testsDir data\n  class cacheDir,outputDir output\n  classDef default fill:#07131c,stroke:#00d7e6,color:#f5fbff,stroke-width:1.4px\n  classDef accent fill:#10151a,stroke:#ff9f1c,color:#fff7ed,stroke-width:2px\n  classDef data fill:#06222a,stroke:#21e6c1,color:#ecfeff,stroke-width:1.5px\n  classDef output fill:#15101a,stroke:#ff9f1c,color:#fff7ed,stroke-width:1.8px\n```\n\n```text\ncodex-seo\u002F\n├── .codex-plugin\u002Fplugin.json        # Codex plugin manifest\n├── skills\u002F\n│   ├── seo\u002FSKILL.md                 # Main orchestrator\n│   └── seo-*\u002FSKILL.md               # 26 specialist workflows\n├── agents\u002F                          # 24 Codex TOML agent profiles\n├── scripts\u002F                         # Deterministic runners and API helpers\n├── extensions\u002F\n│   ├── dataforseo\u002F                  # DataForSEO MCP setup and docs\n│   ├── firecrawl\u002F                   # Firecrawl MCP setup and docs\n│   └── banana\u002F                      # Gemini\u002Fnanobanana image generation setup\n├── hooks\u002F                           # Quality-gate hooks\n├── schema\u002F                          # Schema.org templates\n├── docs\u002F                            # Architecture, commands, installation, MCP, demo\n└── tests\u002F                           # Contract and workflow tests\n```\n\nDesign principles:\n\n- `skills\u002F` is the source of truth.\n- `skills\u002Fseo\u002FSKILL.md` routes natural-language SEO requests.\n- TOML agents are Codex-native and mirror specialist workflows.\n- Runtime credentials stay in `~\u002F.config\u002Fcodex-seo\u002F` or `~\u002F.codex\u002Fsettings.json`.\n- Legacy `claude-seo` config\u002Fcache paths are read only as migration fallback.\n\nMore detail: [docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md).\n\n## Verification\n\nLocal release gate:\n\n```bash\npython -m pytest tests\u002F\nbash -n install.sh uninstall.sh\npython -m compileall -q scripts hooks\npython scripts\u002Frun_api_smoke_suite.py https:\u002F\u002Fexample.com --json\n```\n\nPowerShell parse check:\n\n```powershell\n$files = Get-ChildItem -Recurse -Filter *.ps1\nforeach ($f in $files) {\n  $tokens = $null\n  $errs = $null\n  [System.Management.Automation.Language.Parser]::ParseFile($f.FullName, [ref]$tokens, [ref]$errs) > $null\n  if ($errs.Count) { $errs; exit 1 }\n}\n```\n\nCurrent GitHub CI runs:\n\n- dependency install\n- shell syntax checks\n- Python compile checks\n- `--help` checks for runner scripts\n- `python -m pytest tests\u002F`\n- contract smoke checks for MCP-aware workflows\n\n## Requirements\n\n- Codex CLI with local skills support\n- Python 3.10+\n- Git\n- Optional: Playwright Chromium for screenshots and PDF reports\n- Optional: DataForSEO account for live SEO data\n- Optional: Google API credentials for PageSpeed\u002FCrUX\u002FGSC\u002FGA4\n- Optional: Firecrawl API key for JS-rendered crawling\n- Optional: Google AI API key for Gemini\u002Fnanobanana image generation\n\n## Credentials And Cache\n\nCodex SEO writes new local credentials and state to Codex-specific paths:\n\n- `~\u002F.codex\u002Fsettings.json` for MCP server configuration\n- `~\u002F.config\u002Fcodex-seo\u002F` for API configs and cost ledgers\n- `~\u002F.cache\u002Fcodex-seo\u002F` for runtime caches\n- `.seo-cache\u002F` inside the active project for cross-skill summaries\n\nLegacy `~\u002F.config\u002Fclaude-seo\u002F` and `~\u002F.cache\u002Fclaude-seo\u002F` paths are read only as migration fallback. Do not commit `.seo-cache\u002F`, `output\u002F`, `.mcp.json`, `.env`, OAuth tokens, service accounts, or provider keys.\n\n## Security\n\n- URL-aware scripts block private, loopback, reserved, multicast, unspecified, and metadata hosts.\n- Credential setup writes outside tracked repo files.\n- Sensitive local settings are expected to use `0600` file permissions.\n- DataForSEO calls use cost guardrails through `scripts\u002Fdataforseo_costs.py`.\n- Report vulnerabilities through [SECURITY.md](SECURITY.md).\n\n## Uninstall\n\n```bash\nbash uninstall.sh\n```\n\nWindows:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\uninstall.ps1\n```\n\n## Contributing\n\nUse [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and validation, [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project standards, [SECURITY.md](SECURITY.md) for vulnerability reporting, and [CREDITS.md](CREDITS.md) for project credits. Agent-facing project context is also available in [llms.txt](llms.txt).\n\n## Related Projects\n\n- [`claude-seo`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fclaude-seo) - original Claude Code SEO skill suite\n- [`claude-blog`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fclaude-blog) - blog creation and optimization skill ecosystem\n- [`claude-ads`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fclaude-ads) - paid advertising audit skill suite\n- [`flow`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fflow) - evidence-led SEO framework for AI search\n- [`wp-mcp-ultimate`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fwp-mcp-ultimate) - WordPress MCP server\n\n## Credits\n\nSpecial thanks to [avalonreset](https:\u002F\u002Fgithub.com\u002Favalonreset) for making the Codex conversion possible and for creating the initial Codex SEO version that this repository builds on.\n\n## Attribution\n\nOriginal project and concept by [AgriciDaniel](https:\u002F\u002Fgithub.com\u002FAgriciDaniel) in [`claude-seo`](https:\u002F\u002Fgithub.com\u002FAgriciDaniel\u002Fclaude-seo). This Codex port preserves upstream SEO capabilities and adapts the runtime for Codex skills, TOML agents, plugin discovery, cache sharing, MCP extension setup, and API-safe wrappers.\n\nCodex SEO is released under the MIT License. FLOW prompt references retain their upstream attribution and licensing notices where included.\n","Codex SEO 是一个面向 Codex 的 SEO 技能套件，包含 26 个工作流和 24 个 TOML 代理配置文件。项目集成了 DataForSEO、Gemini、Google 和 Firecrawl 等多种工具，支持 GEO\u002FAEO、Core Web Vitals、结构化数据、反向链接、本地地图优化等功能，并生成确定性的报告。该项目使用 Python 编写，适用于需要进行技术 SEO 审计、页面分析、内容质量评估、E-E-A-T 优化、结构化数据标记、图像优化、站点地图架构、核心网页指标监测、地理定位、AI 搜索优化、反向链接管理、本地 SEO 和电子商务 SEO 等场景的专业人士或团队。",2,"2026-06-11 02:50:00","CREATED_QUERY"]