Surface audit generations on dashboard audits
This commit is contained in:
212
v2_elemente/skills.md
Normal file
212
v2_elemente/skills.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user