213 lines
7.8 KiB
Markdown
213 lines
7.8 KiB
Markdown
# 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.
|