telenetsystems-2026-02-05-v1/skills/SYSTEM_SKILLS.md

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.