{"owner":"AgriciDaniel","repo":"claude-seo","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# Claude SEO: Multi-Platform Agent Instructions\n\n> For **Cursor**, **Cursor Cloud Agents**, **Google Antigravity**, **Gemini CLI**,\n> **Grok Build**,\n> **OpenAI Codex CLI**, **Cline**, **Aider**, and any other agent harness that\n> reads project-root agent instructions.\n>\n> Claude Code users: see `CLAUDE.md` instead.\n\n## Cross-platform portability (v2.0.0)\n\nEvery skill in `skills/*/SKILL.md` is authored to a portable subset of the\nClaude Code skill spec. Validate compatibility with your harness via:\n\n```bash\n./bin/claude-seo run portability_check.py\n```\n\nThe check confirms each `SKILL.md` has the minimum frontmatter every harness\nexpects (`name`, `description`, optional `model`, optional `tools`) and warns\non Claude-Code-specific features (`maxTurns`, multi-line tool list with\ndescriptive comments) that other harnesses may ignore but do not reject.\n\n### Per-harness notes\n\n| Harness | How to load claude-seo |\n|---|---|\n| **Cursor** | Symlink or copy `skills/` and `agents/` into `.cursor/rules/`. Commands are invoked as text prompts; the harness reads `SKILL.md` body as system context. |\n| **Cursor Cloud Agents** | Push the repo; Cloud Agents read `AGENTS.md` automatically at session start. |\n| **Google Antigravity** | Point the workspace at this repo root; Antigravity reads `AGENTS.md` first, falls back to `skills/`. |\n| **Gemini CLI** | `gemini init` in this repo loads `AGENTS.md`. Skills are activated via `activate_skill ` in conversation. |\n| **Grok Build** | Open this repository in Grok Build. It reads `AGENTS.md` and Claude Code compatible plugins and skills without a separate layout. Use `grok inspect` to verify discovery. See the [official compatibility guide](https://docs.x.ai/build/features/skills-plugins-marketplaces). |\n| **OpenAI Codex CLI** | Reads `AGENTS.md` from project root. Bash tools work as documented; some Claude-specific tool names (Read/Write/Edit) are aliased to Codex equivalents transparently. |\n| **Cline** | Loads `AGENTS.md` from project root. Skills appear as system messages; subagent delegation falls back to in-context expansion. |\n| **Aider** | Reads `AGENTS.md` if present; otherwise falls back to README. Aider does not support sub-agent dispatch; the seo-* skills run inline. |\n\n### Tool-name compatibility\n\nWhere claude-seo skills mention Claude Code tools (`Read`, `Write`, `Edit`,\n`Bash`, `Glob`, `Grep`, `WebFetch`), each harness typically has an equivalent:\n\n| Claude Code | Codex | Cline | Aider | Cursor / Antigravity |\n|---|---|---|---|---|\n| Read | read_file | read_file | (inline) | read |\n| Write | write_file | write_file | /add then edit | write |\n| Edit | apply_diff | replace_in_file | /edit | edit |\n| Bash | bash | execute_command | /run | shell |\n| Glob | glob | search_files | (inline) | find |\n| Grep | grep | search_files | /grep | grep |\n| WebFetch | fetch / browse | (browser tool) | (n/a) | fetch |\n\nThese mappings are automatic in most harnesses; we list them for transparency\nin case a recipe needs a specific call.\n\n## Overview\n\nClaude SEO is a Tier 4 SEO analysis skill with 25 sub-skills (21 core + 1 orchestrator +\n1 framework integration + 2 extension mirrors), 18 sub-agents (15 core + 1 framework\nintegration + 2 extension mirrors), and 53 Python execution scripts.\n\n## Quick Reference\n\n| Command | What it does |\n|---------|-------------|\n| `/seo audit ` | Full website audit with parallel subagent delegation |\n| `/seo page ` | Deep single-page analysis |\n| `/seo technical ` | Technical SEO audit (9 categories) |\n| `/seo content ` | E-E-A-T and content quality analysis |\n| `/seo content-brief ` | Generate a content brief for a topic |\n| `/seo schema ` | Schema.org detection, validation, generation |\n| `/seo sitemap ` | XML sitemap analysis or generation |\n| `/seo images ` | Image SEO: on-page audit, SERP analysis, file optimization |\n| `/seo geo ` | AI Overviews / Generative Engine Optimization |\n| `/seo plan ` | Strategic SEO planning |\n| `/seo cluster ` | SERP-based semantic clustering and content architecture |\n| `/seo sxo ` | Search Experience Optimization: page-type analysis, personas |\n| `/seo drift baseline ` | Capture SEO baseline for change monitoring |\n| `/seo drift compare ` | Compare current state to stored baseline |\n| `/seo drift history ` | Show drift history over time |\n| `/seo ecommerce ` | E-commerce SEO: product schema, marketplace intelligence |\n| `/seo programmatic [url]` | Programmatic SEO at scale |\n| `/seo competitor-pages [url]` | Competitor comparison pages |\n| `/seo flow [stage]` | FLOW framework prompts (Find, Leverage, Optimize, Win, Local; prompts/sync utilities.) |\n| `/seo local ` | Local SEO analysis (GBP, citations, reviews) |\n| `/seo maps [cmd] [args]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo hreflang ` | Hreflang/i18n SEO audit, cultural profiles, content parity |\n| `/seo google [cmd] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo backlinks setup` | Setup free backlink APIs |\n| `/seo backlinks verify ` | Verify known backlinks still exist |\n| `/seo dataforseo [cmd]` | Live SEO data via DataForSEO (extension) |\n| `/seo image-gen [use-case]` | AI image generation for SEO assets (extension) |\n| `/seo firecrawl [cmd] ` | Full-site crawling and site mapping (extension) |\n| `/seo ahrefs [cmd] ` | Ahrefs backlink and keyword data (extension) |\n| `/seo bing [cmd] ` | Bing Webmaster data and IndexNow (extension) |\n| `/seo profound [cmd]` | LLM brand-citation tracking (extension) |\n| `/seo seranking [cmd]` | AI share-of-voice tracking (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse audits (extension) |\n\n## Using with Cursor / Cursor Cloud\n\nCursor reads this file automatically. All SKILL.md files contain the full\nanalysis logic as natural language instructions. Python scripts in `scripts/`\nprovide execution capabilities.\n\n**Running scripts directly** (Cursor doesn't have MCP):\n```bash\n# Page fetching with SSRF protection\n./bin/claude-seo run fetch_page.py https://example.com\n\n# HTML parsing for SEO elements\n./bin/claude-seo run parse_html.py https://example.com\n\n# PageSpeed Insights\n./bin/claude-seo run pagespeed_check.py https://example.com --json\n\n# Drift baseline\n./bin/claude-seo run drift_baseline.py https://example.com\n\n# DataForSEO (requires credentials)\nDATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass ./bin/claude-seo run dataforseo_merchant.py search \"keyword\"\n```\n\n**Cursor Cloud gotchas:**\n- SSL certificates may not resolve for some domains. Investigate the certificate issue rather than disabling verification.\n- Run bundled tools through `claude-seo`; never call the venv interpreter directly.\n- Screenshots save to `/tmp/` not CWD. Check absolute paths.\n\n## Using with Google Antigravity\n\nAntigravity discovers this project via `.claude-plugin/plugin.json`.\nPlace the repo in `~/.gemini/antigravity/plugins/claude-seo/` or install via:\n\n```bash\nbash install.sh\n```\n\n## Architecture\n\n```\nskills/ # 25 sub-skills (auto-discovered)\n seo/SKILL.md # Main orchestrator + routing\n seo-cluster/ # Semantic clustering (v1.9.0)\n seo-sxo/ # Search Experience Optimization (v1.9.0)\n seo-drift/ # SEO drift monitoring (v1.9.0)\n seo-ecommerce/ # E-commerce SEO (v1.9.0)\n seo-audit/ # Full site audit\n seo-page/ # Single-page analysis\n seo-technical/ # Technical SEO\n seo-content/ # E-E-A-T quality\n seo-content-brief/ # Content brief generation\n seo-schema/ # Schema.org markup\n seo-sitemap/ # XML sitemaps\n seo-images/ # Image optimization\n seo-geo/ # AI search / GEO\n seo-local/ # Local SEO\n seo-maps/ # Maps intelligence\n seo-plan/ # Strategic planning\n seo-hreflang/ # International SEO\n seo-google/ # Google APIs\n seo-backlinks/ # Backlink analysis\n seo-programmatic/ # Programmatic SEO\n seo-competitor-pages/ # Competitor pages\n seo-flow/ # FLOW framework integration\n seo-dataforseo/ # DataForSEO (extension)\n seo-image-gen/ # AI images (extension)\nagents/ # 18 subagents\nscripts/ # 53 Python scripts, including the managed runtime\nschema/ # JSON-LD templates\nextensions/ # 8 MCP extensions: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, Unlighthouse\n```\n\n## Key Principles\n\n1. **Progressive Disclosure**: Read SKILL.md for routing, load references on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Security**: All scripts call `validate_url()` for SSRF protection\n4. **Config location**: `~/.config/claude-seo/` for API credentials\n\n## Credits\n\nCreated by [@AgriciDaniel](https://github.com/AgriciDaniel).\nv1.9.0 community contributions by Lutfiya Miller, Chris Muller, Florian Schmitz,\nDan Colta, and Matej Marjanovic. See [CONTRIBUTORS.md](CONTRIBUTORS.md).\n","CLAUDE.md":"# Claude SEO: Universal SEO Analysis Skill\n\n## Project Overview\n\nThis repository contains **Claude SEO**, a Tier 4 Claude Code skill for comprehensive\nSEO analysis across all industries. It follows the Agent Skills open standard and the\n3-layer architecture (directive, orchestration, execution). 25 sub-skills (21 core +\n1 orchestrator + 1 framework integration + 2 extension mirrors), 18 sub-agents (15 core +\n1 framework integration + 2 extension mirrors), and an extensible reference\nsystem cover technical SEO, content quality,\nschema markup, image optimization, sitemap architecture, AI search optimization,\nlocal SEO (GBP, citations, reviews, map pack), maps intelligence, semantic topic\nclustering, search experience optimization (SXO), SEO drift monitoring, e-commerce\nSEO, and international SEO with cultural adaptation profiles.\n\n## Architecture\n\n```\nclaude-seo/\n CLAUDE.md # Project instructions (this file)\n CONTRIBUTORS.md # Community credits (Pro Hub Challenge)\n AGENTS.md # Multi-platform agent instructions (Cursor, Antigravity)\n .claude-plugin/\n plugin.json # Plugin manifest (v2.2.4)\n marketplace.json # Marketplace catalog for distribution\n skills/ # 25 sub-skills (auto-discovered)\n seo/ # Main orchestrator skill\n SKILL.md # Entry point, routing table, core rules\n references/ # On-demand knowledge files (13 files)\n seo-audit/SKILL.md # Full site audit with parallel agents\n seo-page/SKILL.md # Deep single-page analysis\n seo-technical/SKILL.md # Technical SEO (9 categories)\n seo-content/SKILL.md # E-E-A-T and content quality\n seo-content-brief/SKILL.md # Content brief generation\n seo-schema/SKILL.md # Schema.org markup detection/generation\n seo-sitemap/SKILL.md # XML sitemap analysis/generation\n seo-images/SKILL.md # Image optimization analysis\n seo-geo/SKILL.md # AI search / GEO optimization\n seo-local/SKILL.md # Local SEO (GBP, citations, reviews, map pack)\n seo-maps/SKILL.md # Maps intelligence (geo-grid, GBP audit, reviews, competitors)\n seo-plan/SKILL.md # Strategic SEO planning\n seo-flow/SKILL.md # FLOW framework integration\n seo-programmatic/SKILL.md # Programmatic SEO at scale\n seo-competitor-pages/SKILL.md # Competitor comparison pages\n seo-hreflang/SKILL.md # International SEO / hreflang\n seo-google/ # Google SEO APIs\n SKILL.md\n references/ # API reference files (11 files)\n seo-backlinks/SKILL.md # Backlink profile analysis\n seo-cluster/ # Semantic topic clustering (v1.9.0, by Lutfiya Miller)\n SKILL.md\n references/ # Clustering methodology, architecture, workflow\n templates/ # cluster-map.html interactive visualization\n seo-sxo/ # Search Experience Optimization (v1.9.0, by Florian Schmitz)\n SKILL.md\n references/ # Page-type taxonomy, user stories, personas, wireframes\n seo-drift/ # SEO drift monitoring (v1.9.0, by Dan Colta)\n SKILL.md\n references/ # Comparison rules (17 rules, 3 severity levels)\n seo-ecommerce/ # E-commerce SEO (v1.9.0, by Matej Marjanovic)\n SKILL.md\n references/ # Marketplace API endpoints\n seo-dataforseo/SKILL.md # Live SEO data via DataForSEO MCP (extension mirror)\n seo-image-gen/ # AI image generation for SEO assets (extension mirror)\n SKILL.md\n references/ # Image gen reference files (7 files)\n agents/ # 18 subagents (auto-discovered)\n seo-technical.md # Crawlability, indexability, security\n seo-content.md # E-E-A-T, readability, thin content\n seo-schema.md # Structured data validation\n seo-sitemap.md # Sitemap quality gates\n seo-performance.md # Core Web Vitals, page speed\n seo-visual.md # Screenshots, mobile rendering\n seo-geo.md # AI crawler access, GEO, citability\n seo-local.md # GBP, NAP, citations, reviews, local schema\n seo-maps.md # Geo-grid, GBP audit, reviews, competitor radius\n seo-google.md # Google API analyst (CrUX, GSC, GA4)\n seo-backlinks.md # Backlink profile analyst (Moz, Bing, CC, verify)\n seo-dataforseo.md # DataForSEO data analyst\n seo-image-gen.md # SEO image audit analyst\n seo-cluster.md # Semantic clustering analysis\n seo-sxo.md # Search experience optimization\n seo-drift.md # SEO drift monitoring\n seo-ecommerce.md # E-commerce SEO analysis\n seo-flow.md # FLOW framework integration\n hooks/ # Quality gate hooks\n hooks.json # PostToolUse schema validation\n scripts/ # 53 Python execution scripts\n google_auth.py # Credential management (OAuth, SA, API key, 4-tier detection)\n backlinks_auth.py # Backlink API credential management (Moz, Bing)\n moz_api.py # Moz Link Explorer API (DA/PA, spam, domains, anchors)\n bing_webmaster.py # Bing Webmaster Tools API (registered-site links/comparison)\n commoncrawl_graph.py # Common Crawl web graph parser (PageRank, in-degree)\n verify_backlinks.py # Backlink existence verification crawler\n pagespeed_check.py # PSI v5 + CrUX API\n crux_history.py # CrUX History API (25-week trends)\n gsc_query.py # Search Console (queries, pages, sitemaps, sites)\n gsc_inspect.py # URL Inspection (single + batch)\n indexing_notify.py # Indexing API v3 (URL_UPDATED/URL_DELETED)\n ga4_report.py # GA4 organic traffic reports\n google_report.py # PDF/HTML report generator (WeasyPrint + matplotlib)\n youtube_search.py # YouTube Data API v3\n nlp_analyze.py # Cloud Natural Language API\n keyword_planner.py # Google Ads Keyword Planner\n fetch_page.py # Page fetcher with UA rotation\n parse_html.py # HTML parser for SEO elements\n capture_screenshot.py # Playwright screenshots\n analyze_visual.py # Visual analysis helper\n drift_baseline.py # SEO drift baseline capture (SQLite)\n drift_compare.py # SEO drift comparison engine (17 rules)\n drift_report.py # SEO drift HTML report generator\n drift_history.py # SEO drift history query\n dataforseo_costs.py # DataForSEO cost estimation and budget tracking\n dataforseo_merchant.py # Google Shopping / Amazon data fetching\n dataforseo_normalize.py # DataForSEO response normalization utility\n sync_flow.py # FLOW prompt library sync (GitHub API, CC BY 4.0 headers, --dry-run, --ref)\n url_safety.py # Canonical URL/SSRF safety module (validate, DNS-pin, safe fetch)\n render_page.py # Shared headless renderer (SPA-aware, Playwright)\n lcp_subparts.py # LCP subparts breakdown via CrUX API\n preload_check.py # Speculation Rules / bfcache / prerender / preload detector\n agent_ux_check.py # Agent-friendly page auditor\n content_quality.py # QRG-aligned content quality detector\n content_humanize.py # AI-pattern remover (rewrites AI-typical phrasing)\n content_verify.py # Claim extractor + citation-gap detector\n schema_generate.py # JSON-LD generators for high-leverage v2 schema types\n schema_ecommerce_validate.py # Product schema validator (merchant-listing requirements)\n iptc_ai_label.py # IPTC DigitalSourceType audit/injection for AI imagery\n parasite_risk.py # Parasite-SEO risk scanner\n gbp_deprecation_lint.py # GBP feature-deprecation linter\n domain_history.py # Expired-domain heritage check\n seo_updates.py # Primary-source Google updates query tool\n indexnow_submit.py # IndexNow submitter\n ucp_check.py # UCP (Universal Commerce Protocol) profile auditor\n unlighthouse_run.py # Unlighthouse CLI wrapper (site-wide Lighthouse)\n validate_backlink_report.py # Backlink report validation\n portability_check.py # Cross-platform portability lint for SKILL.md files\n consistency_check.py # Reference-graph gate: dead refs, routing, lock, orphans\n release_sign.py # SHA-256 manifest generator for release signing\n verify_release.py # Verify checkout integrity against a release manifest\n mobile_analysis.py # Mobile rendering analysis (gitignored, dev-only)\n schema/ # Schema.org JSON-LD templates\n extensions/ # Optional add-on install helpers\n dataforseo/ # DataForSEO MCP install scripts\n firecrawl/ # Firecrawl MCP install scripts\n banana/ # Banana MCP install scripts\n ahrefs/ # Ahrefs MCP install scripts\n bing-webmaster/ # Bing Webmaster and IndexNow install scripts\n profound/ # Profound MCP install scripts\n seranking/ # SE Ranking MCP install scripts\n unlighthouse/ # Unlighthouse install scripts\n docs/ # Extended documentation\n```\n\n## Commands\n\n| Command | Use Case |\n|---------|----------|\n| `/seo audit ` | Full website audit with parallel subagents |\n| `/seo page ` | Single page analysis |\n| `/seo technical ` | Technical SEO across 9 categories |\n| `/seo content ` | E-E-A-T and content quality |\n| `/seo content-brief ` | Detailed content brief: keywords, outline, internal links |\n| `/seo schema ` | Schema markup detection, validation, generation |\n| `/seo sitemap ` | Sitemap validation |\n| `/seo sitemap generate` | Create new sitemap with industry templates |\n| `/seo images ` | Image optimization |\n| `/seo geo ` | AI search optimization (GEO) |\n| `/seo local ` | Local SEO (GBP, citations, reviews) |\n| `/seo maps [command]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo cluster ` | SERP-based semantic clustering |\n| `/seo sxo ` | Search Experience Optimization |\n| `/seo drift baseline\\|compare\\|history ` | SEO drift monitoring |\n| `/seo ecommerce ` | E-commerce SEO |\n| `/seo hreflang [url]` | Hreflang and international SEO |\n| `/seo plan ` | Strategic planning by industry |\n| `/seo programmatic [url\\|plan]` | Programmatic SEO analysis |\n| `/seo competitor-pages [url\\|generate]` | Competitor comparison pages |\n| `/seo flow [stage] [url\\|topic]` | FLOW framework prompts |\n| `/seo google [command] [url]` | Google SEO APIs (GSC, PSI, CrUX, GA4) |\n| `/seo dataforseo [command]` | Live SEO data (extension) |\n| `/seo image-gen [use-case] ` | AI image generation (extension) |\n| `/seo firecrawl [command] ` | Full-site crawling (extension) |\n| `/seo ahrefs [command] ` | Backlinks, organic keywords, and content data via the official Ahrefs MCP (extension) |\n| `/seo seranking [command]` | AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode (extension) |\n| `/seo profound [command]` | LLM citation tracking with time-series data (extension) |\n| `/seo bing [command] ` | Bing Webmaster Tools + IndexNow URL submission (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse runner, runs locally (extension) |\n\n## Development Rules\n\n- Keep SKILL.md files under 500 lines / 5000 tokens\n- Reference files should be focused and under 200 lines\n- Scripts must have docstrings, CLI interface, and JSON output\n- Follow kebab-case naming for all skill directories\n- Agents invoked via Agent tool, never via Bash\n- Bundled tools run through `claude-seo run`; plugin state uses `CLAUDE_PLUGIN_DATA`\n- Manual Python dependencies install into `~/.claude/skills/seo/.venv/`\n- Test with `python3 -m pytest tests/` after changes (if applicable)\n\n## Security Rules\n\n- **Never commit credentials**: `.env`, `client_secret*.json`, `oauth-token.json`, `service_account*.json` are all in `.gitignore`\n- **URL validation**: All scripts that connect to user-supplied URLs must use `scripts/url_safety.py` (`validate_url_strict()` plus the pinned safe request helpers). This blocks private IPs, loopback, metadata endpoints, redirect rebinding, and DNS rebinding.\n- **OAuth tokens**: Never store `client_secret` in the token file. Read it from the client_secret.json file at runtime.\n- **No hardcoded paths**: Use `os.path.dirname(os.path.abspath(__file__))` for relative paths, never a user-specific absolute path\n- **Config location**: `~/.config/claude-seo/google-api.json` and `~/.config/claude-seo/backlinks-api.json` (user-space, not in repo)\n\n## Report Generation Rules\n\n- **All SEO reports must use `scripts/google_report.py`** as the canonical report generator\n- **Dependencies**: `matplotlib>=3.8.0` (charts) + `weasyprint>=61.0` (HTML-to-PDF), both in `requirements.txt`\n- **Format**: A4 PDF via WeasyPrint + matplotlib charts at 200 DPI\n- **Style**: Clean white title page with navy (#1e3a5f) accent, Times New Roman body font\n- **Color palette**: Navy #1e3a5f (headers), dark gold #b8860b (accents), forest green #2d6a4f (pass), warm amber #d4740e (warnings), deep red #c53030 (fail), warm cream #faf9f7 (backgrounds)\n- **Structure**: Title page → TOC with scores → Executive Summary → Data sections → Recommendations → Methodology\n- **Charts**: 85% width, max-height 120mm, figure captions on every chart, saved to `charts/` at 200 DPI\n- **No `page-break-inside: avoid`** on any element (causes white gaps in WeasyPrint)\n- **Post-generation review**: `_review_pdf()` runs automatically, checking for empty images, thin sections, duplicates\n- **Before presenting any PDF to the user**: verify the review passes (`\"status\": \"PASS\"`)\n- **Cross-skill enforcement**: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: \"Generate a PDF report? Use `/seo google report`\"\n- **Google logo** appears on title page when using Google API data (\"Powered by Google APIs\")\n\n## Ecosystem\n\nPart of the Claude Code skill family:\n- [Claude Banana](https://github.com/AgriciDaniel/banana-claude) -- standalone image gen (bundled as extension here)\n- [Claude Blog](https://github.com/AgriciDaniel/claude-blog) -- companion blog engine, consumes SEO findings\n- [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) -- community marketing suite (copy, emails, ads, funnels, CRO)\n\n## Key Principles\n\n1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Parallel Execution**: Full audits spawn up to 15 subagents simultaneously\n4. **Extension System**: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, and Unlighthouse extensions\n\n## Repository Topology (public + private)\n\nThis project is mirrored across two GitHub remotes that share git history.\nBoth originate from the same local checkout; neither is a GitHub fork of\nthe other (different orgs, no parent/child relationship in the GitHub UI).\n\n| Remote | URL | Visibility | Role |\n|---|---|---|---|\n| `origin` | `https://github.com/AgriciDaniel/claude-seo` | **Public** | Published distribution. Users discover, clone, and install from here. `main` only reflects released history. |\n| `aimh` | `https://github.com/AI-Marketing-Hub/claude-seo` | **Private** | Working repo inside the AI Marketing Hub org. Daily development. v2 branch + post-release work lives here before promotion to public. |\n\n### Workflow\n\nDaily development:\n- Work on `v2` (or feature branches off `v2`) locally.\n- `git push aimh ` to publish work-in-progress to the private repo\n (Dependabot, Actions, and CI run there).\n\nPromoting to public on release:\n1. Merge `v2` into local `main` when ready to release (fast-forward).\n2. Tag the release locally (`git tag -a vX.Y.Z`).\n3. Push the tag and main to **both** remotes in this order:\n - First: `git push aimh main && git push aimh vX.Y.Z`\n - Then: `git push origin vX.Y.Z && git push origin main`\n - The \"tag before merge\" sequence (see `feedback_push_caution` memory)\n applies on `origin` to avoid the `curl|bash` outage window where\n users pull a tag that doesn't yet point at code on `main`.\n4. `gh release create vX.Y.Z --repo AgriciDaniel/claude-seo` (public-only).\n5. `/release-blog` to publish the release post.\n\n### Safety rules\n\n- **Never push to `origin/main` autonomously.** The public is release-only;\n pushes are user-authorized per-release.\n- **`aimh` accepts day-to-day pushes.** No release-gate ceremony required\n for the private remote.\n- **Tags push to private first.** Historical pre-release illustration: v2.0.0\n once lived on `aimh` before `origin`. Current released tags through v2.2.4\n are on both remotes.\n- **History stays shared.** Never rewrite history on either remote with\n force-push unless explicitly authorized for that specific operation.\n\n### Verifying the topology\n\n```bash\n# Both remotes configured\ngit remote -v # expects: origin (public) + aimh (private)\n\n# Both share main HEAD\ngit ls-remote --heads aimh main\ngit ls-remote --heads origin main # origin = aimh/main + 1 public-branding commit (intentional; see docs/WORKFLOW-public-private.md)\n```\n\nFull workflow reference: `docs/WORKFLOW-public-private.md`.\n\n## Release Blog Post\n\nAfter cutting a new release (git tag + `gh release create`), run:\n\n```\n/release-blog\n```\n\nThis generates a blog post on https://claude-seo.md/blog/, handles cover image generation, SEO metadata, FAQ schema, internal linking, sitemap/llms.txt updates, Vercel deployment, and Google indexing.\n"},"files":{"AGENTS.md":"# Claude SEO: Multi-Platform Agent Instructions\n\n> For **Cursor**, **Cursor Cloud Agents**, **Google Antigravity**, **Gemini CLI**,\n> **Grok Build**,\n> **OpenAI Codex CLI**, **Cline**, **Aider**, and any other agent harness that\n> reads project-root agent instructions.\n>\n> Claude Code users: see `CLAUDE.md` instead.\n\n## Cross-platform portability (v2.0.0)\n\nEvery skill in `skills/*/SKILL.md` is authored to a portable subset of the\nClaude Code skill spec. Validate compatibility with your harness via:\n\n```bash\n./bin/claude-seo run portability_check.py\n```\n\nThe check confirms each `SKILL.md` has the minimum frontmatter every harness\nexpects (`name`, `description`, optional `model`, optional `tools`) and warns\non Claude-Code-specific features (`maxTurns`, multi-line tool list with\ndescriptive comments) that other harnesses may ignore but do not reject.\n\n### Per-harness notes\n\n| Harness | How to load claude-seo |\n|---|---|\n| **Cursor** | Symlink or copy `skills/` and `agents/` into `.cursor/rules/`. Commands are invoked as text prompts; the harness reads `SKILL.md` body as system context. |\n| **Cursor Cloud Agents** | Push the repo; Cloud Agents read `AGENTS.md` automatically at session start. |\n| **Google Antigravity** | Point the workspace at this repo root; Antigravity reads `AGENTS.md` first, falls back to `skills/`. |\n| **Gemini CLI** | `gemini init` in this repo loads `AGENTS.md`. Skills are activated via `activate_skill ` in conversation. |\n| **Grok Build** | Open this repository in Grok Build. It reads `AGENTS.md` and Claude Code compatible plugins and skills without a separate layout. Use `grok inspect` to verify discovery. See the [official compatibility guide](https://docs.x.ai/build/features/skills-plugins-marketplaces). |\n| **OpenAI Codex CLI** | Reads `AGENTS.md` from project root. Bash tools work as documented; some Claude-specific tool names (Read/Write/Edit) are aliased to Codex equivalents transparently. |\n| **Cline** | Loads `AGENTS.md` from project root. Skills appear as system messages; subagent delegation falls back to in-context expansion. |\n| **Aider** | Reads `AGENTS.md` if present; otherwise falls back to README. Aider does not support sub-agent dispatch; the seo-* skills run inline. |\n\n### Tool-name compatibility\n\nWhere claude-seo skills mention Claude Code tools (`Read`, `Write`, `Edit`,\n`Bash`, `Glob`, `Grep`, `WebFetch`), each harness typically has an equivalent:\n\n| Claude Code | Codex | Cline | Aider | Cursor / Antigravity |\n|---|---|---|---|---|\n| Read | read_file | read_file | (inline) | read |\n| Write | write_file | write_file | /add then edit | write |\n| Edit | apply_diff | replace_in_file | /edit | edit |\n| Bash | bash | execute_command | /run | shell |\n| Glob | glob | search_files | (inline) | find |\n| Grep | grep | search_files | /grep | grep |\n| WebFetch | fetch / browse | (browser tool) | (n/a) | fetch |\n\nThese mappings are automatic in most harnesses; we list them for transparency\nin case a recipe needs a specific call.\n\n## Overview\n\nClaude SEO is a Tier 4 SEO analysis skill with 25 sub-skills (21 core + 1 orchestrator +\n1 framework integration + 2 extension mirrors), 18 sub-agents (15 core + 1 framework\nintegration + 2 extension mirrors), and 53 Python execution scripts.\n\n## Quick Reference\n\n| Command | What it does |\n|---------|-------------|\n| `/seo audit ` | Full website audit with parallel subagent delegation |\n| `/seo page ` | Deep single-page analysis |\n| `/seo technical ` | Technical SEO audit (9 categories) |\n| `/seo content ` | E-E-A-T and content quality analysis |\n| `/seo content-brief ` | Generate a content brief for a topic |\n| `/seo schema ` | Schema.org detection, validation, generation |\n| `/seo sitemap ` | XML sitemap analysis or generation |\n| `/seo images ` | Image SEO: on-page audit, SERP analysis, file optimization |\n| `/seo geo ` | AI Overviews / Generative Engine Optimization |\n| `/seo plan ` | Strategic SEO planning |\n| `/seo cluster ` | SERP-based semantic clustering and content architecture |\n| `/seo sxo ` | Search Experience Optimization: page-type analysis, personas |\n| `/seo drift baseline ` | Capture SEO baseline for change monitoring |\n| `/seo drift compare ` | Compare current state to stored baseline |\n| `/seo drift history ` | Show drift history over time |\n| `/seo ecommerce ` | E-commerce SEO: product schema, marketplace intelligence |\n| `/seo programmatic [url]` | Programmatic SEO at scale |\n| `/seo competitor-pages [url]` | Competitor comparison pages |\n| `/seo flow [stage]` | FLOW framework prompts (Find, Leverage, Optimize, Win, Local; prompts/sync utilities.) |\n| `/seo local ` | Local SEO analysis (GBP, citations, reviews) |\n| `/seo maps [cmd] [args]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo hreflang ` | Hreflang/i18n SEO audit, cultural profiles, content parity |\n| `/seo google [cmd] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo backlinks setup` | Setup free backlink APIs |\n| `/seo backlinks verify ` | Verify known backlinks still exist |\n| `/seo dataforseo [cmd]` | Live SEO data via DataForSEO (extension) |\n| `/seo image-gen [use-case]` | AI image generation for SEO assets (extension) |\n| `/seo firecrawl [cmd] ` | Full-site crawling and site mapping (extension) |\n| `/seo ahrefs [cmd] ` | Ahrefs backlink and keyword data (extension) |\n| `/seo bing [cmd] ` | Bing Webmaster data and IndexNow (extension) |\n| `/seo profound [cmd]` | LLM brand-citation tracking (extension) |\n| `/seo seranking [cmd]` | AI share-of-voice tracking (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse audits (extension) |\n\n## Using with Cursor / Cursor Cloud\n\nCursor reads this file automatically. All SKILL.md files contain the full\nanalysis logic as natural language instructions. Python scripts in `scripts/`\nprovide execution capabilities.\n\n**Running scripts directly** (Cursor doesn't have MCP):\n```bash\n# Page fetching with SSRF protection\n./bin/claude-seo run fetch_page.py https://example.com\n\n# HTML parsing for SEO elements\n./bin/claude-seo run parse_html.py https://example.com\n\n# PageSpeed Insights\n./bin/claude-seo run pagespeed_check.py https://example.com --json\n\n# Drift baseline\n./bin/claude-seo run drift_baseline.py https://example.com\n\n# DataForSEO (requires credentials)\nDATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass ./bin/claude-seo run dataforseo_merchant.py search \"keyword\"\n```\n\n**Cursor Cloud gotchas:**\n- SSL certificates may not resolve for some domains. Investigate the certificate issue rather than disabling verification.\n- Run bundled tools through `claude-seo`; never call the venv interpreter directly.\n- Screenshots save to `/tmp/` not CWD. Check absolute paths.\n\n## Using with Google Antigravity\n\nAntigravity discovers this project via `.claude-plugin/plugin.json`.\nPlace the repo in `~/.gemini/antigravity/plugins/claude-seo/` or install via:\n\n```bash\nbash install.sh\n```\n\n## Architecture\n\n```\nskills/ # 25 sub-skills (auto-discovered)\n seo/SKILL.md # Main orchestrator + routing\n seo-cluster/ # Semantic clustering (v1.9.0)\n seo-sxo/ # Search Experience Optimization (v1.9.0)\n seo-drift/ # SEO drift monitoring (v1.9.0)\n seo-ecommerce/ # E-commerce SEO (v1.9.0)\n seo-audit/ # Full site audit\n seo-page/ # Single-page analysis\n seo-technical/ # Technical SEO\n seo-content/ # E-E-A-T quality\n seo-content-brief/ # Content brief generation\n seo-schema/ # Schema.org markup\n seo-sitemap/ # XML sitemaps\n seo-images/ # Image optimization\n seo-geo/ # AI search / GEO\n seo-local/ # Local SEO\n seo-maps/ # Maps intelligence\n seo-plan/ # Strategic planning\n seo-hreflang/ # International SEO\n seo-google/ # Google APIs\n seo-backlinks/ # Backlink analysis\n seo-programmatic/ # Programmatic SEO\n seo-competitor-pages/ # Competitor pages\n seo-flow/ # FLOW framework integration\n seo-dataforseo/ # DataForSEO (extension)\n seo-image-gen/ # AI images (extension)\nagents/ # 18 subagents\nscripts/ # 53 Python scripts, including the managed runtime\nschema/ # JSON-LD templates\nextensions/ # 8 MCP extensions: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, Unlighthouse\n```\n\n## Key Principles\n\n1. **Progressive Disclosure**: Read SKILL.md for routing, load references on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Security**: All scripts call `validate_url()` for SSRF protection\n4. **Config location**: `~/.config/claude-seo/` for API credentials\n\n## Credits\n\nCreated by [@AgriciDaniel](https://github.com/AgriciDaniel).\nv1.9.0 community contributions by Lutfiya Miller, Chris Muller, Florian Schmitz,\nDan Colta, and Matej Marjanovic. See [CONTRIBUTORS.md](CONTRIBUTORS.md).\n","CLAUDE.md":"# Claude SEO: Universal SEO Analysis Skill\n\n## Project Overview\n\nThis repository contains **Claude SEO**, a Tier 4 Claude Code skill for comprehensive\nSEO analysis across all industries. It follows the Agent Skills open standard and the\n3-layer architecture (directive, orchestration, execution). 25 sub-skills (21 core +\n1 orchestrator + 1 framework integration + 2 extension mirrors), 18 sub-agents (15 core +\n1 framework integration + 2 extension mirrors), and an extensible reference\nsystem cover technical SEO, content quality,\nschema markup, image optimization, sitemap architecture, AI search optimization,\nlocal SEO (GBP, citations, reviews, map pack), maps intelligence, semantic topic\nclustering, search experience optimization (SXO), SEO drift monitoring, e-commerce\nSEO, and international SEO with cultural adaptation profiles.\n\n## Architecture\n\n```\nclaude-seo/\n CLAUDE.md # Project instructions (this file)\n CONTRIBUTORS.md # Community credits (Pro Hub Challenge)\n AGENTS.md # Multi-platform agent instructions (Cursor, Antigravity)\n .claude-plugin/\n plugin.json # Plugin manifest (v2.2.4)\n marketplace.json # Marketplace catalog for distribution\n skills/ # 25 sub-skills (auto-discovered)\n seo/ # Main orchestrator skill\n SKILL.md # Entry point, routing table, core rules\n references/ # On-demand knowledge files (13 files)\n seo-audit/SKILL.md # Full site audit with parallel agents\n seo-page/SKILL.md # Deep single-page analysis\n seo-technical/SKILL.md # Technical SEO (9 categories)\n seo-content/SKILL.md # E-E-A-T and content quality\n seo-content-brief/SKILL.md # Content brief generation\n seo-schema/SKILL.md # Schema.org markup detection/generation\n seo-sitemap/SKILL.md # XML sitemap analysis/generation\n seo-images/SKILL.md # Image optimization analysis\n seo-geo/SKILL.md # AI search / GEO optimization\n seo-local/SKILL.md # Local SEO (GBP, citations, reviews, map pack)\n seo-maps/SKILL.md # Maps intelligence (geo-grid, GBP audit, reviews, competitors)\n seo-plan/SKILL.md # Strategic SEO planning\n seo-flow/SKILL.md # FLOW framework integration\n seo-programmatic/SKILL.md # Programmatic SEO at scale\n seo-competitor-pages/SKILL.md # Competitor comparison pages\n seo-hreflang/SKILL.md # International SEO / hreflang\n seo-google/ # Google SEO APIs\n SKILL.md\n references/ # API reference files (11 files)\n seo-backlinks/SKILL.md # Backlink profile analysis\n seo-cluster/ # Semantic topic clustering (v1.9.0, by Lutfiya Miller)\n SKILL.md\n references/ # Clustering methodology, architecture, workflow\n templates/ # cluster-map.html interactive visualization\n seo-sxo/ # Search Experience Optimization (v1.9.0, by Florian Schmitz)\n SKILL.md\n references/ # Page-type taxonomy, user stories, personas, wireframes\n seo-drift/ # SEO drift monitoring (v1.9.0, by Dan Colta)\n SKILL.md\n references/ # Comparison rules (17 rules, 3 severity levels)\n seo-ecommerce/ # E-commerce SEO (v1.9.0, by Matej Marjanovic)\n SKILL.md\n references/ # Marketplace API endpoints\n seo-dataforseo/SKILL.md # Live SEO data via DataForSEO MCP (extension mirror)\n seo-image-gen/ # AI image generation for SEO assets (extension mirror)\n SKILL.md\n references/ # Image gen reference files (7 files)\n agents/ # 18 subagents (auto-discovered)\n seo-technical.md # Crawlability, indexability, security\n seo-content.md # E-E-A-T, readability, thin content\n seo-schema.md # Structured data validation\n seo-sitemap.md # Sitemap quality gates\n seo-performance.md # Core Web Vitals, page speed\n seo-visual.md # Screenshots, mobile rendering\n seo-geo.md # AI crawler access, GEO, citability\n seo-local.md # GBP, NAP, citations, reviews, local schema\n seo-maps.md # Geo-grid, GBP audit, reviews, competitor radius\n seo-google.md # Google API analyst (CrUX, GSC, GA4)\n seo-backlinks.md # Backlink profile analyst (Moz, Bing, CC, verify)\n seo-dataforseo.md # DataForSEO data analyst\n seo-image-gen.md # SEO image audit analyst\n seo-cluster.md # Semantic clustering analysis\n seo-sxo.md # Search experience optimization\n seo-drift.md # SEO drift monitoring\n seo-ecommerce.md # E-commerce SEO analysis\n seo-flow.md # FLOW framework integration\n hooks/ # Quality gate hooks\n hooks.json # PostToolUse schema validation\n scripts/ # 53 Python execution scripts\n google_auth.py # Credential management (OAuth, SA, API key, 4-tier detection)\n backlinks_auth.py # Backlink API credential management (Moz, Bing)\n moz_api.py # Moz Link Explorer API (DA/PA, spam, domains, anchors)\n bing_webmaster.py # Bing Webmaster Tools API (registered-site links/comparison)\n commoncrawl_graph.py # Common Crawl web graph parser (PageRank, in-degree)\n verify_backlinks.py # Backlink existence verification crawler\n pagespeed_check.py # PSI v5 + CrUX API\n crux_history.py # CrUX History API (25-week trends)\n gsc_query.py # Search Console (queries, pages, sitemaps, sites)\n gsc_inspect.py # URL Inspection (single + batch)\n indexing_notify.py # Indexing API v3 (URL_UPDATED/URL_DELETED)\n ga4_report.py # GA4 organic traffic reports\n google_report.py # PDF/HTML report generator (WeasyPrint + matplotlib)\n youtube_search.py # YouTube Data API v3\n nlp_analyze.py # Cloud Natural Language API\n keyword_planner.py # Google Ads Keyword Planner\n fetch_page.py # Page fetcher with UA rotation\n parse_html.py # HTML parser for SEO elements\n capture_screenshot.py # Playwright screenshots\n analyze_visual.py # Visual analysis helper\n drift_baseline.py # SEO drift baseline capture (SQLite)\n drift_compare.py # SEO drift comparison engine (17 rules)\n drift_report.py # SEO drift HTML report generator\n drift_history.py # SEO drift history query\n dataforseo_costs.py # DataForSEO cost estimation and budget tracking\n dataforseo_merchant.py # Google Shopping / Amazon data fetching\n dataforseo_normalize.py # DataForSEO response normalization utility\n sync_flow.py # FLOW prompt library sync (GitHub API, CC BY 4.0 headers, --dry-run, --ref)\n url_safety.py # Canonical URL/SSRF safety module (validate, DNS-pin, safe fetch)\n render_page.py # Shared headless renderer (SPA-aware, Playwright)\n lcp_subparts.py # LCP subparts breakdown via CrUX API\n preload_check.py # Speculation Rules / bfcache / prerender / preload detector\n agent_ux_check.py # Agent-friendly page auditor\n content_quality.py # QRG-aligned content quality detector\n content_humanize.py # AI-pattern remover (rewrites AI-typical phrasing)\n content_verify.py # Claim extractor + citation-gap detector\n schema_generate.py # JSON-LD generators for high-leverage v2 schema types\n schema_ecommerce_validate.py # Product schema validator (merchant-listing requirements)\n iptc_ai_label.py # IPTC DigitalSourceType audit/injection for AI imagery\n parasite_risk.py # Parasite-SEO risk scanner\n gbp_deprecation_lint.py # GBP feature-deprecation linter\n domain_history.py # Expired-domain heritage check\n seo_updates.py # Primary-source Google updates query tool\n indexnow_submit.py # IndexNow submitter\n ucp_check.py # UCP (Universal Commerce Protocol) profile auditor\n unlighthouse_run.py # Unlighthouse CLI wrapper (site-wide Lighthouse)\n validate_backlink_report.py # Backlink report validation\n portability_check.py # Cross-platform portability lint for SKILL.md files\n consistency_check.py # Reference-graph gate: dead refs, routing, lock, orphans\n release_sign.py # SHA-256 manifest generator for release signing\n verify_release.py # Verify checkout integrity against a release manifest\n mobile_analysis.py # Mobile rendering analysis (gitignored, dev-only)\n schema/ # Schema.org JSON-LD templates\n extensions/ # Optional add-on install helpers\n dataforseo/ # DataForSEO MCP install scripts\n firecrawl/ # Firecrawl MCP install scripts\n banana/ # Banana MCP install scripts\n ahrefs/ # Ahrefs MCP install scripts\n bing-webmaster/ # Bing Webmaster and IndexNow install scripts\n profound/ # Profound MCP install scripts\n seranking/ # SE Ranking MCP install scripts\n unlighthouse/ # Unlighthouse install scripts\n docs/ # Extended documentation\n```\n\n## Commands\n\n| Command | Use Case |\n|---------|----------|\n| `/seo audit ` | Full website audit with parallel subagents |\n| `/seo page ` | Single page analysis |\n| `/seo technical ` | Technical SEO across 9 categories |\n| `/seo content ` | E-E-A-T and content quality |\n| `/seo content-brief ` | Detailed content brief: keywords, outline, internal links |\n| `/seo schema ` | Schema markup detection, validation, generation |\n| `/seo sitemap ` | Sitemap validation |\n| `/seo sitemap generate` | Create new sitemap with industry templates |\n| `/seo images ` | Image optimization |\n| `/seo geo ` | AI search optimization (GEO) |\n| `/seo local ` | Local SEO (GBP, citations, reviews) |\n| `/seo maps [command]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo cluster ` | SERP-based semantic clustering |\n| `/seo sxo ` | Search Experience Optimization |\n| `/seo drift baseline\\|compare\\|history ` | SEO drift monitoring |\n| `/seo ecommerce ` | E-commerce SEO |\n| `/seo hreflang [url]` | Hreflang and international SEO |\n| `/seo plan ` | Strategic planning by industry |\n| `/seo programmatic [url\\|plan]` | Programmatic SEO analysis |\n| `/seo competitor-pages [url\\|generate]` | Competitor comparison pages |\n| `/seo flow [stage] [url\\|topic]` | FLOW framework prompts |\n| `/seo google [command] [url]` | Google SEO APIs (GSC, PSI, CrUX, GA4) |\n| `/seo dataforseo [command]` | Live SEO data (extension) |\n| `/seo image-gen [use-case] ` | AI image generation (extension) |\n| `/seo firecrawl [command] ` | Full-site crawling (extension) |\n| `/seo ahrefs [command] ` | Backlinks, organic keywords, and content data via the official Ahrefs MCP (extension) |\n| `/seo seranking [command]` | AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode (extension) |\n| `/seo profound [command]` | LLM citation tracking with time-series data (extension) |\n| `/seo bing [command] ` | Bing Webmaster Tools + IndexNow URL submission (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse runner, runs locally (extension) |\n\n## Development Rules\n\n- Keep SKILL.md files under 500 lines / 5000 tokens\n- Reference files should be focused and under 200 lines\n- Scripts must have docstrings, CLI interface, and JSON output\n- Follow kebab-case naming for all skill directories\n- Agents invoked via Agent tool, never via Bash\n- Bundled tools run through `claude-seo run`; plugin state uses `CLAUDE_PLUGIN_DATA`\n- Manual Python dependencies install into `~/.claude/skills/seo/.venv/`\n- Test with `python3 -m pytest tests/` after changes (if applicable)\n\n## Security Rules\n\n- **Never commit credentials**: `.env`, `client_secret*.json`, `oauth-token.json`, `service_account*.json` are all in `.gitignore`\n- **URL validation**: All scripts that connect to user-supplied URLs must use `scripts/url_safety.py` (`validate_url_strict()` plus the pinned safe request helpers). This blocks private IPs, loopback, metadata endpoints, redirect rebinding, and DNS rebinding.\n- **OAuth tokens**: Never store `client_secret` in the token file. Read it from the client_secret.json file at runtime.\n- **No hardcoded paths**: Use `os.path.dirname(os.path.abspath(__file__))` for relative paths, never a user-specific absolute path\n- **Config location**: `~/.config/claude-seo/google-api.json` and `~/.config/claude-seo/backlinks-api.json` (user-space, not in repo)\n\n## Report Generation Rules\n\n- **All SEO reports must use `scripts/google_report.py`** as the canonical report generator\n- **Dependencies**: `matplotlib>=3.8.0` (charts) + `weasyprint>=61.0` (HTML-to-PDF), both in `requirements.txt`\n- **Format**: A4 PDF via WeasyPrint + matplotlib charts at 200 DPI\n- **Style**: Clean white title page with navy (#1e3a5f) accent, Times New Roman body font\n- **Color palette**: Navy #1e3a5f (headers), dark gold #b8860b (accents), forest green #2d6a4f (pass), warm amber #d4740e (warnings), deep red #c53030 (fail), warm cream #faf9f7 (backgrounds)\n- **Structure**: Title page → TOC with scores → Executive Summary → Data sections → Recommendations → Methodology\n- **Charts**: 85% width, max-height 120mm, figure captions on every chart, saved to `charts/` at 200 DPI\n- **No `page-break-inside: avoid`** on any element (causes white gaps in WeasyPrint)\n- **Post-generation review**: `_review_pdf()` runs automatically, checking for empty images, thin sections, duplicates\n- **Before presenting any PDF to the user**: verify the review passes (`\"status\": \"PASS\"`)\n- **Cross-skill enforcement**: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: \"Generate a PDF report? Use `/seo google report`\"\n- **Google logo** appears on title page when using Google API data (\"Powered by Google APIs\")\n\n## Ecosystem\n\nPart of the Claude Code skill family:\n- [Claude Banana](https://github.com/AgriciDaniel/banana-claude) -- standalone image gen (bundled as extension here)\n- [Claude Blog](https://github.com/AgriciDaniel/claude-blog) -- companion blog engine, consumes SEO findings\n- [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) -- community marketing suite (copy, emails, ads, funnels, CRO)\n\n## Key Principles\n\n1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Parallel Execution**: Full audits spawn up to 15 subagents simultaneously\n4. **Extension System**: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, and Unlighthouse extensions\n\n## Repository Topology (public + private)\n\nThis project is mirrored across two GitHub remotes that share git history.\nBoth originate from the same local checkout; neither is a GitHub fork of\nthe other (different orgs, no parent/child relationship in the GitHub UI).\n\n| Remote | URL | Visibility | Role |\n|---|---|---|---|\n| `origin` | `https://github.com/AgriciDaniel/claude-seo` | **Public** | Published distribution. Users discover, clone, and install from here. `main` only reflects released history. |\n| `aimh` | `https://github.com/AI-Marketing-Hub/claude-seo` | **Private** | Working repo inside the AI Marketing Hub org. Daily development. v2 branch + post-release work lives here before promotion to public. |\n\n### Workflow\n\nDaily development:\n- Work on `v2` (or feature branches off `v2`) locally.\n- `git push aimh ` to publish work-in-progress to the private repo\n (Dependabot, Actions, and CI run there).\n\nPromoting to public on release:\n1. Merge `v2` into local `main` when ready to release (fast-forward).\n2. Tag the release locally (`git tag -a vX.Y.Z`).\n3. Push the tag and main to **both** remotes in this order:\n - First: `git push aimh main && git push aimh vX.Y.Z`\n - Then: `git push origin vX.Y.Z && git push origin main`\n - The \"tag before merge\" sequence (see `feedback_push_caution` memory)\n applies on `origin` to avoid the `curl|bash` outage window where\n users pull a tag that doesn't yet point at code on `main`.\n4. `gh release create vX.Y.Z --repo AgriciDaniel/claude-seo` (public-only).\n5. `/release-blog` to publish the release post.\n\n### Safety rules\n\n- **Never push to `origin/main` autonomously.** The public is release-only;\n pushes are user-authorized per-release.\n- **`aimh` accepts day-to-day pushes.** No release-gate ceremony required\n for the private remote.\n- **Tags push to private first.** Historical pre-release illustration: v2.0.0\n once lived on `aimh` before `origin`. Current released tags through v2.2.4\n are on both remotes.\n- **History stays shared.** Never rewrite history on either remote with\n force-push unless explicitly authorized for that specific operation.\n\n### Verifying the topology\n\n```bash\n# Both remotes configured\ngit remote -v # expects: origin (public) + aimh (private)\n\n# Both share main HEAD\ngit ls-remote --heads aimh main\ngit ls-remote --heads origin main # origin = aimh/main + 1 public-branding commit (intentional; see docs/WORKFLOW-public-private.md)\n```\n\nFull workflow reference: `docs/WORKFLOW-public-private.md`.\n\n## Release Blog Post\n\nAfter cutting a new release (git tag + `gh release create`), run:\n\n```\n/release-blog\n```\n\nThis generates a blog post on https://claude-seo.md/blog/, handles cover image generation, SEO metadata, FAQ schema, internal linking, sitemap/llms.txt updates, Vercel deployment, and Google indexing.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Claude SEO: Multi-Platform Agent Instructions\n\n> For **Cursor**, **Cursor Cloud Agents**, **Google Antigravity**, **Gemini CLI**,\n> **Grok Build**,\n> **OpenAI Codex CLI**, **Cline**, **Aider**, and any other agent harness that\n> reads project-root agent instructions.\n>\n> Claude Code users: see `CLAUDE.md` instead.\n\n## Cross-platform portability (v2.0.0)\n\nEvery skill in `skills/*/SKILL.md` is authored to a portable subset of the\nClaude Code skill spec. Validate compatibility with your harness via:\n\n```bash\n./bin/claude-seo run portability_check.py\n```\n\nThe check confirms each `SKILL.md` has the minimum frontmatter every harness\nexpects (`name`, `description`, optional `model`, optional `tools`) and warns\non Claude-Code-specific features (`maxTurns`, multi-line tool list with\ndescriptive comments) that other harnesses may ignore but do not reject.\n\n### Per-harness notes\n\n| Harness | How to load claude-seo |\n|---|---|\n| **Cursor** | Symlink or copy `skills/` and `agents/` into `.cursor/rules/`. Commands are invoked as text prompts; the harness reads `SKILL.md` body as system context. |\n| **Cursor Cloud Agents** | Push the repo; Cloud Agents read `AGENTS.md` automatically at session start. |\n| **Google Antigravity** | Point the workspace at this repo root; Antigravity reads `AGENTS.md` first, falls back to `skills/`. |\n| **Gemini CLI** | `gemini init` in this repo loads `AGENTS.md`. Skills are activated via `activate_skill ` in conversation. |\n| **Grok Build** | Open this repository in Grok Build. It reads `AGENTS.md` and Claude Code compatible plugins and skills without a separate layout. Use `grok inspect` to verify discovery. See the [official compatibility guide](https://docs.x.ai/build/features/skills-plugins-marketplaces). |\n| **OpenAI Codex CLI** | Reads `AGENTS.md` from project root. Bash tools work as documented; some Claude-specific tool names (Read/Write/Edit) are aliased to Codex equivalents transparently. |\n| **Cline** | Loads `AGENTS.md` from project root. Skills appear as system messages; subagent delegation falls back to in-context expansion. |\n| **Aider** | Reads `AGENTS.md` if present; otherwise falls back to README. Aider does not support sub-agent dispatch; the seo-* skills run inline. |\n\n### Tool-name compatibility\n\nWhere claude-seo skills mention Claude Code tools (`Read`, `Write`, `Edit`,\n`Bash`, `Glob`, `Grep`, `WebFetch`), each harness typically has an equivalent:\n\n| Claude Code | Codex | Cline | Aider | Cursor / Antigravity |\n|---|---|---|---|---|\n| Read | read_file | read_file | (inline) | read |\n| Write | write_file | write_file | /add then edit | write |\n| Edit | apply_diff | replace_in_file | /edit | edit |\n| Bash | bash | execute_command | /run | shell |\n| Glob | glob | search_files | (inline) | find |\n| Grep | grep | search_files | /grep | grep |\n| WebFetch | fetch / browse | (browser tool) | (n/a) | fetch |\n\nThese mappings are automatic in most harnesses; we list them for transparency\nin case a recipe needs a specific call.\n\n## Overview\n\nClaude SEO is a Tier 4 SEO analysis skill with 25 sub-skills (21 core + 1 orchestrator +\n1 framework integration + 2 extension mirrors), 18 sub-agents (15 core + 1 framework\nintegration + 2 extension mirrors), and 53 Python execution scripts.\n\n## Quick Reference\n\n| Command | What it does |\n|---------|-------------|\n| `/seo audit ` | Full website audit with parallel subagent delegation |\n| `/seo page ` | Deep single-page analysis |\n| `/seo technical ` | Technical SEO audit (9 categories) |\n| `/seo content ` | E-E-A-T and content quality analysis |\n| `/seo content-brief ` | Generate a content brief for a topic |\n| `/seo schema ` | Schema.org detection, validation, generation |\n| `/seo sitemap ` | XML sitemap analysis or generation |\n| `/seo images ` | Image SEO: on-page audit, SERP analysis, file optimization |\n| `/seo geo ` | AI Overviews / Generative Engine Optimization |\n| `/seo plan ` | Strategic SEO planning |\n| `/seo cluster ` | SERP-based semantic clustering and content architecture |\n| `/seo sxo ` | Search Experience Optimization: page-type analysis, personas |\n| `/seo drift baseline ` | Capture SEO baseline for change monitoring |\n| `/seo drift compare ` | Compare current state to stored baseline |\n| `/seo drift history ` | Show drift history over time |\n| `/seo ecommerce ` | E-commerce SEO: product schema, marketplace intelligence |\n| `/seo programmatic [url]` | Programmatic SEO at scale |\n| `/seo competitor-pages [url]` | Competitor comparison pages |\n| `/seo flow [stage]` | FLOW framework prompts (Find, Leverage, Optimize, Win, Local; prompts/sync utilities.) |\n| `/seo local ` | Local SEO analysis (GBP, citations, reviews) |\n| `/seo maps [cmd] [args]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo hreflang ` | Hreflang/i18n SEO audit, cultural profiles, content parity |\n| `/seo google [cmd] [url]` | Google SEO APIs (GSC, PageSpeed, CrUX, Indexing, GA4) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo backlinks setup` | Setup free backlink APIs |\n| `/seo backlinks verify ` | Verify known backlinks still exist |\n| `/seo dataforseo [cmd]` | Live SEO data via DataForSEO (extension) |\n| `/seo image-gen [use-case]` | AI image generation for SEO assets (extension) |\n| `/seo firecrawl [cmd] ` | Full-site crawling and site mapping (extension) |\n| `/seo ahrefs [cmd] ` | Ahrefs backlink and keyword data (extension) |\n| `/seo bing [cmd] ` | Bing Webmaster data and IndexNow (extension) |\n| `/seo profound [cmd]` | LLM brand-citation tracking (extension) |\n| `/seo seranking [cmd]` | AI share-of-voice tracking (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse audits (extension) |\n\n## Using with Cursor / Cursor Cloud\n\nCursor reads this file automatically. All SKILL.md files contain the full\nanalysis logic as natural language instructions. Python scripts in `scripts/`\nprovide execution capabilities.\n\n**Running scripts directly** (Cursor doesn't have MCP):\n```bash\n# Page fetching with SSRF protection\n./bin/claude-seo run fetch_page.py https://example.com\n\n# HTML parsing for SEO elements\n./bin/claude-seo run parse_html.py https://example.com\n\n# PageSpeed Insights\n./bin/claude-seo run pagespeed_check.py https://example.com --json\n\n# Drift baseline\n./bin/claude-seo run drift_baseline.py https://example.com\n\n# DataForSEO (requires credentials)\nDATAFORSEO_USERNAME=user DATAFORSEO_PASSWORD=pass ./bin/claude-seo run dataforseo_merchant.py search \"keyword\"\n```\n\n**Cursor Cloud gotchas:**\n- SSL certificates may not resolve for some domains. Investigate the certificate issue rather than disabling verification.\n- Run bundled tools through `claude-seo`; never call the venv interpreter directly.\n- Screenshots save to `/tmp/` not CWD. Check absolute paths.\n\n## Using with Google Antigravity\n\nAntigravity discovers this project via `.claude-plugin/plugin.json`.\nPlace the repo in `~/.gemini/antigravity/plugins/claude-seo/` or install via:\n\n```bash\nbash install.sh\n```\n\n## Architecture\n\n```\nskills/ # 25 sub-skills (auto-discovered)\n seo/SKILL.md # Main orchestrator + routing\n seo-cluster/ # Semantic clustering (v1.9.0)\n seo-sxo/ # Search Experience Optimization (v1.9.0)\n seo-drift/ # SEO drift monitoring (v1.9.0)\n seo-ecommerce/ # E-commerce SEO (v1.9.0)\n seo-audit/ # Full site audit\n seo-page/ # Single-page analysis\n seo-technical/ # Technical SEO\n seo-content/ # E-E-A-T quality\n seo-content-brief/ # Content brief generation\n seo-schema/ # Schema.org markup\n seo-sitemap/ # XML sitemaps\n seo-images/ # Image optimization\n seo-geo/ # AI search / GEO\n seo-local/ # Local SEO\n seo-maps/ # Maps intelligence\n seo-plan/ # Strategic planning\n seo-hreflang/ # International SEO\n seo-google/ # Google APIs\n seo-backlinks/ # Backlink analysis\n seo-programmatic/ # Programmatic SEO\n seo-competitor-pages/ # Competitor pages\n seo-flow/ # FLOW framework integration\n seo-dataforseo/ # DataForSEO (extension)\n seo-image-gen/ # AI images (extension)\nagents/ # 18 subagents\nscripts/ # 53 Python scripts, including the managed runtime\nschema/ # JSON-LD templates\nextensions/ # 8 MCP extensions: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, Unlighthouse\n```\n\n## Key Principles\n\n1. **Progressive Disclosure**: Read SKILL.md for routing, load references on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Security**: All scripts call `validate_url()` for SSRF protection\n4. **Config location**: `~/.config/claude-seo/` for API credentials\n\n## Credits\n\nCreated by [@AgriciDaniel](https://github.com/AgriciDaniel).\nv1.9.0 community contributions by Lutfiya Miller, Chris Muller, Florian Schmitz,\nDan Colta, and Matej Marjanovic. See [CONTRIBUTORS.md](CONTRIBUTORS.md).\n","category":"root","tokens":2359},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude SEO: Universal SEO Analysis Skill\n\n## Project Overview\n\nThis repository contains **Claude SEO**, a Tier 4 Claude Code skill for comprehensive\nSEO analysis across all industries. It follows the Agent Skills open standard and the\n3-layer architecture (directive, orchestration, execution). 25 sub-skills (21 core +\n1 orchestrator + 1 framework integration + 2 extension mirrors), 18 sub-agents (15 core +\n1 framework integration + 2 extension mirrors), and an extensible reference\nsystem cover technical SEO, content quality,\nschema markup, image optimization, sitemap architecture, AI search optimization,\nlocal SEO (GBP, citations, reviews, map pack), maps intelligence, semantic topic\nclustering, search experience optimization (SXO), SEO drift monitoring, e-commerce\nSEO, and international SEO with cultural adaptation profiles.\n\n## Architecture\n\n```\nclaude-seo/\n CLAUDE.md # Project instructions (this file)\n CONTRIBUTORS.md # Community credits (Pro Hub Challenge)\n AGENTS.md # Multi-platform agent instructions (Cursor, Antigravity)\n .claude-plugin/\n plugin.json # Plugin manifest (v2.2.4)\n marketplace.json # Marketplace catalog for distribution\n skills/ # 25 sub-skills (auto-discovered)\n seo/ # Main orchestrator skill\n SKILL.md # Entry point, routing table, core rules\n references/ # On-demand knowledge files (13 files)\n seo-audit/SKILL.md # Full site audit with parallel agents\n seo-page/SKILL.md # Deep single-page analysis\n seo-technical/SKILL.md # Technical SEO (9 categories)\n seo-content/SKILL.md # E-E-A-T and content quality\n seo-content-brief/SKILL.md # Content brief generation\n seo-schema/SKILL.md # Schema.org markup detection/generation\n seo-sitemap/SKILL.md # XML sitemap analysis/generation\n seo-images/SKILL.md # Image optimization analysis\n seo-geo/SKILL.md # AI search / GEO optimization\n seo-local/SKILL.md # Local SEO (GBP, citations, reviews, map pack)\n seo-maps/SKILL.md # Maps intelligence (geo-grid, GBP audit, reviews, competitors)\n seo-plan/SKILL.md # Strategic SEO planning\n seo-flow/SKILL.md # FLOW framework integration\n seo-programmatic/SKILL.md # Programmatic SEO at scale\n seo-competitor-pages/SKILL.md # Competitor comparison pages\n seo-hreflang/SKILL.md # International SEO / hreflang\n seo-google/ # Google SEO APIs\n SKILL.md\n references/ # API reference files (11 files)\n seo-backlinks/SKILL.md # Backlink profile analysis\n seo-cluster/ # Semantic topic clustering (v1.9.0, by Lutfiya Miller)\n SKILL.md\n references/ # Clustering methodology, architecture, workflow\n templates/ # cluster-map.html interactive visualization\n seo-sxo/ # Search Experience Optimization (v1.9.0, by Florian Schmitz)\n SKILL.md\n references/ # Page-type taxonomy, user stories, personas, wireframes\n seo-drift/ # SEO drift monitoring (v1.9.0, by Dan Colta)\n SKILL.md\n references/ # Comparison rules (17 rules, 3 severity levels)\n seo-ecommerce/ # E-commerce SEO (v1.9.0, by Matej Marjanovic)\n SKILL.md\n references/ # Marketplace API endpoints\n seo-dataforseo/SKILL.md # Live SEO data via DataForSEO MCP (extension mirror)\n seo-image-gen/ # AI image generation for SEO assets (extension mirror)\n SKILL.md\n references/ # Image gen reference files (7 files)\n agents/ # 18 subagents (auto-discovered)\n seo-technical.md # Crawlability, indexability, security\n seo-content.md # E-E-A-T, readability, thin content\n seo-schema.md # Structured data validation\n seo-sitemap.md # Sitemap quality gates\n seo-performance.md # Core Web Vitals, page speed\n seo-visual.md # Screenshots, mobile rendering\n seo-geo.md # AI crawler access, GEO, citability\n seo-local.md # GBP, NAP, citations, reviews, local schema\n seo-maps.md # Geo-grid, GBP audit, reviews, competitor radius\n seo-google.md # Google API analyst (CrUX, GSC, GA4)\n seo-backlinks.md # Backlink profile analyst (Moz, Bing, CC, verify)\n seo-dataforseo.md # DataForSEO data analyst\n seo-image-gen.md # SEO image audit analyst\n seo-cluster.md # Semantic clustering analysis\n seo-sxo.md # Search experience optimization\n seo-drift.md # SEO drift monitoring\n seo-ecommerce.md # E-commerce SEO analysis\n seo-flow.md # FLOW framework integration\n hooks/ # Quality gate hooks\n hooks.json # PostToolUse schema validation\n scripts/ # 53 Python execution scripts\n google_auth.py # Credential management (OAuth, SA, API key, 4-tier detection)\n backlinks_auth.py # Backlink API credential management (Moz, Bing)\n moz_api.py # Moz Link Explorer API (DA/PA, spam, domains, anchors)\n bing_webmaster.py # Bing Webmaster Tools API (registered-site links/comparison)\n commoncrawl_graph.py # Common Crawl web graph parser (PageRank, in-degree)\n verify_backlinks.py # Backlink existence verification crawler\n pagespeed_check.py # PSI v5 + CrUX API\n crux_history.py # CrUX History API (25-week trends)\n gsc_query.py # Search Console (queries, pages, sitemaps, sites)\n gsc_inspect.py # URL Inspection (single + batch)\n indexing_notify.py # Indexing API v3 (URL_UPDATED/URL_DELETED)\n ga4_report.py # GA4 organic traffic reports\n google_report.py # PDF/HTML report generator (WeasyPrint + matplotlib)\n youtube_search.py # YouTube Data API v3\n nlp_analyze.py # Cloud Natural Language API\n keyword_planner.py # Google Ads Keyword Planner\n fetch_page.py # Page fetcher with UA rotation\n parse_html.py # HTML parser for SEO elements\n capture_screenshot.py # Playwright screenshots\n analyze_visual.py # Visual analysis helper\n drift_baseline.py # SEO drift baseline capture (SQLite)\n drift_compare.py # SEO drift comparison engine (17 rules)\n drift_report.py # SEO drift HTML report generator\n drift_history.py # SEO drift history query\n dataforseo_costs.py # DataForSEO cost estimation and budget tracking\n dataforseo_merchant.py # Google Shopping / Amazon data fetching\n dataforseo_normalize.py # DataForSEO response normalization utility\n sync_flow.py # FLOW prompt library sync (GitHub API, CC BY 4.0 headers, --dry-run, --ref)\n url_safety.py # Canonical URL/SSRF safety module (validate, DNS-pin, safe fetch)\n render_page.py # Shared headless renderer (SPA-aware, Playwright)\n lcp_subparts.py # LCP subparts breakdown via CrUX API\n preload_check.py # Speculation Rules / bfcache / prerender / preload detector\n agent_ux_check.py # Agent-friendly page auditor\n content_quality.py # QRG-aligned content quality detector\n content_humanize.py # AI-pattern remover (rewrites AI-typical phrasing)\n content_verify.py # Claim extractor + citation-gap detector\n schema_generate.py # JSON-LD generators for high-leverage v2 schema types\n schema_ecommerce_validate.py # Product schema validator (merchant-listing requirements)\n iptc_ai_label.py # IPTC DigitalSourceType audit/injection for AI imagery\n parasite_risk.py # Parasite-SEO risk scanner\n gbp_deprecation_lint.py # GBP feature-deprecation linter\n domain_history.py # Expired-domain heritage check\n seo_updates.py # Primary-source Google updates query tool\n indexnow_submit.py # IndexNow submitter\n ucp_check.py # UCP (Universal Commerce Protocol) profile auditor\n unlighthouse_run.py # Unlighthouse CLI wrapper (site-wide Lighthouse)\n validate_backlink_report.py # Backlink report validation\n portability_check.py # Cross-platform portability lint for SKILL.md files\n consistency_check.py # Reference-graph gate: dead refs, routing, lock, orphans\n release_sign.py # SHA-256 manifest generator for release signing\n verify_release.py # Verify checkout integrity against a release manifest\n mobile_analysis.py # Mobile rendering analysis (gitignored, dev-only)\n schema/ # Schema.org JSON-LD templates\n extensions/ # Optional add-on install helpers\n dataforseo/ # DataForSEO MCP install scripts\n firecrawl/ # Firecrawl MCP install scripts\n banana/ # Banana MCP install scripts\n ahrefs/ # Ahrefs MCP install scripts\n bing-webmaster/ # Bing Webmaster and IndexNow install scripts\n profound/ # Profound MCP install scripts\n seranking/ # SE Ranking MCP install scripts\n unlighthouse/ # Unlighthouse install scripts\n docs/ # Extended documentation\n```\n\n## Commands\n\n| Command | Use Case |\n|---------|----------|\n| `/seo audit ` | Full website audit with parallel subagents |\n| `/seo page ` | Single page analysis |\n| `/seo technical ` | Technical SEO across 9 categories |\n| `/seo content ` | E-E-A-T and content quality |\n| `/seo content-brief ` | Detailed content brief: keywords, outline, internal links |\n| `/seo schema ` | Schema markup detection, validation, generation |\n| `/seo sitemap ` | Sitemap validation |\n| `/seo sitemap generate` | Create new sitemap with industry templates |\n| `/seo images ` | Image optimization |\n| `/seo geo ` | AI search optimization (GEO) |\n| `/seo local ` | Local SEO (GBP, citations, reviews) |\n| `/seo maps [command]` | Maps intelligence (geo-grid, GBP audit, competitors) |\n| `/seo backlinks ` | Backlink profile analysis |\n| `/seo cluster ` | SERP-based semantic clustering |\n| `/seo sxo ` | Search Experience Optimization |\n| `/seo drift baseline\\|compare\\|history ` | SEO drift monitoring |\n| `/seo ecommerce ` | E-commerce SEO |\n| `/seo hreflang [url]` | Hreflang and international SEO |\n| `/seo plan ` | Strategic planning by industry |\n| `/seo programmatic [url\\|plan]` | Programmatic SEO analysis |\n| `/seo competitor-pages [url\\|generate]` | Competitor comparison pages |\n| `/seo flow [stage] [url\\|topic]` | FLOW framework prompts |\n| `/seo google [command] [url]` | Google SEO APIs (GSC, PSI, CrUX, GA4) |\n| `/seo dataforseo [command]` | Live SEO data (extension) |\n| `/seo image-gen [use-case] ` | AI image generation (extension) |\n| `/seo firecrawl [command] ` | Full-site crawling (extension) |\n| `/seo ahrefs [command] ` | Backlinks, organic keywords, and content data via the official Ahrefs MCP (extension) |\n| `/seo seranking [command]` | AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode (extension) |\n| `/seo profound [command]` | LLM citation tracking with time-series data (extension) |\n| `/seo bing [command] ` | Bing Webmaster Tools + IndexNow URL submission (extension) |\n| `/seo unlighthouse ` | Multi-page Lighthouse runner, runs locally (extension) |\n\n## Development Rules\n\n- Keep SKILL.md files under 500 lines / 5000 tokens\n- Reference files should be focused and under 200 lines\n- Scripts must have docstrings, CLI interface, and JSON output\n- Follow kebab-case naming for all skill directories\n- Agents invoked via Agent tool, never via Bash\n- Bundled tools run through `claude-seo run`; plugin state uses `CLAUDE_PLUGIN_DATA`\n- Manual Python dependencies install into `~/.claude/skills/seo/.venv/`\n- Test with `python3 -m pytest tests/` after changes (if applicable)\n\n## Security Rules\n\n- **Never commit credentials**: `.env`, `client_secret*.json`, `oauth-token.json`, `service_account*.json` are all in `.gitignore`\n- **URL validation**: All scripts that connect to user-supplied URLs must use `scripts/url_safety.py` (`validate_url_strict()` plus the pinned safe request helpers). This blocks private IPs, loopback, metadata endpoints, redirect rebinding, and DNS rebinding.\n- **OAuth tokens**: Never store `client_secret` in the token file. Read it from the client_secret.json file at runtime.\n- **No hardcoded paths**: Use `os.path.dirname(os.path.abspath(__file__))` for relative paths, never a user-specific absolute path\n- **Config location**: `~/.config/claude-seo/google-api.json` and `~/.config/claude-seo/backlinks-api.json` (user-space, not in repo)\n\n## Report Generation Rules\n\n- **All SEO reports must use `scripts/google_report.py`** as the canonical report generator\n- **Dependencies**: `matplotlib>=3.8.0` (charts) + `weasyprint>=61.0` (HTML-to-PDF), both in `requirements.txt`\n- **Format**: A4 PDF via WeasyPrint + matplotlib charts at 200 DPI\n- **Style**: Clean white title page with navy (#1e3a5f) accent, Times New Roman body font\n- **Color palette**: Navy #1e3a5f (headers), dark gold #b8860b (accents), forest green #2d6a4f (pass), warm amber #d4740e (warnings), deep red #c53030 (fail), warm cream #faf9f7 (backgrounds)\n- **Structure**: Title page → TOC with scores → Executive Summary → Data sections → Recommendations → Methodology\n- **Charts**: 85% width, max-height 120mm, figure captions on every chart, saved to `charts/` at 200 DPI\n- **No `page-break-inside: avoid`** on any element (causes white gaps in WeasyPrint)\n- **Post-generation review**: `_review_pdf()` runs automatically, checking for empty images, thin sections, duplicates\n- **Before presenting any PDF to the user**: verify the review passes (`\"status\": \"PASS\"`)\n- **Cross-skill enforcement**: After completing ANY analysis command (audit, page, technical, content, schema, geo, local, maps), offer: \"Generate a PDF report? Use `/seo google report`\"\n- **Google logo** appears on title page when using Google API data (\"Powered by Google APIs\")\n\n## Ecosystem\n\nPart of the Claude Code skill family:\n- [Claude Banana](https://github.com/AgriciDaniel/banana-claude) -- standalone image gen (bundled as extension here)\n- [Claude Blog](https://github.com/AgriciDaniel/claude-blog) -- companion blog engine, consumes SEO findings\n- [AI Marketing Claude](https://github.com/zubair-trabzada/ai-marketing-claude) -- community marketing suite (copy, emails, ads, funnels, CRO)\n\n## Key Principles\n\n1. **Progressive Disclosure**: Metadata always loaded, instructions on activation, resources on demand\n2. **Industry Detection**: Auto-detect SaaS, e-commerce, local, publisher, agency\n3. **Parallel Execution**: Full audits spawn up to 15 subagents simultaneously\n4. **Extension System**: DataForSEO, Firecrawl, Banana, Ahrefs, SE Ranking, Profound, Bing Webmaster, and Unlighthouse extensions\n\n## Repository Topology (public + private)\n\nThis project is mirrored across two GitHub remotes that share git history.\nBoth originate from the same local checkout; neither is a GitHub fork of\nthe other (different orgs, no parent/child relationship in the GitHub UI).\n\n| Remote | URL | Visibility | Role |\n|---|---|---|---|\n| `origin` | `https://github.com/AgriciDaniel/claude-seo` | **Public** | Published distribution. Users discover, clone, and install from here. `main` only reflects released history. |\n| `aimh` | `https://github.com/AI-Marketing-Hub/claude-seo` | **Private** | Working repo inside the AI Marketing Hub org. Daily development. v2 branch + post-release work lives here before promotion to public. |\n\n### Workflow\n\nDaily development:\n- Work on `v2` (or feature branches off `v2`) locally.\n- `git push aimh ` to publish work-in-progress to the private repo\n (Dependabot, Actions, and CI run there).\n\nPromoting to public on release:\n1. Merge `v2` into local `main` when ready to release (fast-forward).\n2. Tag the release locally (`git tag -a vX.Y.Z`).\n3. Push the tag and main to **both** remotes in this order:\n - First: `git push aimh main && git push aimh vX.Y.Z`\n - Then: `git push origin vX.Y.Z && git push origin main`\n - The \"tag before merge\" sequence (see `feedback_push_caution` memory)\n applies on `origin` to avoid the `curl|bash` outage window where\n users pull a tag that doesn't yet point at code on `main`.\n4. `gh release create vX.Y.Z --repo AgriciDaniel/claude-seo` (public-only).\n5. `/release-blog` to publish the release post.\n\n### Safety rules\n\n- **Never push to `origin/main` autonomously.** The public is release-only;\n pushes are user-authorized per-release.\n- **`aimh` accepts day-to-day pushes.** No release-gate ceremony required\n for the private remote.\n- **Tags push to private first.** Historical pre-release illustration: v2.0.0\n once lived on `aimh` before `origin`. Current released tags through v2.2.4\n are on both remotes.\n- **History stays shared.** Never rewrite history on either remote with\n force-push unless explicitly authorized for that specific operation.\n\n### Verifying the topology\n\n```bash\n# Both remotes configured\ngit remote -v # expects: origin (public) + aimh (private)\n\n# Both share main HEAD\ngit ls-remote --heads aimh main\ngit ls-remote --heads origin main # origin = aimh/main + 1 public-branding commit (intentional; see docs/WORKFLOW-public-private.md)\n```\n\nFull workflow reference: `docs/WORKFLOW-public-private.md`.\n\n## Release Blog Post\n\nAfter cutting a new release (git tag + `gh release create`), run:\n\n```\n/release-blog\n```\n\nThis generates a blog post on https://claude-seo.md/blog/, handles cover image generation, SEO metadata, FAQ schema, internal linking, sitemap/llms.txt updates, Vercel deployment, and Google indexing.\n","category":"root","tokens":4649}]}