SkeletonMan/test-2026-02-26-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c7ae06e58f3284c3eaa621d7d1be0ce55bc8c64
test-2026-02-26-v1/skills/SYSTEM_SKILLS.md

14 KiB
Raw Blame History

System Skills

Verbindliche Regeln für die KI-gestützte Website-Generierung im Agentur-Kontext.

Scope

Diese Datei definiert den harten Rahmen für:

  • Arbeitsweise und Workflow
  • Code-Qualität und Repo-Konventionen
  • Source of Truth für Design und Anforderungen
  • Verbote und Pflichten

Geltungsbereich: Gilt global für jedes Projekt. CLIENT_OVERRIDES.md darf diese Regeln präzisieren oder erweitern, aber niemals widersprechen.

Read Order

Die KI muss Dateien in folgender Reihenfolge lesen:

  1. skills/SYSTEM_SKILLS.md (diese Datei)
  2. skills/UI_GUIDELINES.md
  3. skills/DEFINITION_OF_DONE.md
  4. skills/CLIENT_OVERRIDES.md (falls vorhanden)
  5. spec/ProjectSpec.json
  6. spec/design_tokens.json
  7. theme/stylesheet.css / theme/globals.css

Bei Konflikten gilt: Globale Skills > Client Overrides

Non-Goals

Diese Datei definiert NICHT:

  • Konkrete Design-Vorgaben (Farben, Layouts, Abstände)
  • UI-Templates oder vorgefertigte Komponenten
  • Visuelle Entscheidungen jeglicher Art
  • Landingpage-Strukturen oder Section-Vorlagen

Design entsteht ausschließlich aus den Projekt-Specs, nicht aus diesen Skills.

Parameter-Interpreter-Modus

Das System arbeitet mit 9 strukturierten Parameter-Kategorien (A–J). Diese Kategorien sind in CLIENT_OVERRIDES.md und master_prompt.md vollständig aufbereitet.

Die 9 Kategorien

Kat. Name Beschreibung
A Unternehmensidentität & Kontext Name, Slug, Beschreibung, Branche, Standort, Einzugsgebiet, Unternehmensgröße, Reifegrad, Locale, Kontaktdaten
B Zielgruppe & Psychografie Hauptzielgruppe, Altersbereich, Geschlecht, Entscheidertyp, Wissensstand, typische Einwände, Hauptprobleme
C Tonalität & Kommunikation Ansprache (Du/Sie), Basis-Tonalität, Schreibstil, emotionales Gefühl
D Angebot & Leistungsstruktur Angebotstyp, Leistungen mit Titel/Beschreibung/Nutzen, Preissensitivität, Upsells
E Seitenarchitektur Website-Typ (Onepager/Multipage), Seiten mit Slug/Titel/Beschreibung/Zweck/Priorität/Sections
F Marken- & Stilparameter Farben (12 Token), Fonts, Logo, Stil-Adjektive (max 5), Stil-Verbote
G UX & Interaktion Interaktionsniveau, Animationen, Scroll-Verhalten
H Vertrauen & Conversion Primärer & Sekundärer CTA, Kontaktmethoden, Vertrauenselemente
I Technik & Recht Domain, Hosting, Tracking, Legal-Daten, Features, Integrationen
J KI-Kontext Freitext: Was ist BESONDERS WICHTIG, was darf AUF KEINEN FALL passieren, Referenzen

Arbeitsweise

  • Jede Kategorie enthält fertig aufbereitete Parameter
  • Keine Interpretation nötig — die Parameter werden 1:1 umgesetzt
  • Bei fehlenden Parametern: Sinnvolle Defaults verwenden, aber dokumentieren

KI-Kontext Gewichtungshierarchie

Die Priorität bei Konflikten folgt dieser Hierarchie (höchste zuerst):

1. SYSTEM_SKILLS.md
2. UI_GUIDELINES.md
3. DEFINITION_OF_DONE.md
4. KI-KONTEXT (Kategorie J)
5. CLIENT_OVERRIDES (Kategorien A–I)

Spezielle Regeln für Kategorie J

  • Kategorie J hat die höchste Gewichtung innerhalb der Client-Parameter
  • Bei Konflikten zwischen Kat. J und Kat. A–I: Kat. J gewinnt
  • Bei Konflikten zwischen Kat. J und SYSTEM_SKILLS/UI_GUIDELINES: Skills gewinnen
  • whatIsImportant aus Kat. J muss in JEDER Designentscheidung berücksichtigt werden
  • whatToAvoid aus Kat. J sind harte Verbote — keine Ausnahmen

Beispiel

Wenn Kat. J sagt "Keine Animationen" und Kat. G sagt "Interaktionsniveau: dynamisch", dann gilt: Keine Animationen.

Seiten-Zweck-System

Jede Seite in Kat. E hat einen definierten purpose und eine priority.

Purpose-Typen

Purpose Beschreibung Content-Strategie
informieren Fakten vermitteln Fakten zuerst, klare Struktur, erklärende Sprache, CTAs dezent
ueberzeugen Überzeugungsarbeit leisten USPs hervorheben, Social Proof, emotionale + rationale Argumentation
konvertieren Zur Handlung bewegen Prominente CTAs, Einwände adressieren, Trust-Elemente, Urgency

Priority-Levels

Priority Beschreibung
hoch Maximaler Detailgrad, höchste Aufmerksamkeit bei der Implementierung
mittel Solide Umsetzung mit allen wesentlichen Elementen
niedrig Basis-Umsetzung, funktional aber ohne Extras

Umsetzung

  • Informieren: H2-Struktur für Scanability, Inhaltsverzeichnis bei langen Seiten, CTAs am Ende von Sektionen
  • Überzeugen: Problem → Lösung → Beweis → CTA Flow, USP-Cards/Feature-Grid, Social Proof prominent
  • Konvertieren: Above-the-fold CTA, Trust-Section direkt unter Hero, Einwand-Entkräftung vor Kontaktformular

Kommunikations-Parameter

Die Kommunikation wird durch Kategorie C definiert und muss konsistent auf ALLEN Seiten umgesetzt werden.

Ansprache (address)

Wert Verwendung Beispiel
du Informelle Ansprache "Schick uns eine Nachricht", "Dein Name"
sie Formelle Ansprache "Senden Sie uns eine Nachricht", "Ihr Name"

Pflicht: Die gewählte Ansprache gilt für:

  • Alle Fließtexte
  • Alle Button-Labels
  • Alle Formular-Labels und Placeholders
  • Alle Microcopy-Elemente
  • Alle CTAs

Tonalität (baseTone)

Wert Beschreibung
sachlich Neutral, faktenbasiert, nüchtern
freundlich Warm, einladend, zugänglich
beratend Kompetent, hilfsbereit, lösungsorientiert
motivierend Energetisch, inspirierend, aktivierend
exklusiv Premium, distinguiert, hochwertig

Schreibstil (writingStyle)

Wert Beschreibung
kurz_praegnant Kurze Sätze, auf den Punkt, keine Füllwörter
erklaerend Ausführlicher, didaktisch, schrittweise
emotional Gefühlsbetont, storytelling, persönlich
technisch Fachsprachlich, präzise, detailliert

Emotionales Gefühl (emotionalFeeling)

Beschreibt das gewünschte Gesamtgefühl der Website (z.B. "vertrauenswürdig und modern", "dynamisch und innovativ"). Muss sich im Gesamtdesign widerspiegeln.

Vertrauens- & Conversion-Elemente

Kategorie H definiert, wie Vertrauen aufgebaut und Conversions erzielt werden.

Vertrauenselemente (trustElements)

Element Implementierung
bewertungen Google/Trustpilot-Widgets oder Zitat-Karten mit Sternebewertung
zertifikate Logo-Leiste mit Zertifizierungen (TÜV, ISO, etc.)
referenzen Kundenlogos oder Case-Study-Snippets
community Mitglieder-Zahlen, Social-Media-Feeds, Follower-Counts

Kontaktmethoden (contactMethods)

Methode Implementierung
formular Kontaktformular prominent auf Kontaktseite, ggf. auch in Footer
telefon Telefonnummer im Header + sticky CTA auf Mobile
buchung Buchungstool-Integration (z.B. Calendly-Embed) auf Kontaktseite

CTA-Implementierung

  • Primärer CTA: Haupthandlungsaufforderung, prominent platziert (Hero, Header, Sticky)
  • Sekundärer CTA: Alternative Handlung, weniger prominent aber sichtbar

Interaktions-Level

Kategorie G definiert das Interaktionsniveau der Website.

Level-Definitionen

Level Beschreibung Regeln
ruhig Maximale visuelle Ruhe Keine Animationen, kein Parallax, statisches Layout, framer-motion NICHT verwenden, maximal 1 CTA pro Viewport
moderat Ausgewogenes Layout Dezente Fade-In Animationen, subtile Hover-Effekte, framer-motion sparsam einsetzen, IntersectionObserver-basierte Reveals
dynamisch Lebendige Interaktion Scroll-Animationen, Parallax erlaubt, Micro-Interactions, framer-motion aktiv eingesetzt, Sticky CTAs

Animations-Einstellung (animations)

Wert Beschreibung
keine Absolut keine Animationen, auch keine Hover-Transitions
dezent Nur subtile Transitions (opacity, transform), max. 300ms
praesent Auffälligere Animationen, Scroll-triggered, Stagger-Effekte

Scroll-Verhalten (scrollBehavior)

Wert CSS-Umsetzung
normal scroll-behavior: auto
smooth scroll-behavior: smooth (auf html Element)

Integrationen

Kategorie I definiert technische Integrationen.

Newsletter

Wenn newsletter: true:

  • Newsletter-Signup-Formular im Footer
  • Dedizierte Section auf der Startseite (optional)
  • Platzhalter für Newsletter-Provider (Mailchimp, etc.)

Buchungstool

Wenn bookingTool gesetzt:

  • Als iframe/embed auf der Kontaktseite einbinden
  • Platzhalter-Embed wenn kein konkreter Anbieter angegeben: 
    <!-- TODO: Buchungstool-Integration hier einfügen -->
<div class="booking-placeholder">Buchungstool wird hier eingebunden</div>

Externe Integrationen

Externe Integrationen als Platzhalter-Kommentare im Code markieren:

// TODO: Integration ${name} - ${description}

Impressum & Datenschutz

Impressum

Legal-Daten kommen aus spec.technical.legal.impressum mit folgender Struktur:

{
  "companyName": "Firmenname GmbH",
  "street": "Musterstraße 1",
  "postalCode": "12345",
  "city": "Musterstadt",
  "country": "Deutschland",
  "email": "info@example.com",
  "phone": "+49 123 456789",
  "vatId": "DE123456789",
  "register": "HRB 12345, Amtsgericht Musterstadt"
}

Pflicht: Die KI generiert aus diesen Daten automatisch eine korrekte Impressum-Seite gemäß DACH-Recht.

Datenschutz

Datenschutz-Seite enthält mindestens:

  • Cookie-Hinweis
  • Hosting-Info (aus spec.technical.hosting)
  • Analytics-Angabe (aus spec.technical.tracking)
  • Kontaktdaten des Verantwortlichen
  • Hinweis auf Rechte der Betroffenen

Research-Insights Nutzung

Die llmResearch-Daten im ProjectSpec enthalten wertvolle Insights.

Verfügbare Research-Daten

Feld Verwendung
audienceAnalysis Bei Content-Erstellung für Kat. B berücksichtigen
uxRecommendations Bei Layout-Entscheidungen berücksichtigen
conversionStrategy Bei CTA-Platzierung und Funnel-Design berücksichtigen
suggestedUSPs Auf Startseite und Überzeugungsseiten prominent platzieren

Umsetzung

  • USPs aus suggestedUSPs als Feature-Cards oder Hero-Bullet-Points
  • conversionStrategy bestimmt den Aufbau von Conversion-Seiten
  • uxRecommendations fließen in Layout-Entscheidungen ein

Source of Truth

Das Design und die Anforderungen einer Website basieren ausschließlich auf:

Quelle Inhalt
spec/ProjectSpec.json Projektanforderungen, Ziele, Inhalte
spec/design_tokens.json Farben, Typografie, Spacing-System
theme/stylesheet.css Projektspezifische Styles
theme/globals.css Globale CSS-Variablen und Resets

Regel: Keine Design-Entscheidung ohne Grundlage in diesen Quellen.

Verbote

Absolut verboten:

  • KEINE Templates oder vorgefertigten Layouts
  • KEINE Copy-Paste-Strukturen aus anderen Projekten
  • KEINE Boilerplate-Landingpages
  • KEINE Standard-Hero/Feature/CTA-Sections ohne Spec-Grundlage
  • KEINE eigenmächtigen Design-Entscheidungen
  • KEINE hardcodierten Farben, Größen oder Abstände
  • KEINE UI-Libraries (shadcn, MUI, Chakra, Radix, etc.)
  • KEINE CSS-Frameworks außer Tailwind (falls im Projekt konfiguriert)
  • KEINE inline Styles (außer dynamische Werte)
  • KEINE !important (außer dokumentierte Ausnahmen)
  • KEINE Secrets im Repository (nur .env, .env.local)

Daten und Secrets:

  • Sensible Daten gehören in .env / .env.local
  • .env* Dateien sind in .gitignore
  • API-Keys, Passwörter, Tokens niemals committen

Arbeitsprozess

Jede Aufgabe folgt diesem Ablauf:

1. Lesen

  • /skills vollständig lesen
  • /spec vollständig lesen
  • Bestehenden Code verstehen

2. Planen

  • Anforderungen analysieren
  • Struktur und Komponenten konzipieren
  • Abhängigkeiten identifizieren

3. Implementieren

  • Code schreiben
  • Design-Tokens verwenden
  • Keine eigenmächtigen Entscheidungen

4. Self-Check

  • npm run build ausführen
  • Gegen Definition of Done validieren
  • Responsive und Accessibility prüfen

5. Dokumentieren

  • Änderungen in generation_log.json maschinell festhalten
  • Keine manuellen Einträge im Log

Coding-Standards

TypeScript

  • Strict Mode ist Pflicht
  • Keine any Types
  • Explizite Typdefinitionen für Props und State
  • Keine Type-Assertions ohne Notwendigkeit
  • Strict null checks beachten
// Korrekt
interface ComponentProps {
  title: string;
  items: ReadonlyArray<Item>;
  onSelect?: (item: Item) => void;
}

// Falsch
const props: any = { ... }

React / Next.js

  • Funktionale Komponenten
  • Server Components wo möglich
  • Client Components nur wenn nötig ("use client")
  • Keine unnötigen useEffect / useState
  • Keine Over-Abstraktionen

CSS

  • CSS-Variablen aus globals.css verwenden
  • Tailwind für Utility-Klassen (falls konfiguriert)
  • Eigene Klassen für wiederverwendbare Patterns
  • Mobile-first Breakpoints
.element {
  color: var(--color-foreground);
  padding: var(--spacing-md);
}

Allgemein

  • Lesbarkeit > Cleverness
  • Keine unnötigen Abstraktionen
  • Keine Over-Engineering
  • Konsistente Namenskonventionen
  • Keine auskommentierten Code-Blöcke
  • Keine console.log im Production-Code

Pflichten

Performance

  • Core Web Vitals optimieren
  • Lazy Loading für Below-the-fold-Inhalte
  • Kritisches CSS inline
  • JavaScript-Bundle minimieren
  • Fonts optimieren (display: swap)
  • Bildformate: WebP/AVIF bevorzugen
  • Keine unnötigen Dependencies

SEO

  • Semantisches HTML (header, main, nav, article, section, footer)
  • Korrekte Heading-Hierarchie (h1 > h2 > h3)
  • Meta-Tags (title, description)
  • Open Graph Tags
  • Alt-Texte für alle Bilder
  • Strukturierte Daten wo sinnvoll

Mobile-First

  • Responsive Design ist Pflicht
  • Touch-Targets mindestens 44x44px
  • Keine horizontalen Scrollbars
  • Lesbare Schriftgrößen ohne Zoom

Logging

generation_log.json

  • Nur maschinell befüllen
  • Keine manuellen Einträge
  • Dokumentiert: was wurde generiert, wann, welche Dateien
  • Dient der Nachvollziehbarkeit

Zusammenfassung

Jede Website ist einzigartig. Design kommt aus den Specs, nicht aus dem Bauch. Code ist sauber, typisiert und wartbar. Build muss laufen. Diese Regeln sind nicht verhandelbar.

Reference in New Issue View Git Blame Copy Permalink