Content & Media Creation · zubair-trabzada/geo-seo-claude
geo-seo-claude
GEO-first SEO analysis tool. Optimizes websites for AI-powered search engines (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) while maintaining traditional SEO foundations. Performs full GEO audits, citability scoring, AI crawler analysis, llms.txt generation, brand mention scanning, platform-specific optimization, schema markup, technical SEO, content quality (E-E-A-T), and client-ready GEO report generation. Use when user says "geo", "seo", "audit", "AI search", "AI visibility", "optimize", "citability", "llms.txt", "schema", "brand mentions", "GEO report", or any URL for analysis.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandInstall DepsNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The GEO-first 6-dimensional weighted scoring system serves as the backbone of the entire toolkit: AI citability carries the highest weight (25%), brand authority 20%, content E-E-A-T 20%, traditional technical SEO drops to 15%, structured data 10%, and platform presence 10%. Formulas, 0–100 grading tiers, and Critical/High/Medium/Low remediation deadlines are hardcoded into the skill files, reducing the agent's discretion strictly to 'assigning six scores according to the rubric'.
skills/geo-audit/SKILL.md
GEO_Score = (Citability * 0.25) + (Brand * 0.20) + (EEAT * 0.20) + (Technical * 0.15) + (Schema * 0.10) + (Platform * 0.10)
The same file provides definitions across five tiers: 90–100 Excellent / 75–89 Good / 60–74 Fair / 40–59 Poor / 0–39 Critical, along with a prioritized action list ranging from Critical ('Fix Immediately') to Low ('Optimize When Possible')—ensuring transparent, reproducible scores necessary for client deliverables.
Citability is implemented as executable code rather than an abstract concept: citability_scorer.py translates the principle that 'AI prefers self-contained paragraphs of 134–167 words with factual figures' into a regex-based scorer across five dimensions (Answer Chunk 30 / Self-Containment 25 / Structure 20 / Statistical Density 15 / Uniqueness 10), evaluating each paragraph on a 0–100 scale and assigning letter grades A–F.
scripts/citability_scorer.py
if 134 <= word_count <= 167:
The file uses re.search to match definition syntax ('X is a/an/the', 'refers to', 'defined as'), pronoun density, percentages/dollar amounts/units, 'according to|research shows|studies found', 'our research|we found', etc. It operates entirely without LLM calls or API keys via pure heuristics, making it reproducible offline and verifiable in regression tests.
Full-site audits are distributed across 5 parallel subagents: geo/SKILL.md maps each agent file to its assigned sub-skill via a table, while the primary skill handles only Phase 1 probing, Phase 2 concurrent delegation, and Phase 3 synthesis.
geo/SKILL.md
Launch these 5 subagents simultaneously:
The subagent roster consists of geo-ai-visibility (citability/crawlers/llmstxt/brand-mentions), geo-platform-analysis, geo-technical, geo-content, and geo-schema. Each agent independently defines weights and output formats; for instance, agents/geo-ai-visibility.md sets AI_Visibility = Citability*0.35 + Brand*0.30 + Crawler*0.25 + llms.txt*0.10. Concurrency relies on host agent orchestration, while the skill defines the delegation contracts and merging rules.
AI crawler access evaluation relies on concrete data: fetch_page.py hardcodes a list of 14 AI/search crawlers and parses robots.txt per rule, while the agent applies a 100-point deduction rubric (-15 points per blocked primary crawler, -5 points per blocked secondary crawler, and -10 points if no sitemap is referenced).
scripts/fetch_page.py
ai_crawlers = [ "GPTBot", "OAI-SearchBot",
The tracked list includes GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, anthropic-ai, PerplexityBot, CCBot, Bytespider, cohere-ai, Google-Extended, GoogleOther, Applebot-Extended, FacebookBot, and Amazonbot. Beyond robots.txt, it inspects /llms.txt, sitemap references, and non-scoring Content-Signal draft directives (draft-romm-aipref-contentsignals).
llms.txt supports both validation and generation: scripts determine format_valid against four criteria (H1 Title / > Description / ## Section / Link items) and report itemized issues. In generate mode, it crawls the homepage and internal links (default 30 pages) to output llms.txt and llms-full.txt files.
scripts/llmstxt_generator.py
result["format_valid"] = (
When generating llms-full.txt, meta descriptions are fetched for each page. The author explicitly skips cross-origin URLs to minimize SSRF exposure (commented as '# Skip cross-origin URLs to prevent SSRF via redirect chains'), demonstrating awareness of target sites injecting arbitrary request destinations into the script.
Brand mention scanning is split between 'half real API calls and half delegation': Wikipedia and Wikidata are checked via real API requests to yield yes/no conclusions, whereas other platforms like YouTube, Reddit, LinkedIn, and G2 only generate search_url entries and verification checklists, delegating actual fetching to the agent's WebFetch/search tools.
scripts/brand_scanner.py
api_url = f"https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch={quote_plus(brand_name)}&format=json"
Evidence boundary: The YouTube branch in the file explicitly notes '# Note: Actual YouTube API would be used in production' and '# This provides the framework for Claude Code to use WebFetch'. Therefore, the README claim 'Scans YouTube, Reddit, Wikipedia, LinkedIn, and 7+ other platforms' should be understood as providing scanning endpoints and scoring methodologies, with actual retrieval executed by the agent.
PDF deliverables require zero Python dependencies: v2.0.0's geo-report-pdf uses pandoc to render GEO-AUDIT-REPORT.md into self-contained HTML (with embedded cover templates and CSS), then prints it to PDF via local headless Google Chrome. Score and severity color styling are applied via inline JS before printing.
skills/geo-report-pdf/SKILL.md
No Python dependencies. No ReportLab. No JSON data wrangling.
Prerequisites require only pandoc and local Chrome ('/Applications/Google Chrome.app/'), which prints via Chrome "file://$(pwd)/GEO-REPORT.html". The referenced 'charts' are CSS-rendered score badges and color-coded tables rather than a graphing library.
/geo update serves as a self-updating channel: it clones upstream main (--depth 1, unpinned commit, unverified), diffs changes, overwrites geo/, skills/, agents/, scripts/, and schema/ in ~/.claude/, and runs pip install -r to update dependencies without deleting local customized files.
skills/geo-update/SKILL.md
git clone --depth 1 https://github.com/zubair-trabzada/geo-seo-claude.git "$TEMP_DIR/repo"
Step 5 updates dependencies via 'python3 -m pip install -r "$SOURCE_DIR/requirements.txt" --quiet' (bypassing the installer's isolated venv path). Configured with allowed-tools for Bash/Read/Write, this skill represents the repository's sole routine path for pulling and writing upstream code to disk.
2Core Capabilities
01Command routing via single /geo entrypoint (17 commands) with command-specific tool allowlists
02Composite GEO Score (0–100) with 6-dimensional weighting, 5 tier ratings, and prioritized Critical/High/Medium/Low action items
03Paragraph-level citability scoring (0–100 mapped to A–F grades) with actionable rewriting guidance
04AI crawler access evaluation (Allowed/Blocked/Restricted/Unknown) with deduction-based Crawler Access Score and Content-Signal parsing
05llms.txt validation and crawler-based generation from target sites (including llms-full.txt)
06Brand/entity authority scanning: authentic API calls for Wikipedia and Wikidata, plus search entrypoints for Quora, Stack Overflow, GitHub, Crunchbase, Product Hunt, G2, Trustpilot, and more
07Client deliverable pipeline: markdown reports (GEO-CLIENT-REPORT.md/GEO-AUDIT-REPORT.md) → pandoc + headless Chrome cover/score-styled PDFs, with white-label customizable templates and CSS
08GEO agency business suite: CRM-lite (prospect/proposal/compare saved to ~/.geo-prospects/), Flask/HTMX dashboard (localhost:5050), and rich terminal dashboard
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| package | requests |
| package | beautifulsoup4 |
| package | lxml（BeautifulSoup 解析器） |
| package | playwright（可选，截图用；安装器会拉 Chromium 二进制） |
| package | flask（CRM Web 看板） |
| package | rich（终端 CRM 看板） |
| package | Pillow / urllib3 / validators（requirements 其余依赖，脚本中未直接调用点） |
| cli | pandoc |
| cli | Google Chrome（headless 打印 PDF） |
| cli | git（安装与 /geo update 拉取上游） |
| cli | uv（可选，加速 venv/依赖安装） |
| api | Wikipedia MediaWiki 搜索 API |
| api | Wikidata wbsearchentities API |
| network | 被审计目标站点本身（任意 http/https 主机，含 /robots.txt、/llms.txt、/llms-full.txt、/sitemap.xml、/sitemap_index.xml 及页面与页面内同域链接） |
| network | Google Fonts（PDF 样式表 @import，pandoc/Chrome 渲染时取字体） |
| network | Bootstrap 与 HTMX CDN（CRM Web 看板模板） |
| network | raw.githubusercontent.com 一键安装（curl 管道执行 install.sh，不进 skill 运行时） |
| api | GitHub REST stargazers API（仅 CI 生成星标图，不进 skill 运行路径） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: During installation (explicitly run by user): install.sh / install-win.sh creates directories, copies geo/, skills/*, agents/*, s
- scripts/ 或 SKILL.md: Declares dynamic installation of external language package dependencies
- 网络端点: Declares external network access: Audited targets themselves: requests.get in scripts/*.py targets user-supplied http/https URLs (fetch_page explicitly rejects non-HTTP)
- 本地工作目录: File read/write and artifact output: Audit artifacts are written to the current working directory: GEO-AUDIT-REPORT.md, GEO-PAGE-ANALYSIS.md, GEO-CITABILITY-SCORE.
Audit Notes: According to the unified grading criteria: No credential/secret reading (the repository's sole GITHUB_TOKEN read is in the CI script .github/scripts/star_history.py, outside the skill runtime), no telemetry or data exfiltration endpoints, and no obfuscated payloads; all 71 managed files are readable, and network targets are fully enumerable (audited sites, Wikipedia/Wikidata public APIs, GitHub/PyPI for code pulls, and page CDN fonts). Yellow tier is assigned based on four factors: (1) Primary skills, sub-skills, and agents declare Bash + Write while consuming arbitrary, untrusted HTML from audited sites, establishing a content-injection to execution/disk-write path lacking documented sandbox isolation; (2) The one-click install pipes curl directly into install.sh, and the Windows installer uses pip install --user against user-level Python (contradicting the README's isolation guarantee: 'Your system Python is not touched'); (3) /geo update unpinned-clones upstream main, overwriting installed files and running pip install -r, representing an unverified supply-chain update path; (4) The PDF pipeline runs Chrome --no-sandbox to print HTML derived from audited web content. Because all risks can be constrained by host-level permissions and human verification, and no secret access is involved, it is not escalated to Orange (Orange requires cookie/credential access or covert exfiltration).
5Second-Pass Verification
- [ok] skill.path 定位 — 候选位置逐一排查：仓库根无 SKILL.md（git ls-tree 确认根目录只有 README/LICENSE/install*/uninstall/requirements 与各功能目录）；`geo/SKILL.md` 是唯一带 `name: geo` 的路由入口，frontmatter 声明 17 条 /geo 命令并提供 sub-skill/agent 分工表；install.sh 把 `geo/` 装成 ~/.claude/skills/geo 并把 `$INSTALL_DIR/SKILL.md` 当作主技能文件（`INSTALL_DIR="${SKILLS_DIR}/geo"`），geo-update 亦称 Main skill = ~/.claude/skills/geo/；docs/architecture.md 与 README 同称 'geo/ # Main skill orchestrator'。skills/* 是子技能（无 flagship 地位，安装时被平铺到 ~/.claude/skills/geo-*）。故取 skill.path="geo"——仓库根不是 skill，子技能目录是下级组件。
- [discrepancy] README/docs 的 PDF 实现描述（generate_pdf_report.py + ReportLab） — README 架构图写 '│ ├── generate_pdf_report.py # PDF report generator (ReportLab)'，docs/commands-reference.md 写 '- Calls `python3 ~/.claude/skills/geo/scripts/generate_pdf_report.py` (requires `pip install reportlab`).'；但 71 个受管文件中并无该脚本，requirements.txt 没有 reportlab，现行 skills/geo-report-pdf/SKILL.md（version 2.0.0）明确 'No Python dependencies. No ReportLab.'，改用 pandoc + Chrome headless + 仓内模板/CSS。结论：README 与 commands-reference 是未同步的旧文档，应以 geo-report-pdf v2.0.0 为准。
- [discrepancy] 子技能数量与实际目录数 — 三处口径互斥：README '├── skills/ # 13 specialized sub-skills'、docs/architecture.md 同写 13；geo/SKILL.md 标题 '## Sub-Skills (14 Specialized Components)' 且表格缺 geo-report-pdf；实际 `skills/` 下有 15 个目录（含 geo-report-pdf）。另外 router 命令表共 17 条命令，其中 `/geo page` 与 `/geo quick` 没有对应子技能目录（由其它技能组合实现）。用户按文档理解能力边界会有偏差。
- [discrepancy] 品牌提及『扫描 10+ 平台』的夸大检查 — README 称 'Scans YouTube, Reddit, Wikipedia, LinkedIn, and 7+ other platforms'。实读 scripts/brand_scanner.py：只有 Wikipedia API 与 Wikidata API 两处 requests.get 是真实网络判定；YouTube/Reddit/LinkedIn/Quora/Stack Overflow/GitHub/Crunchbase/Product Hunt/G2/Trustpilot 分支仅返回 search_url + check_instructions，并由代码注释明示 'Actual YouTube API would be used in production / This provides the framework for Claude Code to use WebFetch'。属能力边界夸大（真实核查转由 agent 的 WebFetch/搜索完成）。
- [discrepancy] 安装器『隔离 venv、不动系统 Python』承诺 — README 声明 'Python dependencies are installed into a dedicated virtual environment at `~/.claude/skills/geo/.venv/`. Your system Python is **not** touched'，install.sh 确实如此（venv + `uv pip install --python "$VENV_PY"`/`$VENV_PY -m pip install` + 把脚本 shebang 与 SKILL.md 中 python3 调用 sed 成 venv 解释器）。但 install-win.sh 走的是 `$PYTHON_CMD -m pip install --user -r "$SOURCE_DIR/requirements.txt"`（写用户级 site-packages），与承诺不符；/geo update 也用 `python3 -m pip install -r ...`（非 venv 路径）。
- [ok] hooks 安装路径 — 两个安装器都 `mkdir -p "$INSTALL_DIR/scripts" "$INSTALL_DIR/schema" "$INSTALL_DIR/hooks"` 并在 `[ -d "$SOURCE_DIR/hooks" ]` 守卫下复制 hooks；仓库内确无 hooks/ 目录（本地 ls 报 No such file or directory，git ls-tree 亦无），故该分支在源码态为惰性空操作，不构成未列出的执行面。
- [ok] 全部 external_deps 二次定位 — 18 条依赖逐条回到调用点复核：requests 在 fetch_page.py/citability_scorer.py/brand_scanner.py/llmstxt_generator.py 四处 requests.get；beautifulsoup4+lxml 在 fetch_page/llmstxt 的 BeautifulSoup(..., "lxml")；flask 在 webapp/app.py 顶层 import 且 `app.run(debug=debug, port=5050)`；rich 在 crm_dashboard.py import 块；playwright 由 install.sh 的 venv 内 `-m playwright install chromium` 触发（requirements 亦列 playwright>=1.56.0）；pandoc/Chrome/git/uv 均为命令行调用点；Wikipedia/Wikidata/fonts.googleapis.com/jsdelivr/unpkg/api.github.com/raw.githubusercontent.com 均有原文出处。Pillow/urllib3/validators 仅见于 requirements.txt，仓内无直接调用点（已在条目 note 中标注）。
- [ok] 是否漏掉网络调用/隐藏脚本/混淆内容 — 全量 grep `requests\.|urllib|urlopen|getenv|environ|api_key|API_KEY|token|Authorization|https?://` 无遗漏命中：除已列条目外只剩示例/文档里的 schema.org、w3.org 等纯参考资料 URL，无上传/回传/统计端点；全文无 base64 长串、无 eval/exec、无 subprocess 拼装执行远端内容（webapp 与 crm_dashboard 只读写本地 JSON）。资产面 71 文件全部为文本，无二进制/压缩包。
6Verdict & Scenarios
Best for: Ideal for agencies, consultants, and marketing teams delivering AI search visibility (GEO) diagnostics to clients: a single-command install provides 0–100 audits, client-ready reports, proposals, and monthly delta tracking, with PDF generation and white-labeling suited for direct client deliverables. Also well-suited for teams integrating 'AI citability' into existing SEO workflows (via standalone subcommands like /geo citability, /geo crawlers, or /geo llmstxt). From an engineering perspective, it formalizes citability, robots, llms.txt, and SSR evaluations into readable, testable Python heuristics that serve as a strong baseline or reference implementation.
Not for: Not suitable for scenarios requiring 'real AI platform visibility telemetry'—it does not call external AI platform APIs, relying instead on rule-based heuristic scores; verifying ChatGPT or Perplexity citations requires live queries or third-party datasets. Not suitable for unreviewed, unattended batch audits against untrusted websites (Bash+Write operate in the same context as external content, creating an injection-to-execution risk). Not suitable for Windows users requiring strict dependency isolation (install-win.sh relies on pip install --user). Finally, not suitable for teams strictly focused on traditional SEO audits, as the scoring weights and criteria are GEO-first, covering traditional SEO only across the lower-weighted technical and structured data dimensions.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload geo-seo-claude.tar.gz
sha256:
Option B · Copy Guide for Agent3a969f95e983e9c4…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 25f6ae8d6c.