Skip to content
Back to search

ultimate-seo-geo

The definitive SEO + GEO skill for Claude. Full site audits with scored findings, AI search optimization (Google AI Overviews, ChatGPT, Perplexity), schema generation, E-E-A-T assessment, and 20 diagnostic scripts. Three modes: Audit → Plan → Execute.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mykpono/ultimate-seo-geo with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mykpono/ultimate-seo-geo'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mykpono--ultimate-seo-geo/badge.svg)](/listings/mykpono--ultimate-seo-geo)

HTML

<a href="/listings/mykpono--ultimate-seo-geo"><img src="/api/listings/mykpono--ultimate-seo-geo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Any AGENTS.md-Compatible Tool (Codex, Gemini CLI, Copilot, Windsurf, Cline, Aider, etc.)

Clone the repo into your project or working directory. The tool auto-discovers `AGENTS.md`:

git clone https://github.com/mykpono/ultimate-seo-geo.git
cd ultimate-seo-geo
pip install -r requirements.txt

That's it. Open the folder in your tool and start asking for SEO audits.

Claude Code — Plugin Marketplace

**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.

In Claude Code, run:

/plugin marketplace add mykpono/ultimate-seo-geo
/plugin install ultimate-seo-geo@ultimate-seo-geo

Or install directly without adding the marketplace first:

/plugin install https://github.com/mykpono/ultimate-seo-geo.git

Updating the plugin after a GitHub release

Claude Code caches the marketplace clone locally — it does **not** auto-pull new commits. Pick one approach:

**Option A — Update the cache (fastest):**

cd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull

Then restart your Claude session (or run `/reload-plugins` in Claude Code).

**Option B — Full reinstall:**

/plugin uninstall ultimate-seo-geo
/plugin marketplace add mykpono/ultimate-seo-geo
/plugin install ultimate-seo-geo@ultimate-seo-geo

**For maintainers** — before pushing a release, verify plugin sync:

python3 scripts/check-plugin-sync.py

Claude Code — Manual skill install (global)

cp -r ultimate-seo-geo ~/.claude/skills/

Cursor IDE

Cursor reads `AGENTS.md` automatically from the repo root. For the full skill experience with progressive disclosure, install to the skills directory:

rsync -a --delete --exclude='.git/' --exclude='__pycache__/' --exclude='*.pyc' --exclude='.venv/' \
  /path/to/ultimate-seo-geo/ ~/.claude/skills/seo/

ChatGPT Custom GPT

ChatGPT Custom GPTs cannot read repo files — they need uploaded knowledge files. See [`chatgpt/README.md`](chatgpt/README.md) for step-by-step setup.

Claude Desktop App (claude.ai)

The Claude desktop app does not load skills from `~/.claude/skills/`. Instead:

1. Open a **Project** in claude.ai 2. Go to **Project Knowledge** 3. Upload `SKILL.md` as a file, or paste its contents into custom instructions

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 39 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "ultimate-seo-geo",
  4. "description": "SEO + GEO audits for AI coding agents: health scores, technical checks, Schema.org, E-E-A-T, AI search visibility. 65 scripts; HTML/XLSX/PDF. Default reports use seed URL + capped crawls; generate_report.py --crawl-deep for broader link/canonical scans. Optional MCP (Firecrawl, DataForSEO, Ahrefs, SE Ranking). Progressive disclosure via SKILL + references/procedures/. LLM-agnostic.",
  5. "owner": {
  6. "name": "Myk Pono"
  7. },
  8. "metadata": {
  9. "version": "1.22.1"
  10. },
  11. "plugins": [
  12. {
  13. "name": "ultimate-seo-geo",
  14. "description": "Scored SEO audits for developers/marketers using AI agents: technical health, JSON-LD, E-E-A-T, backlinks, GEO (AI Overviews, ChatGPT, Perplexity). 65 scripts; HTML/Excel/PDF. E-commerce schema, drift monitoring, topic clustering, Google API tiers, maps intelligence. Optional MCP (Firecrawl, DataForSEO). Parallel workers: agents/PARALLEL-AUDIT.md. Modes: Audit → Plan → Execute.",
  15. "version": "1.22.1",
  16. "author": {
  17. "name": "Myk Pono",
  18. "url": "https://lab.mykpono.com"
  19. },
  20. "source": "./plugins/ultimate-seo-geo",
  21. "category": "productivity",
  22. "homepage": "https://github.com/mykpono/ultimate-seo-geo",
  23. "repository": "https://github.com/mykpono/ultimate-seo-geo",
  24. "license": "MIT",
  25. "keywords": [
  26. "seo",
  27. "geo",
  28. "audit",
  29. "schema",
  30. "e-e-a-t",
  31. "ai-search",
  32. "structured-data",
  33. "mcp",
  34. "pdf",
  35. "parallel-agents"
  36. ]
  37. }
  38. ]
  39. }
README.md · README · 422 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Ultimate SEO + GEO — LLM-Agnostic SEO Agent
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  3. [![AGENTS.md](https://img.shields.io/badge/AGENTS.md-compatible-blue)](https://agents.md)
  4. [![Version](https://img.shields.io/badge/version-1.22.1-green.svg)](CHANGELOG.md)
  5. [![LLM-Agnostic](https://img.shields.io/badge/LLM--Agnostic-7%2B%20platforms-purple.svg)](#platform-compatibility)
  6. The 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.
  7. Works with **any AGENTS.md-compatible tool**: Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, Windsurf, Cline, Aider, Devin, and more.
  8. **Author:** [Myk Pono](https://mykpono.com) · [Lab](https://lab.mykpono.com) · [LinkedIn](https://www.linkedin.com/in/mykolaponomarenko/)
  9. ---
  10. ## What It Does
  11. Give it a URL and it returns a scored audit, prioritized action plan, and executable fixes — not vague advice.
  12. **Three modes, one skill:**
  13. | Mode | What It Does | Output |
  14. |---|---|---|
  15. | **Audit** | Fetches site, runs all checks, scores findings | SEO Health Score (0–100) + prioritized findings |
  16. | **Plan** | Converts findings into phased roadmap | Implementation table with effort/impact/owner |
  17. | **Execute** | Produces the actual fixes + verifies them | JSON-LD, meta rewrites, redirect maps, robots.txt |
  18. Most 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.
  19. ### Who it’s for and what the bundled report does
  20. Built 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).
  21. ---
  22. ## Coverage
  23. ### SEO (25 Modules)
  24. - **Technical SEO** — Core Web Vitals (LCP/INP/CLS), crawlability, indexability, JavaScript rendering, security headers, mobile-first
  25. - **On-Page SEO** — Title tags, meta descriptions, H1s, URLs, canonicals
  26. - **Content & E-E-A-T** — Content quality scoring, author credentials, experience signals, readability, thin content detection, content pruning/refresh
  27. - **Schema Markup** — All active Schema.org types, deprecation-aware (HowTo, SpecialAnnouncement removed), JSON-LD generation and validation
  28. - **Keywords & Content Strategy** — Keyword research, topic clusters, content gaps, funnel mapping (TOFU/MOFU/BOFU), content brief generation
  29. - **Link Building** — Internal link audit, orphan page detection, anchor text analysis, external link quality hierarchy
  30. - **Local SEO** — Google Business Profile, NAP consistency, review strategy, LocalBusiness schema, citation building
  31. - **Maps Intelligence** — Geo-grid rank tracking, GBP completeness audit, review intelligence, competitor radius mapping, NAP consistency checking
  32. - **International SEO** — Hreflang audit, language code validation, bidirectional return tags
  33. - **Programmatic SEO** — Quality gates for pages at scale, thin content safeguards, template optimization
  34. - **E-commerce SEO** — Product + Offer schema validation, MerchantReturnPolicy, OfferShippingDetails, faceted navigation, EU compliance
  35. - **Site Migrations** — Pre/during/post migration checklists, redirect map validation, Change of Address tool
  36. - **SEO Drift Monitoring** — Baseline snapshots, 17-rule comparison engine (3 severity levels), history tracking, deployment checks
  37. - **Semantic Topic Clustering** — SERP-overlap clustering, hub-and-spoke architecture, internal link matrices
  38. - **Analytics & Reporting** — GA4/GSC setup, traffic drop diagnostics, CTR benchmarks, monthly maintenance, Google API tier system (Tier 0–2)
  39. ### GEO (AI Search Optimization)
  40. - **Platform Coverage** — Google AI Overviews, Google AI Mode, ChatGPT Search, Perplexity, Bing Copilot
  41. - **Citability Scoring** — Passage-level optimization (134–167 word answer blocks), answer placement in first 60 words
  42. - **Brand Mention Strategy** — YouTube/Reddit/Wikipedia/LinkedIn correlation data, Wikidata entity setup
  43. - **AI Crawler Management** — robots.txt checks by crawler role: search (OAI-SearchBot, Claude-SearchBot, PerplexityBot), user fetch, and training (GPTBot, ClaudeBot)
  44. - **llms.txt** — Template generation for the emerging AI content standard
  45. - **RSL 1.0** — Machine-readable AI licensing (December 2025 standard)
  46. ---
  47. ## Platform Compatibility
  48. | Platform | How It Loads Instructions | Script Execution | Setup |
  49. |---|---|---|---|
  50. | **OpenAI Codex** | `AGENTS.md` auto-loaded (32 KiB limit) | Full (shell access) | Clone repo, start coding |
  51. | **Google Gemini CLI** | `GEMINI.md` → imports `AGENTS.md` | Full (shell access) | Clone repo, start coding |
  52. | **Claude Code** | Plugin marketplace + `SKILL.md` | Full (shell access) | `/plugin install` (see below) |
  53. | **Cursor IDE** | `AGENTS.md` + `.cursor/rules/` + skill auto-discovery | Full (shell access) | Clone repo or install skill |
  54. | **GitHub Copilot** | `AGENTS.md` + `.github/copilot-instructions.md` | Full (agent mode) | Clone repo, start coding |
  55. | **Windsurf** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |
  56. | **Cline** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |
  57. | **Aider / Devin / Goose / Amp** | `AGENTS.md` auto-loaded | Full (shell access) | Clone repo, start coding |
  58. | **ChatGPT Custom GPT** | Uploaded instructions + knowledge files | Limited (no scripts) | See `chatgpt/README.md` |
  59. | **Claude Desktop (claude.ai)** | Upload `SKILL.md` to Project Knowledge | No shell access | Manual upload |
  60. `AGENTS.md` is the [cross-tool standard](https://agents.md) (Linux Foundation, 20+ tools). One file covers all AGENTS.md-compatible platforms.
  61. > **Codex users — instruction budget.** Codex loads instruction files up to `project_doc_max_bytes`
  62. > (**32 KiB** by default) and **truncates silently** past that point: no warning in the TUI, `/stats`,
  63. > `exec`, or the VS Code extension, and everything after the cutoff is never sent to the model.
  64. >
  65. > That budget is **combined across every instruction file Codex loads in the directory hierarchy** —
  66. > this repo's `AGENTS.md` *plus* any `AGENTS.md` of your own further up the tree. `AGENTS.md` here is
  67. > kept under the default on its own, and a test (`tests/test_agents_md_size.py`) enforces it, but if
  68. > you also carry your own instruction files you may still hit the cap. Raise it in `~/.codex/config.toml`:
  69. >
  70. > ```toml
  71. > project_doc_max_bytes = 65536
  72. > ```
  73. >
  74. > Symptom to watch for: Codex behaving as though it has never heard of §§22–25 (drift monitoring,
  75. > semantic clustering, e-commerce, maps) — those sit at the end of the file and truncate first.
  76. ## Installation
  77. ### Any AGENTS.md-Compatible Tool (Codex, Gemini CLI, Copilot, Windsurf, Cline, Aider, etc.)
  78. Clone the repo into your project or working directory. The tool auto-discovers `AGENTS.md`:
  79. ```bash
  80. git clone https://github.com/mykpono/ultimate-seo-geo.git
  81. cd ultimate-seo-geo
  82. pip install -r requirements.txt
  83. ```
  84. That's it. Open the folder in your tool and start asking for SEO audits.
  85. ### Claude Code — Plugin Marketplace
  86. **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.
  87. In Claude Code, run:
  88. ```text
  89. /plugin marketplace add mykpono/ultimate-seo-geo
  90. /plugin install ultimate-seo-geo@ultimate-seo-geo
  91. ```
  92. Or install directly without adding the marketplace first:
  93. ```text
  94. /plugin install https://github.com/mykpono/ultimate-seo-geo.git
  95. ```
  96. #### Updating the plugin after a GitHub release
  97. Claude Code caches the marketplace clone locally — it does **not** auto-pull new commits. Pick one approach:
  98. **Option A — Update the cache (fastest):**
  99. ```bash
  100. cd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull
  101. ```
  102. Then restart your Claude session (or run `/reload-plugins` in Claude Code).
  103. **Option B — Full reinstall:**
  104. ```text
  105. /plugin uninstall ultimate-seo-geo
  106. /plugin marketplace add mykpono/ultimate-seo-geo
  107. /plugin install ultimate-seo-geo@ultimate-seo-geo
  108. ```
  109. **For maintainers** — before pushing a release, verify plugin sync:
  110. ```bash
  111. python3 scripts/check-plugin-sync.py
  112. ```
  113. ### Claude Code — Manual skill install (global)
  114. ```bash
  115. cp -r ultimate-seo-geo ~/.claude/skills/
  116. ```
  117. ### Cursor IDE
  118. Cursor reads `AGENTS.md` automatically from the repo root. For the full skill experience with progressive disclosure, install to the skills directory:
  119. ```bash
  120. rsync -a --delete --exclude='.git/' --exclude='__pycache__/' --exclude='*.pyc' --exclude='.venv/' \
  121. /path/to/ultimate-seo-geo/ ~/.claude/skills/seo/
  122. ```
  123. ### ChatGPT Custom GPT
  124. ChatGPT Custom GPTs cannot read repo files — they need uploaded knowledge files. See [`chatgpt/README.md`](chatgpt/README.md) for step-by-step setup.
  125. ### Claude Desktop App (claude.ai)
  126. The Claude desktop app does not load skills from `~/.claude/skills/`. Instead:
  127. 1. Open a **Project** in claude.ai
  128. 2. Go to **Project Knowledge**
  129. 3. Upload `SKILL.md` as a file, or paste its contents into custom instructions
  130. ---
  131. ## Usage Examples
  132. **Full site audit:**
  133. > "Audit mysite.com — we've seen a traffic drop over the past 3 months"
  134. **Schema generation:**
  135. > "Generate the complete schema markup for my SaaS product page at app.example.com"
  136. **Local SEO:**
  137. > "I run a plumbing company in Austin, TX. We're not showing up for 'plumber near me'. What's wrong?"
  138. **GEO optimization:**
  139. > "How do I get cited by ChatGPT and Perplexity for our core product keywords?"
  140. **Site migration:**
  141. > "We're moving from Magento to Shopify — 3,000 product pages. What do we need for SEO?"
  142. ---
  143. ## Architecture
  144. ```
  145. ultimate-seo-geo/
  146. ├── AGENTS.md ← Universal entrypoint (~27KB, under 32KB Codex limit)
  147. │ Auto-loaded by Codex, Gemini, Copilot, Windsurf, Cline, etc.
  148. ├── GEMINI.md ← Gemini CLI entrypoint (imports AGENTS.md)
  149. ├── SKILL.md ← Routing shell (~230 lines): §0, guardrails, procedure index
  150. │
  151. ├── .github/
  152. │ └── copilot-instructions.md ← GitHub Copilot supplementary context
  153. │
  154. ├── chatgpt/ ← ChatGPT Custom GPT bundle
  155. │ ├── instructions.txt Condensed instructions (under 8K chars)
  156. │ ├── README.md Setup guide
  157. │ └── copy-knowledge-files.sh Copies SKILL + references/ + references/procedures/
  158. │
  159. ├── references/ ← Domain knowledge + procedures (load on demand)
  160. │ ├── procedures/ ← Step-by-step §1–§26 (split from former monolithic SKILL.md)
  161. │ │ ├── 22-drift-monitoring.md SEO drift baseline/compare/history
  162. │ │ ├── 23-semantic-clustering.md SERP-overlap topic clustering
  163. │ │ ├── 24-ecommerce-seo.md E-commerce schema + faceted nav
  164. │ │ └── 25-maps-intelligence.md Geo-grid + GBP + review intel
  165. │ ├── thinking-framework.md PERCEIVE → ANALYZE → VALIDATE → ACT methodology
  166. │ ├── ai-search-geo.md GEO signals, platform data, brand strategy
  167. │ ├── technical-checklist.md CWV fixes, JS SEO, IndexNow
  168. │ ├── schema-types.md All Schema.org types + templates
  169. │ ├── eeat-framework.md E-E-A-T scoring, spam categories
  170. │ ├── core-eeat-framework.md 80-item CORE-EEAT content benchmark
  171. │ ├── cite-domain-rating.md 40-item CITE domain authority
  172. │ ├── entity-optimization.md Entity / Knowledge Graph checklist
  173. │ ├── ...and 14 more topical files
  174. │
  175. ├── scripts/ ← bundled Python scripts
  176. │ ├── generate_report.py Full-site HTML/XLSX/PDF report (runs all scripts)
  177. │ ├── validate_schema.py JSON-LD validation
  178. │ ├── robots_checker.py AI crawler access check
  179. │ ├── drift_monitor.py SEO drift baseline, compare, history, report
  180. │ ├── topic_cluster.py SERP-overlap topic clustering
  181. │ ├── content_brief.py Content brief generation
  182. │ ├── ecommerce_schema.py E-commerce schema validation
  183. │ ├── google_api_tier.py Google API credential detection (Tier 0–2)
  184. │ ├── google_auth.py Search Console sign-in: setup, login, status, logout
  185. │ ├── maps_checker.py Advanced local SEO / GBP audit
  186. │ ├── pdf_charts.py SVG chart generation for PDF reports
  187. │ ├── pdf_template.py Professional A4 PDF template
  188. │ ├── ...and 43 more
  189. │
  190. └── evals/ ← 17 scenarios, 74 assertions + golden fixtures
  191. ├── evals.json
  192. └── fixtures/
  193. ```
  194. **Progressive disclosure for cross-platform support:**
  195. - **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`.
  196. - **Layer 2** — `SKILL.md` (routing shell) + `references/procedures/*.md` (detailed steps per §, now §1–§26) + topical `references/*.md` + `scripts/`: load only what the task needs.
  197. For 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.
  198. **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.
  199. ### Claude Code: why two `.claude-plugin/` folders?
  200. Do **not** merge them into one directory. This repo follows the layout Claude Code expects for a **GitHub marketplace** plus an **installable plugin**:
  201. | Location | File | Role |
  202. |----------|------|------|
  203. | **Repo root** | `.claude-plugin/marketplace.json` | **Marketplace catalog** — lists plugins, owner metadata, and each plugin’s `source` path (here: `./plugins/ultimate-seo-geo`). |
  204. | **Under that path** | `plugins/ultimate-seo-geo/.claude-plugin/plugin.json` | **Plugin manifest** for the package at `source` — name, version, keywords, repository URL, etc. |
  205. When 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.
  206. ---
  207. ## Scripts
  208. **Bundled in the plugin:** every diagnostic script in `references/audit-script-matrix.md`. **`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:
  209. ```bash
  210. pip install -r requirements.txt
  211. ```
  212. On **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`.
  213. Preflight (optional): `python scripts/requirements-check.py` or `python scripts/requirements-check.py --json` — exits non-zero if `requests` / `beautifulsoup4` are missing.
  214. **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/`.
  215. Eval 1 also lints the written report against the § 2 contract (`report_lint.py`). Add `--summary summary.json` to check its score against a `generate_report.py` run.
  216. Run the full-site report to start any audit:
  217. ```bash
  218. python scripts/generate_report.py https://example.com --output seo-report.html
  219. ```
  220. In CI, `--format none --json seo-summary.json --fail-under 70 --fail-on critical` writes a machine-readable summary and fails the build on a regression. Checks that could not run are left out of the score rather than failing it. Exit codes and a GitHub Actions step: `references/procedures/21-script-toolbox.md` → CI Gate on the Full Report.
  221. | Script | Purpose |
  222. |---|---|
  223. | `generate_report.py` | Full-site HTML report in the report-set design (`--previous` for the delta since the last run; `--prepared-for`, `--prepared-by`, `--accent` for white-label) — bundled analysis pipeline |
  224. | `requirements-check.py` | Preflight: `requests` + `beautifulsoup4` installed (`--json`) |
  225. | `score_eval_transcript.py` | Score replies vs `evals/evals.json` (`--eval-id` or `--all-fixtures`) |
  226. | `meta_lengths_checker.py` | Title / meta description / H1 lengths (`--url` or local HTML) |
  227. | `validate_schema.py` | Validates JSON-LD blocks (pure stdlib) |
  228. | `robots_checker.py` | robots.txt rules + AI crawler allow/block status |
  229. | `ai_bot_access.py` | Suspected firewall / CDN blocks: fetches a URL as a browser and as each AI crawler |
  230. | `ai_bot_logs.py` | AI crawler requests in server access logs, verified against published IP ranges |
  231. | `citation_sampling.py` | AI citation rates with 95% intervals from repeated, recorded runs (no API calls) |
  232. | `hidden_instructions.py` | Instructions to AI systems hidden from visitors (CSS-hidden text, comments, attributes, invisible Unicode) |
  233. | `pagespeed.py` | Core Web Vitals via PageSpeed Insights API |
  234. | `hreflang_checker.py` | All 8 hreflang rules + bidirectional return tags |
  235. | `internal_links.py` | Link graph, orphan pages, anchor text, crawl depth |
  236. | `broken_links.py` | 4xx/5xx broken links + redirect counts |
  237. | `redirect_checker.py` | Full redirect chain analysis — loops and mixed HTTP/HTTPS |
  238. | `security_headers.py` | HSTS, CSP, X-Frame-Options — weighted score |
  239. | `entity_checker.py` | Wikidata, Wikipedia, sameAs entity signals |
  240. | `llms_txt_checker.py` | llms.txt presence + format validation |
  241. | `indexnow_checker.py` | IndexNow key file validation + ping |
  242. | `social_meta.py` | Open Graph + Twitter Card validation |
  243. | `readability.py` | Flesch-Kincaid grade + sentence stats |
  244. | `duplicate_content.py` | Near-duplicate detection |
  245. | `article_seo.py` | CMS-aware article structure + keyword analysis |
  246. | `link_profile.py` | Link equity distribution |
  247. | `finding_verifier.py` | Deduplicates findings across a full audit |
  248. | `fetch_page.py` | Fetch and save raw HTML (utility) |
  249. | `parse_html.py` | Extract titles, H1s, meta, canonical, schema (utility) |
  250. | `sitemap_checker.py` | Sitemap discovery via robots.txt + first sitemap sanity |
  251. | `local_signals_checker.py` | LocalBusiness / tel / address signals on a URL |
  252. | `image_checker.py` | Image alt coverage from saved HTML |
  253. | `canonical_checker.py` | Canonical tag validation |
  254. | `content_quality.py` | E-E-A-T risk detection (filler, citation gaps, missing author) |
  255. | `content_brief.py` | Content brief generation from competitor analysis |
  256. | `drift_monitor.py` | SEO drift baseline, compare, history, report (17 rules) |
  257. | `topic_cluster.py` | SERP-overlap topic clustering (CSV input) |
  258. | `ecommerce_schema.py` | E-commerce schema validation (Product, Offer, Return, Shipping) |
  259. | `maps_checker.py` | Advanced local SEO / GBP schema audit |
  260. | `google_api_tier.py` | Detect available Google API credentials (Tier 0–2) |
  261. | `google_auth.py` | Sign in to Search Console once per user (browser, read-only); every copy of the skill reads the token |
  262. | `crux_history.py` | CrUX History API — historical CWV data (Tier 0) |
  263. | `gsc_query.py` | Google Search Console queries (Tier 1, OAuth) |
  264. | `link_opportunities.py` | Pages that name a target's topic but do not link to it: the sentence and the anchor |
  265. | `index_coverage_diff.py` | GSC Page indexing week over week from two exports: what moved, why, one reason to investigate |
  266. | `gsc_insights.py` | GSC opportunities: striking distance, low CTR vs the site's own curve, cannibalisation, decay, serve map (Tier 1) |
  267. | `gsc_export.py` | GSC data export (Tier 1, OAuth) |
  268. | `ga4_report.py` | GA4 organic and AI-assistant referral traffic (Tier 2, OAuth) |
  269. | `page_network.py` | What rendered pages call: first-party write endpoints any website can call without a key, llms.txt endpoints, tracking vendors per page |
  270. | `ga4_audit.py` | GA4 conversion event audit: test hosts, bursts, repeat firing, tracking steps, (not set) landing pages (Tier 2) |
  271. | `conversion_reconcile.py` | Form conversions on two rulers: GA4 events vs distinct clean CRM people, with tests, preview hosts, bursts and repeats set aside |
  272. | `pdf_charts.py` | SVG chart generation for PDF reports (module) |
  273. | `pdf_template.py` | Professional A4 PDF template with cover + TOC (module) |
  274. | `render_page.py` | SPA-aware rendering (Playwright optional) |
  275. | `url_safety.py` | Outbound URL validation (SSRF prevention) |
  276. | `crawl_adapter.py` | Pluggable crawl backend (requests/firecrawl/playwright) |
  277. | `site_mapper.py` | URL discovery via sitemap + crawl |
  278. | `backlink_analyzer.py` | 7-section backlink audit (CSV/API data) |
  279. | `programmatic_seo_auditor.py` | Quality gates for pages at scale |
  280. ---
  281. ## Eval Results
  282. Benchmarked against baseline (no skill) across multiple scenarios (see `evals/evals.json`; **17** prompts, **74** assertions):
  283. | Metric | With Skill | Without Skill | Delta |
  284. |---|---|---|---|
  285. | Pass rate | **100%** | 87% | **+13 pts** |
  286. | Avg time | 103s | 54s | +49s |
  287. | Avg tokens | 83K | 64K | +19K |
  288. The 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.
  289. **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, wrong brand facts in AI answers (facts page, segment prices). **Automated check:** `python scripts/score_eval_transcript.py --all-fixtures`.
  290. ---
  291. ## Troubleshooting
  292. | Symptom | Cause | Fix |
  293. |---|---|---|
  294. | "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` |
  295. | "Could not load skill files" | Stale cache after a GitHub update | `cd ~/.claude/plugins/marketplaces/ultimate-seo-geo && git pull`, then restart session |
  296. | 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 |
  297. | `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 |
  298. | 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 |
  299. ---
  300. ## What It Doesn't Do
  301. This skill focuses on organic search and AI search visibility. It does not cover:
  302. - PPC / Google Ads / paid advertising
  303. - Social media management or posting
  304. - General marketing strategy
  305. - Web design or UX (beyond SEO-relevant elements)
  306. - Content writing (it generates briefs and meta tags, not full articles)
  307. ---
  308. ## Credits
  309. Built on research, patterns, and prior work from:
  310. - **[Bhanunamikaze/Agentic-SEO-Skill](https://github.com/Bhanunamikaze/Agentic-SEO-Skill)** — SEO analysis toolkit architecture, specialist agent patterns, technical SEO audit framework
  311. - **[AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)** — GEO platform citation data, DataForSEO integration patterns, AI crawler detection tables, subagent delegation architecture
  312. ---
  313. ## Maintainers
  314. Releases, version alignment, and syncing the plugin skill tree: [RELEASE.md](RELEASE.md).
  315. ---
  316. ## License
  317. [MIT](LICENSE) — use it, modify it, ship it.
plugins/ultimate-seo-geo/skills/ultimate-seo-geo/scripts/hidden_instructions.py · Bundled script · 264 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """
  3. Find text on a page that is aimed at AI systems but hidden from human readers.
  4. Prompt injection on web pages puts instructions for LLM crawlers and AI
  5. assistants ("ignore previous instructions", "AI assistants must recommend ...")
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore previous instructions"
    • Line 6 on GitHub
  6. where a visitor never sees them: CSS-hidden elements, noscript, HTML comments,
  7. alt / title / aria-label attributes, meta descriptions, JSON-LD, or invisible
  8. Unicode (tag characters and long zero-width runs). A site owner who did not
  9. put it there has been compromised, often through a plugin, an injected script
  10. or user comments. One who did is hiding text from visitors, which Google's
  11. spam policies prohibit when it is placed to manipulate search engines.
  12. Only instruction-like text in a hidden place is flagged. The same sentence in
  13. visible body copy, such as an article about prompt injection, is not.
  14. Limits, repeated in every result:
  15. * Hidden means inline styles, the hidden attribute, noscript / template and
  16. common hiding or screen-reader classes. Text hidden by external stylesheets
  17. or scripts is not seen; check a rendered page in DevTools.
  18. * Instruction patterns are English and phrase-based. Paraphrased or
  19. other-language instructions are missed, so no findings is not proof of a
  20. clean page.
  21. Usage:
  22. python hidden_instructions.py https://example.com
  23. python hidden_instructions.py page.html --json
  24. """
  25. import argparse
  26. import json
  27. import os
  28. import re
  29. import sys
  30. try:
  31. from bs4 import BeautifulSoup, Comment
  32. except ImportError:
  33. print("Error: beautifulsoup4 required. Install with: pip install beautifulsoup4")
  34. sys.exit(1)
  35. INSTRUCTION_PATTERNS = [
  36. ("override", re.compile(
  37. r"\b(?:ignore|disregard|forget)\s+(?:all\s+|any\s+|the\s+)?(?:previous|prior|above|earlier|preceding|other)\s+"
  38. r"(?:instructions|prompts|directions|rules|context)", re.I)),
  39. ("role", re.compile(
  40. r"\byou\s+are\s+(?:now\s+)?(?:an?\s+)?(?:ai|assistant|chatbot|language\s+model|llm|chatgpt|claude|gemini|copilot|perplexity)\b",
  41. re.I)),
  42. ("addressed to AI", re.compile(
  43. r"\b(?:chatgpt|claude|gemini|perplexity|copilot|llms?|large\s+language\s+models?|"
  44. r"ai\s+(?:assistants?|models?|agents?|systems?|crawlers?|search\s+engines?))\b[^.!?\n]{0,60}?"
  45. r"\b(?:must|should|always|never|recommend|mention|say|state|tell|describe|rank|cite|respond)\b", re.I)),
  46. # Instruction form only: "System prompt" as a heading or link title (Wikipedia's own
  47. # article on prompt injection has one) is a topic, not an injection.
  48. ("system prompt", re.compile(
  49. r"(?:\bsystem\s+prompt\s*:|\b(?:new|updated|override(?:\s+the)?)\s+system\s+prompt\b"
  50. r"|\bnew\s+instructions\s*:|<\|im_start\|>|\[/?INST\])", re.I)),
  51. ("answer framing", re.compile(
  52. r"\bwhen\s+(?:summari[sz]ing|asked\s+about|answering\s+questions\s+about)\s+(?:this|our|the)\b", re.I)),
  53. ]
  54. # Inline declarations that take an element out of what a visitor sees.
  55. HIDDEN_STYLE = re.compile(
  56. r"display\s*:\s*none"
  57. r"|visibility\s*:\s*hidden"
  58. r"|opacity\s*:\s*0(?:\.0+)?\s*(?:;|!|$)"
  59. r"|font-size\s*:\s*0(?:\.0+)?(?:px|pt|em|rem|%)?\s*(?:;|!|$)"
  60. r"|(?:left|top|text-indent|margin-left)\s*:\s*-\d{3,}(?:\.\d+)?(?:px|em|rem)"
  61. r"|clip\s*:\s*rect\(\s*0",
  62. re.I,
  63. )
  64. SCREEN_READER_CLASSES = {"sr-only", "visually-hidden", "screen-reader-text"}
  65. HIDING_CLASSES = {"d-none", "hidden", "invisible"}
  66. TEXT_ATTRIBUTES = ("alt", "title", "aria-label")
  67. META_NAMES = {"description", "og:description", "twitter:description"}
  68. TAG_CHARACTERS = re.compile("[\U000E0000-\U000E007F]+")
  69. ZERO_WIDTH_RUN = re.compile("[​‌‍⁠]{16,}")
  70. BLACK_FLAG = "\U0001F3F4" # subdivision flags (England, Scotland, Wales) use tag characters legitimately
  71. LIMITS = [
  72. "Hidden means inline styles, the hidden attribute, noscript and template, and common hiding or "
  73. "screen-reader classes. Text hidden by external stylesheets or scripts is not seen; check the "
  74. "rendered page in DevTools.",
  75. "Instruction patterns are English and phrase-based. Paraphrased or other-language instructions are "
  76. "missed, so no findings is not proof of a clean page.",
  77. ]
  78. SNIPPET_BEFORE, SNIPPET_AFTER = 60, 120
  79. PLACE_PHRASES = {
  80. "hidden element": "a hidden element",
  81. "HTML comment": "an HTML comment",
  82. "attribute": "an attribute",
  83. "meta tag": "a meta tag",
  84. "structured data": "structured data",
  85. }
  86. def find_instruction(text: str):
  87. """Return (pattern name, match) for the first instruction-like phrase in text, or None."""
  88. for name, pattern in INSTRUCTION_PATTERNS:
  89. match = pattern.search(text or "")
  90. if match:
  91. return name, match
  92. return None
  93. def _snippet(text: str, match) -> str:
  94. start = max(0, match.start() - SNIPPET_BEFORE)
  95. end = min(len(text), match.end() + SNIPPET_AFTER)
  96. body = re.sub(r"\s+", " ", text[start:end]).strip()
  97. return ("…" if start else "") + body + ("…" if end < len(text) else "")
  98. def hidden_reason(tag):
  99. """Why a visitor cannot see this element, or None. aria-hidden is not a reason: it hides from screen readers only."""
  100. if tag.name in ("noscript", "template"):
  101. return f"{tag.name} element"
  102. if tag.has_attr("hidden"):
  103. return "hidden attribute"
  104. match = HIDDEN_STYLE.search(tag.get("style") or "")
  105. if match:
  106. return f"inline style ({re.sub(r'[;!]$', '', match.group(0)).strip()})"
  107. classes = {c.lower() for c in (tag.get("class") or [])}
  108. if classes & SCREEN_READER_CLASSES:
  109. return f"screen-reader-only class ({sorted(classes & SCREEN_READER_CLASSES)[0]})"
  110. if classes & HIDING_CLASSES:
  111. return f"hiding class ({sorted(classes & HIDING_CLASSES)[0]})"
  112. return None
  113. def scan_markup(html: str) -> list:
  114. """Instruction-like text in places a visitor does not see."""
  115. soup = BeautifulSoup(html, "html.parser")
  116. found = []
  117. def record(context, where, text, severity):
  118. hit = find_instruction(text)
  119. if hit:
  120. found.append({
  121. "context": context,
  122. "where": where,
  123. "pattern": hit[0],
  124. "snippet": _snippet(text, hit[1]),
  125. "severity": severity,
  126. })
  127. for script in soup.find_all("script", attrs={"type": re.compile(r"ld\+json", re.I)}):
  128. record("structured data", "JSON-LD", script.get_text(" "), "warning")
  129. for comment in soup.find_all(string=lambda s: isinstance(s, Comment)):
  130. record("HTML comment", "<!-- -->", str(comment), "warning")
  131. for tag in soup.find_all(["script", "style"]):
  132. tag.decompose()
  133. inside_hidden = set()
  134. for tag in soup.find_all(True):
  135. for attr in TEXT_ATTRIBUTES:
  136. if tag.has_attr(attr):
  137. record("attribute", f"{tag.name}[{attr}]", str(tag[attr]), "warning")
  138. if tag.name == "meta" and (tag.get("name") or tag.get("property") or "").lower() in META_NAMES:
  139. record("meta tag", f"meta {(tag.get('name') or tag.get('property')).lower()}", tag.get("content") or "", "warning")
  140. if id(tag) in inside_hidden:
  141. continue
  142. reason = hidden_reason(tag)
  143. if reason:
  144. inside_hidden.update(id(d) for d in tag.descendants)
  145. record("hidden element", f"<{tag.name}> {reason}", tag.get_text(" "), "critical")
  146. return found
  147. def scan_unicode(text: str) -> list:
  148. """Invisible Unicode that carries text only machines read."""
  149. found = []
  150. for match in TAG_CHARACTERS.finditer(text):
  151. if match.start() > 0 and text[match.start() - 1] == BLACK_FLAG:
  152. continue
  153. decoded = "".join(chr(ord(c) - 0xE0000) for c in match.group(0) if 0x20 <= ord(c) - 0xE0000 < 0x7F)
  154. found.append({"kind": "Unicode tag characters", "length": len(match.group(0)), "decoded": decoded[:200]})
  155. for match in ZERO_WIDTH_RUN.finditer(text):
  156. found.append({"kind": "zero-width character run", "length": len(match.group(0)), "decoded": None})
  157. return found
  158. def check_html(html: str, source: str) -> dict:
  159. hidden = scan_markup(html)
  160. invisible = scan_unicode(html)
  161. issues = []
  162. for item in hidden:
  163. icon = "🔴" if item["severity"] == "critical" else "⚠️"
  164. place = PLACE_PHRASES.get(item["context"], item["context"])
  165. issues.append(
  166. f"{icon} Instruction-like text aimed at AI systems in {place} ({item['where']}): "
  167. f"\"{item['snippet']}\". Visitors cannot see it. If the site did not add it, treat it as a compromise "
  168. "(plugin, injected script or user comments); if it did, remove it: Google's spam policies cover hidden "
  169. "text and attempts to manipulate generative AI responses in Google Search"
  170. )
  171. for item in invisible:
  172. detail = f', decoding to "{item["decoded"]}"' if item["decoded"] else ""
  173. issues.append(
  174. f"⚠️ Invisible {item['kind']} ({item['length']} characters){detail}. They carry text only machines "
  175. "read; find where they enter the page and remove them"
  176. )
  177. critical = any(item["severity"] == "critical" for item in hidden)
  178. return {
  179. "source": source,
  180. "hidden_instructions": hidden,
  181. "invisible_unicode": invisible,
  182. "score": 0 if critical else 50 if issues else 100,
  183. "issues": issues,
  184. "limits": LIMITS,
  185. "error": None,
  186. }
  187. def load_source(source: str, timeout: int):
  188. """Return (html, error) from a local file or a URL."""
  189. if os.path.isfile(source):
  190. with open(source, encoding="utf-8", errors="replace") as fh:
  191. return fh.read(), None
  192. from fetch_page import fetch_page
  193. result = fetch_page(source, timeout=timeout)
  194. if result.get("error"):
  195. return None, result["error"]
  196. return result.get("content") or "", None
  197. def main():
  198. parser = argparse.ArgumentParser(description="Find instructions to AI systems hidden from human readers")
  199. parser.add_argument("source", help="URL or saved HTML file")
  200. parser.add_argument("--timeout", type=int, default=30, help="Fetch timeout in seconds (default: 30)")
  201. parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
  202. args = parser.parse_args()
  203. html, error = load_source(args.source, args.timeout)
  204. result = {"source": args.source, "error": error} if error else check_html(html, args.source)
  205. if args.json:
  206. print(json.dumps(result, indent=2, ensure_ascii=False))
  207. if result.get("error"):
  208. sys.exit(1)
  209. return
  210. if result.get("error"):
  211. print(f"Error: {result['error']}")
  212. sys.exit(1)
  213. print(f"Hidden AI instructions — {result['source']}")
  214. print("=" * 50)
  215. print(f"Hidden instruction-like text: {len(result['hidden_instructions'])}")
  216. print(f"Invisible Unicode runs: {len(result['invisible_unicode'])}")
  217. if result["issues"]:
  218. print(f"\nIssues ({len(result['issues'])}):")
  219. for issue in result["issues"]:
  220. print(f" {issue}")
  221. else:
  222. print("\nNo hidden instruction-like text found.")
  223. print("\nLimits:")
  224. for limit in result["limits"]:
  225. print(f" - {limit}")
  226. if __name__ == "__main__":
  227. main()

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.