seo-audit · diff
git:20260829.db9afdf to git:20260829.e767f78
95 added, 105 removed. Audit B to B.
---
name: seo-audit
description: >-
- Vollständiger SEO-Orchestrator (Port von claude-seo v2.2.5): technische SEO,
- On-Page, Schema, E-E-A-T, GEO/AI-Overview, Local/GBP, Backlinks, E-Commerce,
- hreflang/i18n, Sitemap, Bilder-SEO, Keyword-Clustering, Content-Briefs,
- Drift-Tracking und Google-APIs (PSI/CrUX/GSC) über ein lokales Python-Toolkit
- (53 Skripte) + 24 Sub-Skills + 18 Agents. Befunde mit priorisiertem
- Aktionsplan und 4-Felder-Empfehlungen.
+ Run a full, weighted local & technical SEO audit on any website — entirely
+ local, no SaaS, no per-domain pricing. Measures 8 discipline areas with a
+ Python CLI (technical, on-page, schema.org/JSON-LD, local/GBP, Core Web
+ Vitals, GEO/AI-Overview, content/E-E-A-T, images, sitemap, hreflang, content
+ briefs, keyword clustering, drift, and Google APIs), then synthesises the
+ findings into one prioritised report with weighted scoring, dependency-ordered
+ actions and falsifiable recommendations.
whenToUse: >-
- SEO-Audits, technische SEO, Schema.org/JSON-LD, E-E-A-T, GEO/AI-Overview,
- Local/GBP, Backlinks, E-Commerce, hreflang/i18n, Sitemap, Bilder-SEO,
- Keyword-Clustering, Content-Briefs, Drift-Tracking, Google-API-Reports.
+ Any request to audit or improve a website's search visibility, technical SEO,
+ schema.org markup, E-E-A-T/content quality, local SEO or Google Business
+ Profile, GEO/AI-Overview readiness, Core Web Vitals, sitemap/hreflang,
+ keyword clustering, content briefs, or drift tracking.
---
- # SEO-Audit-Orchestrator (Port von claude-seo)
+ # seo-audit — local & technical SEO audit toolkit
- Natives Tool unter `seo-toolkit/`. Zwei Schichten:
- - **Messung** = `./seo <cmd>` (Python: eigene Specialists + 53 portierte Skripte).
- - **Urteil** = Sub-Skills (`skills/`) + Agents (`agents/`), die ich als Agent
- ausführe, ergänzt durch `web_search` und `subagent`-Fan-out.
+ A two-layer audit engine. **Measurement** is deterministic (a Python CLI + 53
+ curated scripts). **Judgment** is where the model interprets those findings and
+ writes the plan. Both stay on your machine: no API keys for the core, no
+ third-party SaaS, no per-domain pricing.
- ## Wichtig zuerst
+ ## Use this first
- 1. **Erst breit, dann tief:** `./seo audit <url>` zuerst, dann gezielt
- nachbohren. Wer mit Einzelbefehlen startet, optimiert Symptome statt Ursachen.
- 2. **Erst einrichten:** Wenn `./seo doctor` einen Fehler meldet → `./setup.sh`.
- Chromium liegt workspace-lokal; gelegentliche Sandbox-Hänger werden per
- Subprozess-Timeout abgefangen (einfach erneut versuchen).
- 3. **Jede Empfehlung trägt 4 Felder:** Beobachtung → Abhängigkeit →
- Misserfolgssignal → Frühindikator. Feld 2 = Reihenfolge, Feld 3 = Erfolgskontrolle.
+ 1. **Broad, then deep.** Run `./seo audit <url>` once, then drill into the
+ highest-impact findings. Starting with single commands optimises symptoms
+ instead of root causes.
+ 2. **Setup first.** If `./seo doctor` reports an error, run `./setup.sh`. Chromium
+ is workspace-local; occasional sandbox hangs are caught by a subprocess
+ timeout — just retry.
+ 3. **Recommendations carry 4 fields.** Observation → Dependency → Failure signal →
+ Early indicator. Field 2 sets the order, field 3 tells you how you'd know it
+ worked.
- ## Befehlsfläche
+ ## Command surface
- | Befehl | Schicht | Was es tut |
- |---|---|---|
- | `./seo doctor` | Messung | Umgebungs-Check |
- | `./seo audit <url>` | Messung+Urteil | Gesamtbefund (Specialists + Sitemap + HTML-Struktur) |
- | `./seo technical <url>` | Messung | Technisch (9 Kategorien via `checks_technical`) |
- | `./seo page <url>` | Messung | On-Page (Content, Links, Keyword-Signale) |
- | `./seo schema <url>` | Messung | JSON-LD/LocalBusiness erkennen+validieren |
- | `./seo local <url>` | Messung | Lokal/NAP (entspricht claude-seo `local`) |
- | `./seo visual <url>` | Messung | Render/Hydration, Console, Ladezeit (Lab) |
- | `./seo sitemap <url>` | Messung | Sitemap erkennen/validieren (`sitemap_discovery.py`) |
- | `./seo content <url\|datei>` | Messung | QRG-Content-Qualität (`content_quality.py`) |
- | `./seo hreflang <url>` | Messung | hreflang/i18n extrahieren (`parse_html.py`) |
- | `./seo backlinks <url>` | Messung | Freie Quellen (Moz/Bing/CommonCrawl); Premium: DataForSEO |
- | `./seo cluster <keyword>` | Messung | Heuristisches Clustering (SERP-basiert: `skills/seo-cluster`) |
- | `./seo content-brief <topic> [kw]` | Messung | Content-Brief |
- | `./seo drift baseline\|compare\|history <url>` | Messung | Zeitreihe |
- | `./seo google <sub> [args]` | Messung | PSI/CrUX/GSC/GA4/Indexing/Keyword-Planner (Key nötig) |
- | `./seo run <script.py> [args]` | Messung | Beliebiges der 53 Skripte direkt |
- | `./seo list` | — | Skripte + Sub-Skills + Extensions auflisten |
+ | Command | Measures |
+ |---------|----------|
+ | `./seo doctor` | Environment health check |
+ | `./seo audit <url>` | Full weighted verdict (specialists + sitemap + structure) |
+ | `./seo technical <url>` | Technical SEO (9 categories) |
+ | `./seo page <url>` | On-page: content, links, keyword signals |
+ | `./seo schema <url>` | JSON-LD / LocalBusiness detection + validation |
+ | `./seo local <url>` | Local / NAP consistency |
+ | `./seo visual <url>` | Render, hydration, console errors, load time (lab) |
+ | `./seo sitemap <url>` | Sitemap discovery + validation |
+ | `./seo content <url\|file>` | QRG-style content-quality scoring |
+ | `./seo hreflang <url>` | hreflang / i18n extraction |
+ | `./seo backlinks <url>` | Free sources (Moz/Bing/Common Crawl); premium via DataForSEO |
+ | `./seo cluster <keyword>` | Keyword clustering |
+ | `./seo content-brief <topic> [kw]` | Content brief |
+ | `./seo drift baseline\|compare\|history <url>` | Time-series drift |
+ | `./seo google <sub> [args]` | PSI / CrUX / GSC / GA4 (key required) |
+ | `./seo run <script.py> [args]` | Run any of the 53 scripts directly |
+ | `./seo list` | Enumerate scripts, sub-skills, extensions |
- ## Urteils-Befehle (Agent führt Sub-Skill aus)
+ ## Judgment layer
- Diese brauchen LLM-Urteil, nicht nur Messung. Ich lade die passende
- `skills/<name>/SKILL.md` und führe sie aus (bei Bedarf mit `subagent` parallel):
+ For anything that needs interpretation — not just measurement — load the matching
+ sub-skill and execute it (optionally in parallel via `subagent`):
- - **E-E-A-T / Content-Qualität** → `skills/seo-content/SKILL.md` (+ `agents/seo-content.md`)
- - **GEO / AI Overviews** (ChatGPT/Perplexity/AI Overviews) → `skills/seo-geo/SKILL.md`
- - **Local/GBP** (Google Business, Zitate, Reviews, Map Pack) → `skills/seo-local/SKILL.md`
- - **Maps-Intelligence** (Geo-Grid, GBP-Audit) → `skills/seo-maps/SKILL.md`
- - **SXO** (Search Experience, Personas, User Stories) → `skills/seo-sxo/SKILL.md`
- - **Plan** (Strategie je Branche) → `skills/seo-plan/SKILL.md`
+ - **E-E-A-T / content quality** → `skills/seo-content/SKILL.md`
+ - **GEO / AI Overviews** → `skills/seo-geo/SKILL.md`
+ - **Local / GBP** → `skills/seo-local/SKILL.md`
+ - **Maps intelligence** → `skills/seo-maps/SKILL.md`
+ - **SXO** (search experience, personas) → `skills/seo-sxo/SKILL.md`
+ - **Strategy per industry** → `skills/seo-plan/SKILL.md`
- **Programmatic SEO** → `skills/seo-programmatic/SKILL.md`
- - **Competitor-Pages** → `skills/seo-competitor-pages/SKILL.md`
- - **E-Commerce** → `skills/seo-ecommerce/SKILL.md`
- - **Bilder-SEO** → `skills/seo-images/SKILL.md`
- - **FLOW-Framework** → `skills/seo-flow/SKILL.md`
- - **Cluster (SERP-basiert)** → `skills/seo-cluster/SKILL.md`
-
- ## Orchestrierung (`audit`) — gated Multi-Agent-Fan-out
-
- **Zwei Schranken (gating), dann parallel:**
-
- 1. **Branche erkennen** (SaaS / local-service / ecommerce / publisher / agency / other)
- aus Homepage-Signalen (`./seo audit` druckt sie bereits).
-
- 2. **Kategorie-Menge bestimmen:**
- - **Immer** (branchenunabhängig): `technical`, `content` (E-E-A-T), `schema`, `page`, `sxo`, `geo` (GEO/AI-Overview)
- - **Nach Branche:**
- | Branche | zusätzliche Agents |
- |---|---|
- | saas | `cluster`, `programmatic` |
- | local-service | `local`, `maps` |
- | ecommerce | `ecommerce` |
- | publisher | `cluster`, `images` |
- | agency | `competitor-pages` |
- | other | — |
- - **Nach Credentials** (nur wenn Key/Zugang vorhanden): `google`, `backlinks`, `dataforseo`, `firecrawl`
-
- 3. **PARALLEL ausführen:** Diese Kategorien als **echte parallele Subagenten**
- starten (via `subagent`-Tool oder `workflow`-Skript `audit-fanout.workflow.js`).
- Jeder Subagent: lädt seine `skills/seo-<kategorie>/SKILL.md`, führt die
- Messungen über `./seo <cmd>` aus, liefert strukturierte Findings mit den
- 4 Feldern (Beobachtung → Abhängigkeit → Misserfolgssignal → Frühindikator).
+ - **Competitor pages** → `skills/seo-competitor-pages/SKILL.md`
+ - **E-commerce** → `skills/seo-ecommerce/SKILL.md`
+ - **Image SEO** → `skills/seo-images/SKILL.md`
+ - **FLOW framework** → `skills/seo-flow/SKILL.md`
+ - **Cluster (SERP-based)** → `skills/seo-cluster/SKILL.md`
- 4. **Synthese im Haupt-Agent:** alle Subagent-Ergebnisse zu EINEM Befund mit
- **gewichtetem** Score zusammenführen (in `lib/report.py`): Technical 22 % ·
- Content 23 % · On-Page 20 % · Schema 10 % · Performance 10 % ·
- AI-Search-Readiness 10 % · Images 5 %.
+ ## Orchestration — gated multi-agent fan-out
- 5. **Aktionsplan** mit Abhängigkeits-Sortierung + Falsifizierbarkeit je Empfehlung.
+ Only as many agents as the site actually needs (typically 7–10, never all 18):
- **Warum gated:** ein normaler Audit startet so nur ~7–10 Agents statt 18 —
- `ecommerce` nie für eine Werkstatt, `google` nie ohne Key.
+ 1. **Detect business type** (SaaS / local-service / ecommerce / publisher /
+ agency / other) from homepage signals.
+ 2. **Choose the category set:**
+ - **Always:** technical, content (E-E-A-T), schema, page, sxo, geo
+ - **By industry:** saas → cluster/programmatic · local-service → local/maps
+ · ecommerce → ecommerce · publisher → cluster/images
+ · agency → competitor-pages
+ - **By credential:** google, backlinks, dataforseo, firecrawl (only with keys)
+ 3. **Run in parallel.** Each subagent loads its `skills/seo-<category>/SKILL.md`,
+ runs measurement via `./seo <cmd>`, and returns structured findings with the
+ 4 fields.
+ 4. **Synthesise** into one weighted score (in `lib/report.py`): Technical 22% ·
+ Content 23% · On-Page 20% · Schema 10% · Performance 10% ·
+ AI-Readiness 10% · Images 5%.
+ 5. **Action plan** sorted by dependency, with a falsifiability check per
+ recommendation.
- ## Qualitäts-Gates (nicht ignorieren)
+ ## Quality gates (do not ignore)
- - **30+ Location-Seiten** → Warnung (60 % Unique-Content erzwingen); **50+ → Hard Stop**.
- - **HowTo-Schema nie empfehlen** (seit Sept 2023 deprecated).
- - **FAQ-Schema:** Rich Results seit 7. Mai 2026 für alle Sites eingestellt → nur
- Info-Hinweis, keine neuen FAQPage für SERP-Nutzen empfehlen; für echtes Q&A QAPage.
- - **Core Web Vitals immer INP, nie FID.**
+ - **30+ location pages** → warn (enforce 60% unique content); **50+ → hard stop**.
+ - **Never recommend HowTo schema** (deprecated since Sept 2023).
+ - **FAQ schema:** rich results withdrawn for all sites on 7 May 2026 → note only;
+ use QAPage for genuine Q&A.
+ - **Core Web Vitals always INP, never FID.**
- ## Referenzdateien (bei Bedarf laden)
+ ## Honest limits
- - `skills/seo/references/cwv-thresholds.md` · `eeat-framework.md` · `quality-gates.md`
- · `schema-types.md` · `local-seo-signals.md` · `thinking-framework.md`
- · `backlink-quality.md` · `free-backlink-sources.md`
+ - **Without a Google key:** load time is a lab estimate, no CrUX/PSI/GSC data.
+ - **Without third-party index:** no search volumes/backlink graph
+ (DataForSEO/Ahrefs/Bing need their own keys).
+ - **Extensions** (DataForSEO, Firecrawl, Ahrefs, Bing, Banana, Profound,
+ SE Ranking, Unlighthouse) are ported but only work once you supply credentials.
+ - **Scroll/hydration content** stays noisy → use `visual` as a cross-check.
- ## Grenzen (ehrlich)
+ ## Cost
- - **Ohne Google-Key:** Ladezeit = Laborschätzung, kein CrUX/PSI/GSC.
- - **Ohne Fremdindex:** keine Suchvolumina/Backlinks (DataForSEO/Ahrefs brauchen Keys).
- - **Extensions** (DataForSEO, Firecrawl, Ahrefs, Bing, Banana, profound, seranking,
- unlighthouse) sind portiert, laufen aber erst mit ihren Credentials.
- - **Scroll-/Hydrations-Inhalte** bleiben verrauscht → `visual` als Quervergleich.
+ The measurement layer is pure local Python — **$0 in tokens**. Only the LLM
+ interpretation costs anything, which is typically **~12×–30× cheaper** than the
+ equivalent Claude-based audit. See the project README for the worked example.