mveplus/claude-skills

How-it-works-Website

Erstelle eine ablauffreie Diashow in site/, die eine Codebasis vom Warum bis zum Code erklärt, mit interaktiven Demos, die die reale Logik des Projekts abbilden, sowie einem CI-Job, der sie veröffentlicht. Referenzimplementierung: https://mveplus.github.io/onair-led-sign-firmware/ (19 Folien, 4 Simulationen; Quelle in https://github.com/mveplus/onair-led-sign-firmware/tree/main/site).

Vorlagen im templates/-Verzeichnis dieser Fähigkeit:

Datei	Kopieren nach	Zweck
index.html	site/index.html	Seiten-Chrome + Folienmuster zum Klonen
deck.css	site/deck.css	Theme-Tokens, Layout, Komponenten
deck.js	site/deck.js	Navigation, Übersicht, Hash-Routing, Frame-Loop, Stepper-Helfer
app.js	site/app.js	Starter für die Demos des Projekts (Stepper-Verkabelung, Frame-Hook)
github-pages.yml	.github/workflows/pages.yml	GitHub Pages Deploy
gitlab-ci.yml	in .gitlab-ci.yml einfügen	GitLab Pages Deploy

Projektspezifischer Demo-Code kommt in site/app.js (und Styles optional in site/app.css); deck.js und deck.css bleiben generisch.

Ablauf

1. Vor dem Bauen fragen (ein AskUserQuestion-Aufruf)

Prüfe zuerst git remote -v, damit die Hosting-Frage die Realität widerspiegelt. Wenn das Remote GitHub ist und der Benutzer GitLab sagt (oder umgekehrt), frage nach. Stelle höchstens vier Fragen:

• Hosting: GitHub Pages, GitLab Pages oder beides.
• Zielgruppe/Tiefe: gemischt (zuerst Idee, dann tiefer Einstieg; Standard), Entwickler oder Nicht-Entwickler.
• Interaktive Demos: Biete 3–4 Kandidaten spezifisch für dieses Projekt an, gefunden durch kurzes Überfliegen (Zustandsmaschinen, Timing/Threshold-Logik, Request-Flows, Mathematik/Formeln, Konfigurations-Builder). MultiSelect.
• Optional: eine Sprach- oder Branding-Einschränkung, falls das Repository eine nahelegt.

2. Code richtig lesen

Lies die Einstiegspunkte, die Hauptmodule, die README/Dokumentation und die CI-Dateien. Für jede Behauptung, die die Folien aufstellen (Timeouts, Schwellwerte, Standardwerte, Themen, Endpunkte, was ein Reset löscht), hole sie aus dem Code, nicht aus der README. Führe eine Liste der Dokumentations-vs.-Code-Diskrepanzen und Sackgassen (z. B. ein CI-Job, dessen Verbraucher nicht existiert). Zeige das tatsächliche Verhalten des Codes auf den Folien und melde die Liste dem Benutzer am Ende. „Korrigiere“ die Folien niemals stillschweigend, um sie an die Dokumentation anzupassen.

3. Gliederung (~12–20 Folien), gruppiert in Kapitel

Typischer Bogen: Titel (mit einem spielerischen interaktiven Element) → die Idee/das Problem → grobes Bild (anklickbare Architektur) → Request/Datenfluss (animierter Stepper) → eine Folie pro Hauptkomponente → Resilienz/Fehlerbehandlung → Sicherheit/Geheimnisse → Build, CI, Auslieferung → Zusammenfassung der Designprinzipien mit Links. Jede Folie benötigt ein data-chapter und ein data-title.

4. Bauen

• Kopiere die Vorlagen und klone die Folienmuster in index.html (Hero, zwei Spalten mit einer Karte, Stepper, Info-Grid).
• Simulationen verwenden den tatsächlichen Algorithmus des Projekts: Portiere die Funktion (Ganzzahl-Mathematik, Schwellwerte, Reihenfolge) und zitiere ihren Namen auf der Folie. Eine Simulation, die nur richtig aussieht, ist ein Fehler.
• Verwende Deck.onFrame(slideId, fn) für Animationen, sodass nur die sichtbare Folie animiert. Verwende Deck.stepper(...) für Klick-durch-Sequenzen.
• Diagramme: Inline-SVG mit den CSS-Tokens; nichts Externes. Keine CDNs und keine Schriftarten zum Abrufen, damit die Seite offline und auf abgeriegelten Pages-Seiten funktioniert.
• Bilder: Kopiere sie nach site/img/, verkleinert und mit entfernten Metadaten (mit ImageMagick: magick in -auto-orient -strip -resize 1200x -quality 80 out.jpg). Überprüfe die Originalbilder des Repos auf GPS-EXIF (z. B. identify -format '%[EXIF:GPSLatitude]' oder exiftool -gps:all) und warne den Benutzer, falls welche gefunden werden. Handyfotos enthalten meist den Standort, an dem sie aufgenommen wurden. Sobald sie gepusht sind, befinden sie sich in der Git-Historie, sodass ihre Entfernung einen History-Rewrite erfordert, was die Entscheidung des Benutzers ist.

5. Veröffentlichung einrichten

• GitHub: Kopiere github-pages.yml. Pages muss einmal mit Quelle = Aktionen aktiviert werden (Einstellungen → Pages) oder mit dem folgenden Befehl. Gib Befehle, die der Benutzer in einem Code-Block ohne nachfolgende Zeichen kopieren kann. Ein Punkt am Satzende, der mitkopiert wird, landet im Argument (build_type=workflow.), und die API lehnt es ab:

  gh api -X POST repos/BESITZER/REPO/pages -f build_type=workflow
  

  Es stellt nur vom Standard-Branch bereit.
• GitLab: Füge den pages-Job in jede vorhandene .gitlab-ci.yml ein; überschreibe sie nicht. Pages wird automatisch aktiviert; die URL wird unter Bereitstellen → Pages angezeigt.
• Füge einen kurzen Link-Absatz zum Abschnitt „Übersicht“/„Wie es funktioniert“ der README hinzu.

6. Vor der Meldung überprüfen

• node --check site/*.js
• Bereitstellen mit python3 -m http.server 8765 --bind 127.0.0.1 --directory site (im Hintergrund). Falls ein Browser-Automatisierungswerkzeug verfügbar ist (z. B. Claude in Chrome), öffne die Seite, mache Screenshots von jedem Kapitel und bediene jede Demo, indem du JavaScript in der Seite ausführst (.click(), dispatche PointerEvents), anstatt auf Koordinaten zu klicken: Screenshots sind oft relativ zu CSS-Pixeln skaliert, sodass Koordinatenklicks daneben treffen. Wenn das Fenster nicht verkleinert werden kann, überprüfe die Telefonbreite, indem du die Seite in einem 380 px breiten Iframe lädst und nach Elementen mit getBoundingClientRect().right > 381 suchst.
• Ohne Browser-Werkzeug: Sage dem Benutzer, welche Seiten und Demos er von Hand überprüfen soll. Melde die Seite nicht als getestet.
• Schließe alle geöffneten Tabs und stoppe den Server danach.

7. Übergeben

Frage vor dem Committen oder Pushen. Dann auf einem Branch: ein Commit für die Seite, separate Commits für eventuelle Code-Korrekturen, die der Benutzer wünscht. Melde: was gebaut wurde, wie man Pages aktiviert, die Liste der Diskrepanzen und alles, was nicht getestet wurde (z. B. Hardware).

Stilregeln

• Dunkles Theme standardmäßig (Tokens in deck.css), mit einem roten Akzent, der pro Projekt über --accent umgefärbt werden kann.
• Klarer, konkreter Text. Erkläre, warum eine Designentscheidung existiert, nicht nur, was sie tut.
• Code-Auszüge sind kurz und echt (aus der Quelle gekürzt, mit einem Kommentar, der die Datei nennt).
• Tastatur: ←/→/Leertaste/Bild↑/Bild↓/Pos1/Ende, O für die Übersicht, Esc zum Schließen. Wischen auf Touch. Jede Folie hat ihre eigene URL (#/slide-id).