{
  "markdown": "# Ultimate SEO + GEO — LLM-Agnostic SEO Agent\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![AGENTS.md](https://img.shields.io/badge/AGENTS.md-compatible-blue)](https://agents.md)\n[![Version](https://img.shields.io/badge/version-1.12.8-green.svg)](CHANGELOG.md)\n[![LLM-Agnostic](https://img.shields.io/badge/LLM--Agnostic-7%2B%20platforms-purple.svg)](#platform-compatibility)\n\nThe definitive SEO and Generative Engine Optimization agent for AI coding tools. LLM-agnostic — works on any platform that reads `AGENTS.md`. Runs full site audits with scored findings, generates ready-to-deploy fixes, and optimizes content for both Google Search and AI search engines (Google AI Overviews, AI Mode, ChatGPT Search, Perplexity). Exports HTML, Excel, and PDF reports.\n\nWorks with **any AGENTS.md-compatible tool**: Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, Windsurf, Cline, Aider, Devin, and more.\n\n**Author:** [Myk Pono](https://mykpono.com) · [Lab](https://lab.mykpono.com) · [LinkedIn](https://www.linkedin.com/in/mykolaponomarenko/)\n\n---\n\n## What It Does\n\nGive it a URL and it returns a scored audit, prioritized action plan, and executable fixes — not vague advice.\n\n**Three modes, one skill:**\n\n| Mode | What It Does | Output |\n|---|---|---|\n| **Audit** | Fetches site, runs all checks, scores findings | SEO Health Score (0–100) + prioritized findings |\n| **Plan** | Converts findings into phased roadmap | Implementation table with effort/impact/owner |\n| **Execute** | Produces the actual fixes + verifies them | JSON-LD, meta rewrites, redirect maps, robots.txt |\n\nMost requests run all three in sequence. Skip to Mode 2 if you already have audit findings; skip to Mode 3 if you know exactly what to fix.\n\n### Who it’s for and what the bundled report does\n\nBuilt for **developers, founders, and marketers using AI coding agents** who want scripted checks plus guided fixes. `python scripts/generate_report.py <url>` aggregates many diagnostics in one HTML/Excel export; **by default** several checks use the **seed URL and modest crawl limits** (not a full-site Screaming Frog–style crawl). For broader link and canonical coverage, use `--crawl-deep` (capped depth/pages; slower and more load on the target host). For JS-rendered sites or very large audits, optional extensions (Firecrawl, DataForSEO) are documented in `references/optional-extensions-mcp.md`. Setup: `pip install -r requirements.txt` (optional API keys for PageSpeed and extensions).\n\n---\n\n## Coverage\n\n### SEO (25 Modules)\n\n- **Technical SEO** — Core Web Vitals (LCP/INP/CLS), crawlability, indexability, JavaScript rendering, security headers, mobile-first\n- **On-Page SEO** — Title tags, meta descriptions, H1s, URLs, canonicals\n- **Content & E-E-A-T** — Content quality scoring, author credentials, experience signals, readability, thin content detection, content pruning/refresh\n- **Schema Markup** — All active Schema.org types, deprecation-aware (HowTo, SpecialAnnouncement removed), JSON-LD generation and validation\n- **Keywords & Content Strategy** — Keyword research, topic clusters, content gaps, funnel mapping (TOFU/MOFU/BOFU), content brief generation\n- **Link Building** — Internal link audit, orphan page detection, anchor text analysis, external link quality hierarchy\n- **Local SEO** — Google Business Profile, NAP consistency, review strategy, LocalBusiness schema, citation building\n- **Maps Intelligence** — Geo-grid rank tracking, GBP completeness audit, review intelligence, competitor radius mapping, NAP consistency checking\n- **International SEO** — Hreflang audit, language code validation, bidirectional return tags\n- **Programmatic SEO** — Quality gates for pages at scale, thin content safeguards, template optimization\n- **E-commerce SEO** — Product + Offer schema validation, MerchantReturnPolicy, OfferShippingDetails, faceted navigation, EU compliance\n- **Site Migrations** — Pre/during/post migration checklists, redirect map validation, Change of Address tool\n- **SEO Drift Monitoring** — Baseline snapshots, 17-rule comparison engine (3 severity levels), history tracking, deployment checks\n- **Semantic Topic Clustering** — SERP-overlap clustering, hub-and-spoke architecture, internal link matrices\n- **Analytics & Reporting** — GA4/GSC setup, traffic drop diagnostics, CTR benchmarks, monthly maintenance, Google API tier system (Tier 0–2)\n\n### GEO (AI Search Optimization)\n\n- **Platform Coverage** — Google AI Overviews, Google AI Mode, ChatGPT Search, Perplexity, Bing Copilot\n- **Citability Scoring** — Passage-level optimization (134–167 word answer blocks), answer placement in first 60 words\n- **Brand Mention Strategy** — YouTube/Reddit/Wikipedia/LinkedIn correlation data, Wikidata entity setup\n- **AI Crawler Management** — robots.txt configuration for GPTBot, OAI-SearchBot, PerplexityBot, ClaudeBot\n- **llms.txt** — Template generation for the emerging AI content standard\n- **RSL 1.0** — Machine-readable AI licensing (December 2025 standard)\n\n---\n\n## Platform Compatibility\n\n| Platform | How It Loads Instructions | Script Execution | Setup |\n|---|---|---|---|\n| **OpenAI Codex** | `AGENTS.md` auto-loaded (32 KiB limit) | Full (shell access) | Clone repo, start coding |\n| **Google Gemini CLI** | `GEMINI.md` → imports `AGENTS.md` | Full (shell access) | Clone repo, start coding |\n| **Claude Code** | Plugin marketplace + `SKILL.md` | Full (shell access) | `/plugin install` (see below) |\n| **Cursor IDE** | `AGENTS.md` + `.cursor/rules/` + skill auto-discovery | Full (shell access) | Clone repo or install skill |\n| **GitHub Copilot** | `AGENTS.md` + `.github/copilot-instructions.md` | Full (agent mode) | Clone repo, start coding |\n| **Windsurf** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |\n| **Cline** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |\n| **Aider / Devin / Goose / Amp** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |\n| **ChatGPT Custom GPT** | Uploaded instructions + knowledge files | Limited (no scripts) | See `chatgpt/README.md` |\n| **Claude Desktop (claude.ai)** | Upload `SKILL.md` to Project Knowledge | No shell access | Manual upload |\n\n`AGENTS.md` is the [cross-tool standard](https://agents.md) (Linux Foundation, 20+ tools). One file covers all AGENTS.md-compatible platforms.\n\n> **Codex users — instruction budget.** Codex loads instruction files up to `project_doc_max_bytes`\n> (**32 KiB** by default) and **truncates silently** past that point: no warning in the TUI, `/stats`,\n> `exec`, or the VS Code extension, and everything after the cutoff is never sent to the model.\n>\n> That budget is **combined across every instruction file Codex loads in the directory hierarchy** —\n> this repo's `AGENTS.md` *plus* any `AGENTS.md` of your own further up the tree. `AGENTS.md` here is\n> kept under the default on its own, and a test (`tests/test_agents_md_size.py`) enforces it, but if\n> you also carry your own instruction files you may still hit the cap. Raise it in `~/.codex/config.toml`:\n>\n> ```toml\n> project_doc_max_bytes = 65536\n> ```\n>\n> Symptom to watch for: Codex behaving as though it has never heard of §§22–25 (drift monitoring,\n> semantic clustering, e-commerce, maps) — those sit at the end of the file and truncate first.\n\n## Installation\n\n### Any AGENTS.md-Compatible Tool (Codex, Gemini CLI, Copilot, Windsurf, Cline, Aider, etc.)\n\nClone the repo into your project or working directory. The tool auto-discovers `AGENTS.md`:\n\n```bash\ngit clone https://github.com/mykpono/ultimate-seo-geo.git\ncd ultimate-seo-geo\npip install -r requirements.txt\n```\n\nThat's it. Open the folder in your tool and start asking for SEO audits.\n\n### Claude Code — Plugin Marketplace\n\n**Use [Claude Code](https://code.claude.com/)** (the terminal-based Claude product). The lines below are **slash commands** you type in the **Claude Code chat**, not in macOS Terminal or zsh.\n\nIn Claude Code, run:\n\n```text\n/plugin marketplace add mykpono/ultimate-seo-geo\n/plugin install ultimate-seo-geo@ultimate-seo-geo\n```\n\nOr install directly without adding the marketplace first:\n\n```text\n/plugin install https://github.com/mykpono/ultimate-seo-geo.git\n```\n\n#### Updating the plugin after a GitHub release\n\nClaude Code caches the marketplace clone locally — it does **not** auto-pull new commits. Pick one approach:\n\n**Option A — Update the cache (fastest):**\n\n```bash\ncd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull\n```\n\nThen restart your Claude session (or run `/reload-plugins` in Claude Code).\n\n**Option B — Full reinstall:**\n\n```text\n/plugin uninstall ultimate-seo-geo\n/plugin marketplace add mykpono/ultimate-seo-geo\n/plugin install ultimate-seo-geo@ultimate-seo-geo\n```\n\n**For maintainers** — before pushing a release, verify plugin sync:\n\n```bash\npython3 scripts/check-plugin-sync.py\n```\n\n### Claude Code — Manual skill install (global)\n\n```bash\ncp -r ultimate-seo-geo ~/.claude/skills/\n```\n\n### Cursor IDE\n\nCursor reads `AGENTS.md` automatically from the repo root. For the full skill experience with progressive disclosure, install to the skills directory:\n\n```bash\nrsync -a --delete --exclude='.git/' --exclude='__pycache__/' --exclude='*.pyc' --exclude='.venv/' \\\n  /path/to/ultimate-seo-geo/ ~/.claude/skills/seo/\n```\n\n### ChatGPT Custom GPT\n\nChatGPT Custom GPTs cannot read repo files — they need uploaded knowledge files. See [`chatgpt/README.md`](chatgpt/README.md) for step-by-step setup.\n\n### Claude Desktop App (claude.ai)\n\nThe Claude desktop app does not load skills from `~/.claude/skills/`. Instead:\n\n1. Open a **Project** in claude.ai\n2. Go to **Project Knowledge**\n3. Upload `SKILL.md` as a file, or paste its contents into custom instructions\n\n---\n\n## Usage Examples\n\n**Full site audit:**\n> \"Audit mysite.com — we've seen a traffic drop over the past 3 months\"\n\n**Schema generation:**\n> \"Generate the complete schema markup for my SaaS product page at app.example.com\"\n\n**Local SEO:**\n> \"I run a plumbing company in Austin, TX. We're not showing up for 'plumber near me'. What's wrong?\"\n\n**GEO optimization:**\n> \"How do I get cited by ChatGPT and Perplexity for our core product keywords?\"\n\n**Site migration:**\n> \"We're moving from Magento to Shopify — 3,000 product pages. What do we need for SEO?\"\n\n---\n\n## Architecture\n\n```\nultimate-seo-geo/\n├── AGENTS.md             ← Universal entrypoint (~27KB, under 32KB Codex limit)\n│                           Auto-loaded by Codex, Gemini, Copilot, Windsurf, Cline, etc.\n├── GEMINI.md             ← Gemini CLI entrypoint (imports AGENTS.md)\n├── SKILL.md              ← Routing shell (~230 lines): §0, guardrails, procedure index\n│\n├── .github/\n│   └── copilot-instructions.md  ← GitHub Copilot supplementary context\n│\n├── chatgpt/              ← ChatGPT Custom GPT bundle\n│   ├── instructions.txt     Condensed instructions (under 8K chars)\n│   ├── README.md            Setup guide\n│   └── copy-knowledge-files.sh  Copies SKILL + references/ + references/procedures/\n│\n├── references/            ← Domain knowledge + procedures (load on demand)\n│   ├── procedures/        ← Step-by-step §1–§25 (split from former monolithic SKILL.md)\n│   │   ├── 22-drift-monitoring.md       SEO drift baseline/compare/history\n│   │   ├── 23-semantic-clustering.md    SERP-overlap topic clustering\n│   │   ├── 24-ecommerce-seo.md          E-commerce schema + faceted nav\n│   │   └── 25-maps-intelligence.md      Geo-grid + GBP + review intel\n│   ├── thinking-framework.md  PERCEIVE → ANALYZE → VALIDATE → ACT methodology\n│   ├── ai-search-geo.md     GEO signals, platform data, brand strategy\n│   ├── technical-checklist.md  CWV fixes, JS SEO, IndexNow\n│   ├── schema-types.md       All Schema.org types + templates\n│   ├── eeat-framework.md     E-E-A-T scoring, spam categories\n│   ├── core-eeat-framework.md  80-item CORE-EEAT content benchmark\n│   ├── cite-domain-rating.md   40-item CITE domain authority\n│   ├── entity-optimization.md  Entity / Knowledge Graph checklist\n│   ├── ...and 14 more topical files\n│\n├── scripts/               ← 46 bundled Python scripts\n│   ├── generate_report.py    Full-site HTML/XLSX/PDF dashboard (runs all scripts)\n│   ├── validate_schema.py    JSON-LD validation\n│   ├── robots_checker.py     AI crawler access check\n│   ├── drift_monitor.py      SEO drift baseline, compare, history, report\n│   ├── topic_cluster.py      SERP-overlap topic clustering\n│   ├── content_brief.py      Content brief generation\n│   ├── ecommerce_schema.py   E-commerce schema validation\n│   ├── google_api_tier.py    Google API credential detection (Tier 0–2)\n│   ├── maps_checker.py       Advanced local SEO / GBP audit\n│   ├── pdf_charts.py         SVG chart generation for PDF reports\n│   ├── pdf_template.py       Professional A4 PDF template\n│   ├── ...and 35 more\n│\n└── evals/                 ← 15 scenarios, 63 assertions + golden fixtures\n    ├── evals.json\n    └── fixtures/\n```\n\n**Progressive disclosure for cross-platform support:**\n- **Layer 1** — `AGENTS.md` (~32KB, held under Codex's 32 KiB default): auto-loaded by AGENTS.md-compatible tools. Routing index, condensed procedures, quality gates. The full script index lives in `references/audit-script-matrix.md`.\n- **Layer 2** — `SKILL.md` (routing shell) + `references/procedures/*.md` (detailed steps per §, now §1–§25) + topical `references/*.md` + `scripts/`: load only what the task needs.\n\nFor Claude Code and Cursor, `SKILL.md` is loaded natively as a skill (small shell); hosts pull `references/procedures/` when a section’s detail is required. Other platforms use `AGENTS.md` plus explicit reads of procedure files as needed.\n\n**Claude Code plugin install:** `bash setup-plugin.sh` mirrors `SKILL.md`, `AGENTS.md`, `GEMINI.md`, `references/`, `scripts/` (audit scripts only), and `evals/` into `plugins/.../skills/ultimate-seo-geo/` so `python scripts/...` paths work after marketplace install.\n\n### Claude Code: why two `.claude-plugin/` folders?\n\nDo **not** merge them into one directory. This repo follows the layout Claude Code expects for a **GitHub marketplace** plus an **installable plugin**:\n\n| Location | File | Role |\n|----------|------|------|\n| **Repo root** | `.claude-plugin/marketplace.json` | **Marketplace catalog** — lists plugins, owner metadata, and each plugin’s `source` path (here: `./plugins/ultimate-seo-geo`). |\n| **Under that path** | `plugins/ultimate-seo-geo/.claude-plugin/plugin.json` | **Plugin manifest** for the package at `source` — name, version, keywords, repository URL, etc. |\n\nWhen someone runs `/plugin marketplace add mykpono/ultimate-seo-geo`, the tool reads the **root** catalog, then resolves **`source`** and loads **that folder’s** `plugin.json`. Putting both JSON files in a single `.claude-plugin/` would break that resolution. A repo that is **only** a plugin (no marketplace) can use a single plugin manifest at the root, but then you typically would **not** use the marketplace flow for that repo.\n\n---\n\n## Scripts\n\n**Bundled in the plugin:** **46** diagnostic scripts. **`check-plugin-sync.py`**, **`check_github_release.py`**, and **`check_version_sync.py`** are repo-only for CI and are not included in the bundle. Python 3.8+; install dependencies with:\n\n```bash\npip install -r requirements.txt\n```\n\nOn **PEP 668**–managed Python (e.g. Homebrew), use a venv first: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`, then run scripts with `.venv/bin/python`.\n\nPreflight (optional): `python scripts/requirements-check.py` or `python scripts/requirements-check.py --json` — exits non-zero if `requests` / `beautifulsoup4` are missing.\n\n**Eval regression (optional):** save a model reply to `transcript.txt`, then `python scripts/score_eval_transcript.py --eval-id 1 --text-file transcript.txt`. CI runs `python scripts/score_eval_transcript.py --all-fixtures` against `evals/fixtures/`.\n\nRun the full-site report to start any audit:\n\n```bash\npython scripts/generate_report.py https://example.com --output seo-report.html\n```\n\n| Script | Purpose |\n|---|---|\n| `generate_report.py` | Full-site HTML dashboard — bundled analysis pipeline |\n| `requirements-check.py` | Preflight: `requests` + `beautifulsoup4` installed (`--json`) |\n| `score_eval_transcript.py` | Score replies vs `evals/evals.json` (`--eval-id` or `--all-fixtures`) |\n| `meta_lengths_checker.py` | Title / meta description / H1 lengths (`--url` or local HTML) |\n| `validate_schema.py` | Validates JSON-LD blocks (pure stdlib) |\n| `robots_checker.py` | robots.txt rules + AI crawler allow/block status |\n| `pagespeed.py` | Core Web Vitals via PageSpeed Insights API |\n| `hreflang_checker.py` | All 8 hreflang rules + bidirectional return tags |\n| `internal_links.py` | Link graph, orphan pages, anchor text, crawl depth |\n| `broken_links.py` | 4xx/5xx broken links + redirect counts |\n| `redirect_checker.py` | Full redirect chain analysis — loops and mixed HTTP/HTTPS |\n| `security_headers.py` | HSTS, CSP, X-Frame-Options — weighted score |\n| `entity_checker.py` | Wikidata, Wikipedia, sameAs entity signals |\n| `llms_txt_checker.py` | llms.txt presence + format validation |\n| `indexnow_checker.py` | IndexNow key file validation + ping |\n| `social_meta.py` | Open Graph + Twitter Card validation |\n| `readability.py` | Flesch-Kincaid grade + sentence stats |\n| `duplicate_content.py` | Near-duplicate detection |\n| `article_seo.py` | CMS-aware article structure + keyword analysis |\n| `link_profile.py` | Link equity distribution |\n| `finding_verifier.py` | Deduplicates findings across a full audit |\n| `fetch_page.py` | Fetch and save raw HTML (utility) |\n| `parse_html.py` | Extract titles, H1s, meta, canonical, schema (utility) |\n| `sitemap_checker.py` | Sitemap discovery via robots.txt + first sitemap sanity |\n| `local_signals_checker.py` | LocalBusiness / tel / address signals on a URL |\n| `image_checker.py` | Image alt coverage from saved HTML |\n| `canonical_checker.py` | Canonical tag validation |\n| `content_quality.py` | E-E-A-T risk detection (filler, citation gaps, missing author) |\n| `content_brief.py` | Content brief generation from competitor analysis |\n| `drift_monitor.py` | SEO drift baseline, compare, history, report (17 rules) |\n| `topic_cluster.py` | SERP-overlap topic clustering (CSV input) |\n| `ecommerce_schema.py` | E-commerce schema validation (Product, Offer, Return, Shipping) |\n| `maps_checker.py` | Advanced local SEO / GBP schema audit |\n| `google_api_tier.py` | Detect available Google API credentials (Tier 0–2) |\n| `crux_history.py` | CrUX History API — historical CWV data (Tier 0) |\n| `gsc_query.py` | Google Search Console queries (Tier 1, OAuth) |\n| `gsc_export.py` | GSC data export (Tier 1, OAuth) |\n| `ga4_report.py` | GA4 organic traffic data (Tier 2, OAuth) |\n| `pdf_charts.py` | SVG chart generation for PDF reports (module) |\n| `pdf_template.py` | Professional A4 PDF template with cover + TOC (module) |\n| `render_page.py` | SPA-aware rendering (Playwright optional) |\n| `url_safety.py` | Outbound URL validation (SSRF prevention) |\n| `crawl_adapter.py` | Pluggable crawl backend (requests/firecrawl/playwright) |\n| `site_mapper.py` | URL discovery via sitemap + crawl |\n| `backlink_analyzer.py` | 7-section backlink audit (CSV/API data) |\n| `programmatic_seo_auditor.py` | Quality gates for pages at scale |\n\n---\n\n## Eval Results\n\nBenchmarked against baseline (no skill) across multiple scenarios (see `evals/evals.json`; **15** prompts, **63** assertions):\n\n| Metric | With Skill | Without Skill | Delta |\n|---|---|---|---|\n| Pass rate | **100%** | 87% | **+13 pts** |\n| Avg time | 103s | 54s | +49s |\n| Avg tokens | 83K | 64K | +19K |\n\nThe skill adds ~50 seconds and ~19K tokens per task, but achieves 100% on structured output requirements (finding format, correct schema types, health scoring) where the baseline misses.\n\n**Test scenarios include:** YMYL publisher audit, local HVAC + schema, SaaS schema, migration plan, recipe content (no URL), negative PPC, news/paywall, scoped robots+sitemap-only, international hreflang, pre-launch strategy (no live site), traffic drop routing, GEO platform routing, execute mode risk gate (robots.txt), evaluator-optimizer fabrication check. **Automated check:** `python scripts/score_eval_transcript.py --all-fixtures`.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| \"This plugin doesn't have any skills or agents\" | Marketplace not cloned to local cache | Run `/plugin marketplace add mykpono/ultimate-seo-geo` then `/plugin install ultimate-seo-geo@ultimate-seo-geo`, or manually clone: `git clone https://github.com/mykpono/ultimate-seo-geo.git ~/.claude/plugins/marketplaces/ultimate-seo-geo` |\n| \"Could not load skill files\" | Stale cache after a GitHub update | `cd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull`, then restart session |\n| Plugin enabled but skill not appearing | Known Claude Code bug — `/reload-plugins` sometimes misses new skills ([#35641](https://github.com/anthropics/claude-code/issues/35641)) | Fully restart your Claude session |\n| `zsh: no such file or directory: /plugin` | `/plugin` is a Claude Code slash command, not a shell command | Run `claude` first to start a Claude Code session, then type the `/plugin` commands inside it |\n| Only some skills downloaded | Incomplete cache clone ([#35989](https://github.com/anthropics/claude-code/issues/35989)) | Delete `~/.claude/plugins/marketplaces/ultimate-seo-geo` and re-clone |\n\n---\n\n## What It Doesn't Do\n\nThis skill focuses on organic search and AI search visibility. It does not cover:\n\n- PPC / Google Ads / paid advertising\n- Social media management or posting\n- General marketing strategy\n- Web design or UX (beyond SEO-relevant elements)\n- Content writing (it generates briefs and meta tags, not full articles)\n\n---\n\n## Credits\n\nBuilt on research, patterns, and prior work from:\n\n- **[Bhanunamikaze/Agentic-SEO-Skill](https://github.com/Bhanunamikaze/Agentic-SEO-Skill)** — SEO analysis toolkit architecture, specialist agent patterns, technical SEO audit framework\n- **[AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)** — GEO platform citation data, DataForSEO integration patterns, AI crawler detection tables, subagent delegation architecture\n\n---\n\n## Maintainers\n\nReleases, version alignment, and syncing the plugin skill tree: [RELEASE.md](RELEASE.md).\n\n---\n\n## License\n\n[MIT](LICENSE) — use it, modify it, ship it.\n",
  "bytes": 22459,
  "sha": "2ed5d179df4544480f12dafd68a638bb884937d30f4f358eab50bfe8168d372f",
  "repo_slug": "mykpono/ultimate-seo-geo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_mykpono_ultimate_seo_geo_ultimate_seo_ge_dbe23a61/readme"
}