# skills.md — Audit-Skill-Registry Diese Datei steuert, **wie der KI-Auditor eine Website beurteilt**. Jeder Skill ist eine fokussierte Prüf-Linse mit klarem Einsatzbereich, definierten Eingaben und einer einheitlichen Ausgabestruktur. Die Registry liegt im Repo, ist versioniert und wird der Audit-Action als Kontext mitgegeben. ## So nutzt der Agent diese Datei 1. Die Audit-Pipeline sammelt Artefakte: `cheerioFindings`, `jinaMarkdown`, `pageSpeedRaw`, Screenshots (Desktop/Mobile). 2. Der Agent liest die Registry und wählt **alle Skills, deren `applies_when` erfüllt ist und deren benötigte `inputs` vorliegen**. 3. Pro Skill erzeugt er Findings im unten definierten Schema. 4. Aus den Findings entstehen zwei Dinge: - **`finalSummary` (intern):** vollständig, mit `severity` zur Priorisierung. - **`publicAuditText` (extern):** nur Beobachtung + Kundennutzen, **ohne** Scores, Ampeln, Severity oder anklagende Sprache (siehe Voice-Regeln). 5. `usedSkills` (Liste der `id`) wird am Audit gespeichert und im Dashboard angezeigt. ## Voice-Regeln (für jeden Skill verbindlich) - **Beobachtung statt Urteil.** „Die Telefonnummer ist auf dem Smartphone erst nach Scrollen sichtbar" statt „schlechte mobile UX". - **In Kundennutzen übersetzen.** Technischer Befund → konkreter Vorteil (weniger Absprünge, mehr Anfragen, mehr Vertrauen, bessere lokale Auffindbarkeit). - **Ich-Form, auf Augenhöhe, lokal, respektvoll, ohne Floskeln, ohne Dringlichkeit, ohne Preise.** - **Severity ist intern.** Extern nie Zahlen, Noten oder Warnfarben. ## Finding-Schema (Ausgabe jedes Skills) ```yaml findings: - skill_id: string # id des erzeugenden Skills observation: string # neutrale Beobachtung (intern + Basis für extern) customer_benefit: string # was die Verbesserung dem Betrieb bringt public_phrasing: string # fertige, voice-konforme Formulierung für die Audit-Seite severity: 1 | 2 | 3 # INTERN: 1 niedrig … 3 hoch (Priorisierung) evidence: string # Beleg: "screenshot_mobile" | "markdown:/kontakt" | "pagespeed:LCP" | "dom:title" applies: boolean # false, wenn der Skill nichts Relevantes gefunden hat ``` ## Skill-Format (so wird ein Skill deklariert) Jeder Skill ist ein `##`-Abschnitt mit YAML-Metablock + Anleitung in Prosa: ```yaml id: kebab-case-id title: Lesbarer Titel applies_when: always | website_exists | has_mobile_screenshot | has_pagespeed inputs: [desktop_screenshot, mobile_screenshot, markdown, pagespeed, dom] outputs: findings ``` --- ## visual-design ```yaml id: visual-design title: Visueller Gesamteindruck & Zeitgemäßheit applies_when: website_exists inputs: [desktop_screenshot, mobile_screenshot] outputs: findings ``` Beurteile den ersten visuellen Eindruck: wirkt der Auftritt zeitgemäß oder veraltet? Achte auf visuelle Hierarchie, Weißraum, Typografie (Lesbarkeit, Schriftmischung), Farbkontraste, Bildqualität und Konsistenz. Konkrete Beobachtungen statt Geschmacksurteilen — z. B. „kleine Schrift mit geringem Zeilenabstand erschwert das Lesen auf dem Smartphone", nicht „sieht altbacken aus". Kundennutzen: ein moderner, ruhiger Auftritt schafft Vertrauen, bevor der erste Satz gelesen wird. ## first-impression-clarity ```yaml id: first-impression-clarity title: Klarheit über dem Falz applies_when: website_exists inputs: [desktop_screenshot, mobile_screenshot, markdown] outputs: findings ``` Prüfe, ob im sichtbaren Bereich (ohne Scrollen) sofort klar wird: **Was** macht der Betrieb, **für wen**, **wo**? Fehlt eine klare Überschrift, ein Leistungsversprechen oder der Ort, muss ein Besucher raten. Kundennutzen: Besucher entscheiden in Sekunden, ob sie bleiben — Klarheit hält sie auf der Seite. ## contact-conversion ```yaml id: contact-conversion title: Kontaktaufnahme & Handlungsaufforderung applies_when: website_exists inputs: [mobile_screenshot, markdown, dom] outputs: findings ``` Wie leicht kann ein Interessent Kontakt aufnehmen? Sind Telefonnummer, E-Mail bzw. Formular und Öffnungszeiten leicht auffindbar — besonders mobil und ohne langes Scrollen? Ist die Telefonnummer auf dem Smartphone klickbar (`tel:`)? Gibt es eine klare nächste Handlung (anrufen, schreiben, Termin)? Kundennutzen: jede Reibung weniger ist eine Anfrage mehr. ## mobile-usability ```yaml id: mobile-usability title: Mobile Nutzbarkeit applies_when: has_mobile_screenshot inputs: [mobile_screenshot, pagespeed] outputs: findings ``` Beurteile die mobile Darstellung: bricht Text oder Layout um, sind Tap-Ziele groß genug, ist die Schrift ohne Zoom lesbar, verdecken Banner Inhalte? Nutze PageSpeed-Mobile-Signale ergänzend. Kundennutzen: der Großteil lokaler Suchen passiert am Handy — hier entscheidet sich, ob aus Interesse eine Anfrage wird. ## trust-signals ```yaml id: trust-signals title: Vertrauenssignale & Seriosität applies_when: website_exists inputs: [desktop_screenshot, markdown, dom] outputs: findings ``` Welche Vertrauenssignale sind vorhanden oder fehlen? Echte Fotos statt Stockbilder, Team/Über-uns, Referenzen oder Bewertungen, vollständiges Impressum, sichtbare Erreichbarkeit, gültiges HTTPS. Kundennutzen: lokale Kunden beauftragen, wem sie vertrauen — sichtbare Seriosität senkt die Hemmschwelle. ## conversion-copy ```yaml id: conversion-copy title: Texte & Ansprache applies_when: website_exists inputs: [markdown] outputs: findings ``` Sind die Texte klar, nutzenorientiert und auf die Zielgruppe zugeschnitten — oder generisch, fachsprachlich oder leer? Wird beschrieben, was der Betrieb leistet und welches Problem er löst? Achte auf Verständlichkeit und Tonalität (Deutsch, lokal). Kundennutzen: verständliche Texte holen mehr Besucher in eine Anfrage. ## local-seo-basics ```yaml id: local-seo-basics title: Lokale Auffindbarkeit (Grundlagen) applies_when: website_exists inputs: [dom, markdown] outputs: findings ``` Prüfe Title-Tag und Meta-Description (vorhanden, aussagekräftig, mit Ort?), Überschriftenstruktur (genau eine sinnvolle H1?), sowie die Konsistenz von Name, Adresse, Telefon (NAP) und ob der Ort/Einzugsbereich textlich auftaucht. Nutzt `cheerioFindings`. Kundennutzen: wer lokal gefunden wird, bekommt Anfragen aus der Region — ohne Werbebudget. ## performance-experience ```yaml id: performance-experience title: Tempo & Ladeerlebnis applies_when: has_pagespeed inputs: [pagespeed] outputs: findings ``` Übersetze PageSpeed-Rohdaten (LCP, CLS, INP, Gesamt-Score) in ein erlebbares Bild, **ohne** Scores zu nennen. Beispiel: „Auf dem Smartphone erscheinen die ersten Inhalte spürbar verzögert." Kundennutzen: schnelle Seiten halten Besucher — langsame verlieren sie, bevor sie etwas gesehen haben. ## accessibility-basics ```yaml id: accessibility-basics title: Zugänglichkeit (Grundlagen) applies_when: website_exists inputs: [desktop_screenshot, dom] outputs: findings ``` Niedrigschwellige Barrieren: ausreichende Farbkontraste, lesbare Schriftgrößen, sinnvolle Alt-Texte bei zentralen Bildern, bedienbare Menüs. Kundennutzen: gut zugängliche Seiten erreichen mehr Menschen — und wirken professioneller. --- ## Einen neuen Skill hinzufügen 1. Neuen `##`-Abschnitt mit eindeutiger `id` (kebab-case) anlegen. 2. YAML-Metablock ausfüllen: `applies_when`, `inputs`, `outputs`. 3. In der Prosa beschreiben: **woran** der Skill erkennt, was relevant ist, und **wie** die Befunde voice-konform formuliert werden (Beobachtung + Kundennutzen). 4. Keine Code-Änderung nötig — der Agent liest die Registry zur Laufzeit. Nur wenn ein neuer `inputs`-Typ gebraucht wird, muss die Pipeline dieses Artefakt liefern. ## Reihenfolge & Priorisierung Der Agent gewichtet Findings nach interner `severity` und Relevanz für lokale Dienstleister. Für den öffentlichen Audit-Text gilt: **wenige, konkrete, freundlich formulierte Beobachtungen** schlagen eine lange Mängelliste. Ziel ist ein Gespräch, keine Abrechnung.