Files

Matthias Meister e9463e8ef2 Surface audit generations on dashboard audits

2026-06-06 18:14:27 +02:00

7.8 KiB

Raw Blame History

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

Die Audit-Pipeline sammelt Artefakte: cheerioFindings, jinaMarkdown, pageSpeedRaw, Screenshots (Desktop/Mobile).
Der Agent liest die Registry und wählt alle Skills, deren applies_when erfüllt ist und deren benötigte inputs vorliegen.
Pro Skill erzeugt er Findings im unten definierten Schema.
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).
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)

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:

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

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

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

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

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

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

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

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

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

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

Neuen ##-Abschnitt mit eindeutiger id (kebab-case) anlegen.
YAML-Metablock ausfüllen: applies_when, inputs, outputs.
In der Prosa beschreiben: woran der Skill erkennt, was relevant ist, und wie die Befunde voice-konform formuliert werden (Beobachtung + Kundennutzen).
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.

7.8 KiB Raw Blame History