jdevalk/skills – Static SEO

Statisches SEO

Auditiert und verbessert das SEO-Setup einer statischen HTML-Seite anhand von neun Kategorien: Head-Metadaten, strukturierte Daten, Inhaltsqualität, Open-Graph-Bilder, Sitemaps und Indexierung, Agentenfindung, Performance, Weiterleitungen und CI-Validierung. Die Rezepte sind plattformneutral: rohe <meta>-Tags, rohes JSON-LD, handgeschriebene sitemap.xml, generische CI-Werkzeuge. Der Audit-Rahmen ist parallel zu astro-seo, aber ohne die @jdevalk/astro-seo-graph-Grundlage.

Code-Rezepte befinden sich in AGENTS.md – lies sie, wenn du eine spezifische Lösung implementieren musst. Diese Datei enthält den Workflow und die Audit-Checkliste.

Workflow

1. Projekt erkennen – bestätige, dass es sich um eine statische Site handelt, identifiziere das Build-Tool und finde heraus, wo Änderungen anzuwenden sind.
2. Audit – bewerte neun Kategorien und erstelle umsetzbare Ergebnisse.
3. Verbessern – generiere oder modifiziere Dateien, um die Lücken zu schließen. Rezepte befinden sich in AGENTS.md.
4. Metadaten-Prüfung – führe metadata-check für jeden kurzen String aus, den die Fähigkeit generiert hat (Titel, Beschreibungen, Schema-description-Felder, FAQ-Antworten).
5. Verifizieren – führe einen Build aus, validiere die Ausgabe und erinnere den Nutzer an nicht-dateibasierte Aufgaben (Search Console, Bing Webmaster Tools, IndexNow-Key-Einreichung).

---

Phase 0: Projekt erkennen

Bestätige die Grundlagen vor dem Audit:

• Es ist tatsächlich eine statische Site. Suche nach gebautem HTML – index.html im Repository-Root oder unter _site/ (Jekyll), public/ (Hugo / 11ty / Gatsby), dist/ (Vite / Astro statisch), out/ (Next.js mit output: export). Wenn alles serverseitig gerendert wird (Express, PHP, dynamische Routen), ist dies die falsche Fähigkeit – verweise auf astro-seo für Astro, wp-readme-optimizer für WP-Plugin-Seiten oder empfehle ein generisches SEO-Audit.
• Quell-Build-Tool. Bestimmt, wo Head-Metadaten-Änderungen angewendet werden:
  • _config.yml / _layouts/ → Jekyll
  • config.toml / config.yaml / themes/ → Hugo
  • .eleventy.js / _includes/ → 11ty
  • gatsby-config.js / src/components/SEO.* → Gatsby
  • next.config.js mit output: 'export' und pages/_document.tsx → Next.js statischer Export
  • astro.config.mjs → Astro (in diesem Fall verwende stattdessen astro-seo)
  • Keine Build-Konfiguration, nur HTML-Dateien → handgeschrieben oder gescrapt (z. B. wp-static-clone-Ausgabe). Bearbeite das HTML direkt oder verwende ein Post-Process-Skript.
• Kanonische Site-URL. Durchsuche das Repository nach der Produktions-Origin – typischerweise in _config.yml, config.toml, astro.config oder fest in einem Layout codiert. Wenn sie fehlt, leer ist oder localhost lautet, markiere dies als blockierendes Problem vor allem anderen. Kanonische URLs, Sitemaps, OG-Bild-URLs und JSON-LD-@id-Werte leiten sich alle davon ab.
• Deployment-Ziel. Lese vercel.json, netlify.toml, wrangler.toml oder public/_headers, um den Host zu bestimmen. Bestimmt die Syntax für Weiterleitungen und Header in Phase 2.
• Ist die Site mehrsprachig? Überprüfe auf Locale-Unterverzeichnisse (/en/, /nl/, /de/) oder Build-Tool-i18n-Konfiguration. Wenn ja, ist hreflang wichtig; wenn nein, überspringe es.
• Was ist bereits im <head>? Öffne eine gebaute HTML-Datei und inventarisiere: Titel, Beschreibung, kanonische URL, robots, Open Graph, Twitter Cards, JSON-LD, hreflang. Das Audit in Phase 1 ist schneller, wenn du darauf verweisen kannst, was vorhanden ist.

Frage nur, was du nicht erkennen kannst.

---

Phase 1: Audit

Bewerte jede Kategorie mit 0–10 Punkten. Gib für jede 2–4 spezifische Ergebnisse, die das tatsächliche HTML, die Konfiguration oder das Template zitieren. Innerhalb jeder Kategorie sind die Prüfungen abgestuft:

• Muss – lieferblockierend. Ein Fehlschlag verursacht sichtbare SEO-Verschlechterung.
• Sollte – Standardpraxis. Überspringen kostet Reichweite.
• Kann – zukunftsorientiert oder situationsabhängig. Nützlich, aber nicht grundlegend für jede Site.

Überspringe Kann-Prüfungen für kleine persönliche Seiten, es sei denn, der Nutzer wünscht die vollständige Behandlung.

1. Head-Metadaten (/10)

• Muss – jede Seite hat einen <title> und ein <meta name="description">.
• Muss – <link rel="canonical"> gesetzt, mit entfernten Tracking-Parametern, abgeleitet von der Produktions-Origin.
• Muss – kanonische URL ausgelassen, wenn die Seite noindex ist (gemäß Googles Empfehlung).
• Muss – <title>-Länge 30–65 Zeichen, <meta name="description">-Länge 70–200 Zeichen (die SERP-Trunkierungsgrenzen; identisch mit den metadata-check-Standards).
• Sollte – <meta name="robots"> enthält max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Sollte – Open Graph (og:title, og:description, og:image, og:url, og:type, og:site_name) auf jeder Seite.
• Sollte – Twitter-Card-Tags (twitter:card) unterdrückt, wenn sie Open Graph duplizieren (Twitter greift automatisch darauf zurück).
• Sollte – hreflang-Alternativen auf mehrsprachigen Seiten. Überspringen, wenn einsprachig.
• Sollte – ein einzelnes <meta name="robots"> und ein einzelnes og:image pro Seite (ältere Tools geben manchmal Duplikate aus).

2. Strukturierte Daten / JSON-LD (/10)

• Muss – mindestens ein <script type="application/ld+json">-Block auf jeder wichtigen Seite.
• Sollte – verknüpftes @graph anstelle eines flachen Article-Objekts – Entitäten, die mit @id-Referenzen verbunden sind, sodass ein BlogPosting auf seinen Person-Autor und WebPage-Elternteil verweisen kann.
• Sollte – WebSite, Blog / WebPage, Person / Organization, BlogPosting / Article, BreadcrumbList, ImageObject alle vorhanden, wo relevant.
• Sollte – Vertrauenssignale: publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction.
• Muss – validiert im Rich Results Test und ClassySchema.

3. Inhaltsqualität (/10)

• Muss – jede Seite hat einen eindeutigen <title> und ein eindeutiges <meta name="description"> (keine doppelten Metadaten auf der gesamten Site).
• Muss – genau ein <h1> pro Seite.
• Sollte – <title> und <meta name="description"> auditiert via metadata-check (Phase 2.5) auf Frontloading, Konkretheit und SERP-Passung.
• Sollte – Fließtext auditiert via readability-check für einzelne lange Beiträge (nicht im Bulk auditen).
• Sollte – jedes <img> hat ein alt-Attribut (oder alt="" / role="presentation" für dekorative).
• Sollte – interne Links verwenden root-relative Pfade (/foo/) nicht absolute (https://...) – überlebt Domain-Änderungen und Vorschauen.

4. Open-Graph-Bilder (/10)

• Muss – jede Seite hat ein OG-Bild.
• Muss – 1200×675 (Google Discover mindestens 1200px breit, 16:9-Verhältnis).
• Sollte – JPEG (Social-Media-Plattformen unterstützen WebP / AVIF für OG nicht zuverlässig).
• Sollte – zur Build-Zeit generiert (satori-cli, sharp, ImageMagick, Vercel OG, Bannerbear) anstatt manuell pro Seite hochgeladen – verhindert Drift.
• Sollte – URL deterministisch vom Slug abgeleitet (z. B. /og/<slug>.jpg), sodass das Hinzufügen einer Seite automatisch ein Bild erhält.
• Sollte – jedes <img> im Body-Inhalt hat ein alt-Attribut (oder alt="" / role="presentation"). In CI validiert via html-proofer oder ähnlich.

5. Sitemaps und Indexierung (/10)

• Muss – /sitemap.xml (oder /sitemap_index.xml für geteilte Sitemaps) erreichbar, gültiges XML, jede URL gibt 200 zurück.
• Muss – robots.txt im Site-Root vorhanden und verweist auf die Sitemap.
• Muss – RSS-Feed existiert, beworben via <link rel="alternate" type="application/rss+xml">, enthält vollständigen Beitragsinhalt (nicht gekürzte Auszüge).
• Sollte – pro Abschnitt geteilt, wenn die Site mehrere Inhaltstypen hat (sitemap-posts.xml, sitemap-pages.xml) – einfacher, Indexierung in GSC zu debuggen.
• Sollte – <lastmod> aus Git-Commit-Zeitstempeln (genaueste), Build-Zeitstempeln (akzeptabel) oder Frontmatter-Daten (letzter Ausweg) befüllt. Dateisystem-mtime aus CI-Checkout ist falsch – es ist das Checkout-Datum, nicht das Inhaltsdatum.
• Sollte – IndexNow integriert. Verifizierungsschlüssel als statische /<key>.txt-Route im Site-Root, plus ein Build- oder Deploy-Hook, der neue URLs an https://api.indexnow.org/IndexNow per POST sendet. Schalte die Einreichung auf den Produktions-Host (z. B. CF_PAGES_BRANCH=main, VERCEL_ENV=production, CONTEXT=production) – eine bedingungslose Einreichung pingt den Endpunkt von lokalen Builds mit URLs, die der Produktions-Host noch nicht ausgeliefert hat, was den Schlüssel als ungültig (403) markiert und eine Rotation erzwingt.

6. Agentenfindung (/10)

• Sollte – Schema-Endpunkte (/schema/<type>.json), die korpusweites JSON-LD pro Inhaltstyp bereitstellen. Statische JSON-Dateien, die im Repository committet oder vom Build neu generiert werden.
• Sollte – Schema-Map (/schemamap.xml), die jeden Schema-Endpunkt auflistet, mit Schemamap:-Direktive in robots.txt.
• Sollte – llms.txt im Site-Root, das Seiten (Titel + Beschreibung) für LLM-Konsumenten auflistet. Statische Textdatei; eine Zeile pro Seite.
• Sollte – Markdown-Alternativ-URLs (/blog/post.md neben /blog/post/), die sauberes Markdown mit YAML-Frontmatter ausliefern, sodass KI-Agenten Inhalte ohne HTML-Parsing konsumieren können. Entweder .md-Geschwister committen oder eine Cloudflare-Transform-Regel + Vary: Accept für Content-Negotiation verwenden (CF Pages entfernt benutzerdefinierte Vary-Header, verwende daher die URL-Neuschreibung der Transform-Regel allein – Rezept in AGENTS.md).
• Sollte – API-Katalog unter /.well-known/api-catalog gemäß RFC 9727, als application/linkset+json (RFC 9264). Listet Schema-Endpunkte, Schema-Map, RSS-Feed und alle seitenspezifischen APIs auf. Statische JSON-Datei.
• Sollte – Content-Signals-Direktive in robots.txt (Content-Signal: ai-train=yes, search=yes, ai-input=yes oder deine bevorzugte Richtlinie). Eine Zeile, IETF-Entwurf, geringe Kosten.
• Sollte – Link-Header auf /*, der auf Discovery-Dateien verweist (Sitemap, llms.txt, api-catalog, schemamap). Agenten, die Antwort-Header lesen, finden sie ohne HTML-Parsing. Host-spezifisch (_headers auf Cloudflare Pages / Netlify, vercel.json auf Vercel, Server-Konfiguration anderweitig).
• Kann – MCP-Serverkarte unter /.well-known/mcp/server-card.json und/oder A2A-Agentenkarte unter /.well-known/agent-card.json. Nur relevant, wenn die Site einen MCP-Server oder A2A-Agenten bereitstellt.
• Kann – <link rel="nlweb">, das auf einen konversationellen Endpunkt verweist. NLWeb-Adoption ist früh; das Tag ist eine Zeile und es wert zu haben, aber kein Bewertungsblocker im Jahr 2026.
• Kann – ARD (Agentic Resource Discovery)-Katalog unter /.well-known/ai-catalog.json, der auflistet, was die Domain bietet (MCP-Server, A2A-Agent, OKF-Bundle, seitenspezifische APIs). v0.9-Entwurf, daher optional – aber es ist die Discovery-Schicht, durch die sich die MCP-/A2A-Karten und das OKF-Bundle auszahlen. Zwei Fallstricke: Der Basisspezifikation (Agent-Card/ai-catalog) benennt das Media-Type-Feld mediaType, während die ARD-Schicht (ards-project/ard-spec) es type nennt – gib beide Schlüssel mit demselben Wert aus, sodass der Eintrag unter beiden Lesarten validiert (beide Spezifikationen verlangen, dass Konsumenten unbekannte Schlüssel ignorieren). ARD fügt außerdem ein optionales representativeQueries-Array mit Beispiel-Prompts pro Eintrag hinzu. Statische JSON-Datei.
• Kann – OKF (Open Knowledge Format)-Bundle: ein Baum von getippten Markdown-Konzeptdateien (eine pro Seite, Pfade spiegeln kanonische URLs wider) verpackt als einzelnes .tar.gz, mit Indexdateien dazwischen. Auslieferung und Discovery sind explizite Nicht-Ziele von OKF – dafür ist der ARD-Katalogeintrag da. v0.9-Entwurf, optional. Es gibt noch keinen registrierten Medientyp, daher ist der Zwischenstring application/okf-bundle+gzip (verfolgt in knowledge-catalog#111 und ard-spec#27); markiere ihn als vorläufig, er kann sich ändern. Am besten aus derselben Quelle generiert, von der der Rest der Site abgeleitet wird, anstatt handgepflegt.

7. Performance (/10)

• Muss – gehashte Assets bedienen Cache-Control: public, max-age=31536000, immutable (oder äquivalent), sodass sie nur einmal heruntergeladen werden.
• Sollte – primäre Web-Schriftart als woff2 vorgeladen via <link rel="preload" as="font" crossorigin>.
• Sollte – No-Vary-Search-Response-Header entfernt UTM-Parameter aus dem Cache-Key (sodass /?utm_source=x und / einen Cache-Eintrag teilen).
• Sollte – kein render-blockierendes JavaScript beim ersten Paint (defer oder async für nicht-kritische Skripte).
• Sollte – Bilder verwenden moderne Formate (WebP / AVIF für In-Page-Inhalte; JPEG nur für OG-Karten) und loading="lazy" unterhalb des Fold.
• Sollte – alle Lighthouse / PageSpeed Core Web Vitals im grünen Bereich: LCP < 2,5s, INP < 200ms, CLS < 0,1.

8. Weiterleitungen und Fehlerbehandlung (/10)

• Muss – _redirects / vercel.json / Server-Konfiguration für jede URL gepflegt, die jemals existierte und verschoben wurde.
• Muss – 301 nicht 302 für permanente Verschiebungen.
• Muss – 404.html (oder äquivalent) gibt einen 404-Status zurück, nicht 200. Überprüfe mit curl -I gegen eine absichtlich falsche URL.
• Sollte – Fuzzy-Match-Vorschlag auf der 404-Seite ("Meintest du …?") für Tippfehler in URLs. Statische Implementierung: Erstelle einen JSON-Index gültiger Slugs vor, Fuzzy-Match clientseitig.

9. CI-Validierung (/10)

• Muss – Kaputt-Link-Prüfer in CI. linkinator oder lychee bei jedem Push, der Inhalte betrifft. Sowohl interne als auch externe Links – interne fangen Build-Regressionen, externe fangen Link-Rot. Plane einen wöchentlichen Lauf für reine Extern-Links-Prüfungen.
• Sollte – HTML-Validierung via html-proofer oder W3C-Validator – fängt fehlerhaftes Markup, das Crawler bricht.
• Sollte – Lighthouse CI bei jedem Push, mit Score-Schwellenwerten (z. B. SEO ≥ 95, Performance ≥ 80).
• Sollte – JSON-LD-Validierung in CI via dem Schema.org JSON-LD-Validator (kein offizielles CLI; leite durch ein Node-Skript, das per POST an die API sendet).
• Sollte – Titel- und Beschreibungslängen-Validierung in CI: ein kleines Skript, das gebautes HTML durchläuft, <title> und <meta name="description"> extrahiert und alles markiert, was außerhalb der Grenzen liegt.

…

[truncated for translation]