Communitygithub.com

pessimistcamellia/proto-note

Cursor Agent Skill: Erstelle interaktive HTML-Prototypen mit Änderungsnotizen, Ankern, Verbindungen und SDD-Deep-Links. Axure-ähnlicher Anmerkungsbalken.

Was ist proto-note?

Diese Fähigkeit für Cursor Agent (prototyping-note-layer) ermöglicht es, in einem einzigen HTML-Prototyp eine „Entwickler-Änderungsführung“ zu überlagern. Sie besteht aus einem fixierten, dunklen Anmerkungsbalken auf der rechten Seite, der Module und Änderungskarten kombiniert, welche mit Seitenankern und Canvas-Verbindungen interagieren. Entwickler können durch Hover oder Klick bidirektional navigieren und jede Änderungskarte kann einen Deep-Link zur zugehörigen SDD-Dokumentation enthalten. Die Fähigkeit ist für den Einsatz in Cursor (v0.45+) konzipiert. Sie priorisiert die Nutzung realer UI-Bibliotheken und Komponenten des Zielsystems, wobei sie auf die interne Hosting-Umgebung (Intranet) oder als Fallback auf GitHub Pages als Veröffentlichungsplattform zurückgreift. Der Workflow umfasst das Extrahieren von Änderungen aus PRDs, das Mapping zu SDD-Abschnitten, die Erstellung von Prototypen pro System/Seite, die Integration der Anmerkungsschicht sowie die automatische Bereitstellung und Selbstprüfung.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor
npx skills add pessimistcamellia/proto-note
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

Prototyp-Änderungsnotizen-Schicht (proto-note)

Überlagere einen einzelnen HTML-Prototypen mit einer „Entwickler-Änderungsführung“: Fixierter, dunkler Anmerkungsbalken (Modulauswahl + Anmerkungskarten) ↔ Seitenanker-Punkte + Canvas-Verbindungen; bidirektionales Hover-/Klick-Locator; Anmerkungskarten mit SDD-Deep-Links.

Installation und Verzeichnis

# Persönliche Fähigkeit (empfohlen)
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# Oder innerhalb eines Projekts
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

Alternativ kann das gesamte Verzeichnis in den oben genannten Pfad kopiert werden. Verzeichnisstruktur:

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # Annotations-Engine (als Ganzes in den Prototyp integriert, Logik nicht ändern)
├── references/changeset-schema.md
├── docs/screenshots/             # Screenshots für die README
└── scripts/deploy_github.sh      # Backup-Bereitstellung für GitHub Pages

Umgebungsabhängigkeiten

FähigkeitWerkzeugFehlschlagverhalten
Technologie-Stack/Quellcode-Lokalisierungcodewiki MCP (oder gleichwertige Code-Recherche)Verwende Online-URL + Quellcode-Repository + Browser-DOM zur Rekonstruktion
SDD Deep-Linklark-cli (Lark)Manuelles Ausfüllen der Dokumenten-URL und des Kapitel-blockId; für Nicht-Lark-Systeme: Verlinke auf den entsprechenden Kapitel-Anker
Pixelgenaue KalibrierungBrowser DevTools / chrome-devtools MCPManuelles Öffnen der Online-Seite zum Vergleich
BereitstellungInterne statische Hosting-Umgebung (bevorzugt)Persönliches GitHub Pages (deploy_github.sh, benötigt gh-Autorisierung)

Falls das Team über weitere Frontend-Regel-Fähigkeiten (z. B. Whitelist für Bibliotheken, Komponentenverwendung) verfügt, lese diese vor der Erstellung je nach Bedarf; anderenfalls orientiere dich am Quellcode des Ziel-Repositorys und der Team-Dokumentation.

Standard-Schema: Komponentenbibliothek und Veröffentlichungs-Priorität

Ausführen nach Priorität; nur wenn die vorherige Stufe nicht verfügbar ist, wird auf die nächste zurückgegriffen; die letzte Stufe ist die Standard-Fallbacklösung:

  1. Komponentenbibliothek / Standard (bevorzugt): Verwende die reale, im Zielsystem verwendete Komponentenbibliothek und deren Konventionen (anhand Quellcode / DOM / Team-Komponentenregel-Fähigkeit). Kein unbegründeter Bibliothekswechsel.
  2. Veröffentlichungsadresse (bevorzugt): Wenn ein bestehendes internes statisches Hosting (oder eine im Team vereinbarte interne Adresse) vorhanden ist, veröffentliche bevorzugt im Intranet.
  3. Standard-Fallback: Falls die reale Komponentenbibliothek / -spezifikation nicht ermittelt werden kann oder aufgrund von Berechtigungen, Netzwerk, nicht erreichbarem Intranet etc. nicht verwendet werden kann → Komponenten können nach einem allgemeinen Schema frei gewählt werden (bleibt dennoch als interaktives Einzel-HTML); veröffentliche im persönlichen GitHub-Repository (Pages) des Benutzers. Vor der Bereitstellung muss die gh-Autorisierung bestätigt werden; ohne Autorisierung zuerst mit dem Benutzer kommunizieren; es ist verboten, ohne Zustimmung in ein privates Repository zu pushen.

Produkt-Grundregeln

  1. Änderungsebenen + Typen: Seite / Modul / Feld; Typen unterscheiden: Neu, Textänderung, Aufzählungsdefinition, Logik, Ablauf, Löschung. Verallgemeinernde Angaben wie „Neu“ sind verboten.
  2. Standardmäßig versteckt, Modul-Auswahl: Beim Öffnen werden keine Anmerkungen angezeigt; Auswahl nach page::module; Zustand in localStorage. Fehlende Keys bei neuen Modulen sind standardmäßig true (sichtbar); es ist verboten, zu erben, dass ein Schalter jemals ausgeschaltet war, um die Sichtbarkeit zu bestimmen; unsaubere Zustände werden durch Upgrade der LS_KEY-Version gelöscht.
  3. Nur mit SDD verknüpfen, kein PRD anzeigen: Anmerkungskarten verwenden SDD-Dokumenten-URL#blockId.
  4. Informationen minimieren: Keine Versionsnummern/Baselines/Bedienungsanleitungen im Anmerkungsbalken; desc enthält nur die Schlussfolgerung.
  5. Klickbar muss funktionieren: Anklicken eines Moduls schaltet die Ansicht um + scrollt + pulsiert zur Position.
  6. Review-Zustand nur im Anmerkungsbalken: Normalzustand/Leerzustand/Fehlerzustand etc. in demoControls; echte Business-Tabs bleiben in der Business-Seite.
  7. Eingabezweige mit reproduzierbaren Beispielen: examples müssen mit den Fixtures übereinstimmen; keine Platzhalter mit falschen Werten.
  8. Anmerkungsbalken blockiert nicht den Inhalt: Keine Komprimierung des Business-Layouts; verwende Spacer zur Erweiterung des scrollWidth. Horizontales Scrollen, um die rechte Seite vollständig zu sehen. Kein body padding-right oder Änderung der Business-Root-Breite.
  9. Komponentenbibliothek und -spezifikation bevorzugen die echte Online-Version: Wenn möglich, muss rekonstruiert werden (siehe „Standardschema“ Stufe 1). Gleiche Komponentenbibliothek bedeutet nicht Rekonstruktion – Skelette, Spaltensets/-breiten, fixierte Spalten, Zellenstrukturen, Aktionsspalten-Layouts, benutzerdefinierte Klassennamen und wichtige Styles müssen mit dem Online-DOM/Quellcode abgeglichen werden; vor Auslieferung Screenshot-für-Screenshot vergleichen. Nur wenn keine echte Komponentenbibliothek/-spezifikation ermittelt werden kann, ist ein Fallback auf allgemeine Komponenten erlaubt.
  10. Veröffentlichung bevorzugt im Intranet, sonst persönliches GitHub: Wenn eine Intranet-Adresse vorhanden ist, diese bevorzugen; wenn nicht, auf persönlichem GitHub Pages veröffentlichen (siehe „Standardschema“ Stufen 2–3).
  11. „Vorher“ = aktueller Online-Zustand: Bei Neuerungen schreibe „Keine dieser Seite/dieses Moduls/dieser Funktion/dieses Feldes vorhanden“; keine Angabe als Differenz zur vorherigen Demo; neue Online-Punkte dürfen nicht übersehen werden.
  12. Keine UI-Landepunkte → keine Verbindung: Reine Prozess-/Ablaufänderungen: target: null, kein Anker; Karte in „Prozesse & Abläufe · Seite nicht sichtbar“ und ans Ende der Changes setzen.
  13. Änderungen innerhalb eines Popups: Beim Anklicken der Anmerkungskarte muss DIFF_HOOKS.locate das Popup öffnen, bevor die Verbindung gezeichnet wird; Anker/Verbindungen haben einen höheren z-index als das Popup (Engine verwendet 9000er Bereich).
  14. Popup scrollt mit der Seite mit: Bei geöffnetem Anmerkungsbalken wird der Popup-Container mit (-scrollX,-scrollY) verschoben (von der Engine behandelt); kein Fixieren des Scrollens zur Umgehung.
  15. Herunterladbare Dateien im korrekten Format: Vorlagen/Quittungen haben dasselbe Format und dieselbe Struktur wie im echten Geschäft (z. B. echte .xlsx mit zwei Sheets); Verwenden von CSV als Ersatz ist verboten.
  16. Mehrere Endpunkte separat erstellen und verknüpfen: Admin-Backend, C-Seite etc. nach Systemgrenzen in separaten HTMLs; einheitliches Menü mit „Endpunkt · Seite“; bei seitenübergreifenden Daten das Schreiben/Lesen/Starten/Stoppen/Fehler simulieren.
  17. Anmerkungskarten müssen zu SDD springen können: Jede Änderung (oder der zugehörige Funktionspunkt) erhält sdd.section + blockId; die Karte rendert einen Deep-Link; Klick sollte das entsprechende Kapitel öffnen, nicht nur den Kapitelnamen anzeigen.

Präsentationsschicht-Spezifikation (bereits in der Engine enthalten, nicht rückgängig machen)

  • Rechter Anmerkungsbalken: Dunkles Marineblau, Breite 360px, einklappbar als schwebender Einstieg.
  • Horizontales Scrollen: Verwende document.body.scrollWidth zur Messung der Business-Breite (Spacer als absolute, wird nicht hinzugefügt); nicht zuerst den Spacer verstecken und dann messen. Wiederherstellung des Scrollens mit behavior: "instant", um Konflikte mit scroll-behavior:smooth zu vermeiden.
  • Anker: Dokumentkoordinaten (position:absolute), fixiert an der oberen linken Ecke des Ziels; fixed + verfolgendes Scrollen ist verboten; Verdeckung mit elementFromPoint verstecken.
  • Verbindungen: Normal keine Linien; bei Hover/Fixierung nur eine Linie zeichnen; fixierter Zustand hat Vorrang vor Hover-Zustand; Startpunkt ist das aktuelle rect.
  • Anmerkungskarte: Nummer + Titel + Typ·Ebene + Schlussfolgerung + Vorher/Nachher + SDD; kann examples enthalten.
  • Demobereich: Segmented Control oben im Anmerkungsbalken → DIFF_HOOKS.setDemoState.

Technologie-Stack-Rekonstruktion (Schritt 0)

Ausführen nach dem „Standardschema“: Wenn möglich, rekonstruieren; wenn nicht, den Grund dokumentieren und dann zur freien Auswahl als Fallback übergehen.

  1. Hat der Benutzer keine Online-URL angegeben → zuerst daran erinnern; falls weiterhin keine vorhanden, selbstständig das System/die Routen/den Quellcode durchsuchen.
  2. Mit codewiki (oder Quellcode-Recherche) bestätigen: Framework, Komponentenbibliothek, Routen → Seitendateien, wichtige Vorlagenfragmente; ggf. Aktualität des Index prüfen und mit Online-DOM kalibrieren.
  3. Bevorzugt die reale Komponentenbibliothek und Spezifikation aus dem Ziel-Repository verwenden; neue Steuerelemente übernehmen den bestehenden Typ/die Größe/Anordnung dieser Seite. Gleiche Komponentenbibliothek bedeutet nicht Rekonstruktion – Skelette, Spaltenbreiten, fixierte Spalten, Zellenstrukturen, Aktionsspalten-Layouts, benutzerdefinierte Klassennamen müssen mit dem Online-DOM/Quellcode abgeglichen werden.
  4. Falls Team-Komponentenregel-Fähigkeit vorhanden, dieser folgen; anderenfalls am Ziel-Repository und der Dokumentation orientieren.
  5. Bei unzureichenden Pixel- oder Rechercheinformationen: Öffne die Online-Seite und erfasse die Mount-Methode, Komponenten-Klassennamen, Tabellenspaltenbreiten/fixierte Spalten, Aktionsspalten-Struktur, benutzerdefinierte Computed Styles.
  6. Ausgabe bleibt ein einzelnes HTML; falls möglich, dasselbe Framework/dieselbe Komponentenbibliothek über CDN einbinden. Wenn die gesamte Seite nicht rekonstruiert werden kann, eine gängige Komponentenbibliothek für den interaktiven Prototyp frei wählen und im Auslieferungshinweis die „Ursache für die Nicht-Rekonstruktion“ angeben.
  7. Veröffentlichung: Bei vorhandener interner statischer Adresse bevorzugt dort hochladen; sonst nach Erhalt der GitHub-Autorisierung des Benutzers mit deploy_github.sh im persönlichen Repository veröffentlichen.

Häufige Fallstricke: Keine übermäßige min-width für äußere Container setzen, die die Tabelle aufbläht (dadurch gehen internes horizontales Scrollen und fixed-Spalten verloren); das einheitliche Menü in der Kopfzeile mit position:fixed, um zu vermeiden, dass die Kopfzeile bei breiten Seiten bricht.

Mehrere Seiten / Mehrere Endpunkte und Datenverknüpfung

  1. Zuerst eine Matrix erstellen: Endpunkt/System → Seite → Schlüsselzustände → Datenflüsse; verschiedene Technologie-Stacks in separaten Dateien, nicht gewaltsam zusammenführen.
  2. Einheitliches Menü: „Endpunkt · Seite“-Benennung, aktuelle Seite hervorheben; Menüs werden nicht mit Änderungsnotizen versehen.
  3. Gleicher Ursprung, gleiches Verzeichnis bereitstellen, um localStorage-Freigabe zu gewährleisten.
  4. Gemeinsamer Zustands-Key: proto-note:<requirement-slug>:state:v1; nach dem Schreiben/Lesen ein Ereignis auf derselben Seite auslösen, über Tabs hinweg auf storage hören.
  5. URL trägt nur die Business-ID; der Inhalt im gemeinsamen Zustand. Bei unterschiedlichen Ursprüngen bevorzugt gleichen Ursprung herstellen, sonst postMessage und origin validieren.
  6. Eingebaute Fixtures + "Demo-Daten zurücksetzen"; Zustände und Fehler der verbundenen Systeme reproduzierbar.

Arbeitsablauf

  1. Schritt 0: Technologie-Stack-Rekonstruktion.
  2. Aus der PRD die Änderungsliste, Endpunkt/Seiten-Matrix, Eingabezweige und seitenübergreifende Datenbeziehungen extrahieren → siehe references/changeset-schema.md.
  3. SDD blockId abrufen und in jede sdd schreiben.
  4. Prototypen pro Endpunkt erstellen; bei mehreren Endpunkten mit Menü und gemeinsamem Zustand versehen und Verknüpfung testen.
  5. Anmerkungsschicht einbinden:
    • Container mit data-diff-page versehen; Landepunkte mit id ergänzen; DIFF_HOOKS.locate / setDemoState implementieren.
    • Review-Tabs in meta.demoControls verschieben.
    • Zweige in examples schreiben (konsistent mit Fixtures).
    • Vor </body> DIFF_CHANGESET inline einfügen, dann die gesamte neueste assets/diff-annotator.js kopieren (keine veraltete Kopie verwenden).
  6. Bereitstellung und Selbstprüfung:

    • Bevorzugt Intranet: Bei bestehendem internen statischen Hosting dort hochladen; falls Objektschlüssel nicht überschrieben werden können, neuen Pfad verwenden (z. B. -v2), anhand der zurückgegebenen URL + md5.

    • Fallback GitHub Pages: Wenn Intranet nicht verfügbar, im persönlichen Repository veröffentlichen. Zuerst gh auth status; bei fehlender Berechtigung kommunizieren und gh auth login durchführen; es ist verboten, ohne Autorisierung in ein privates Repository zu pushen:

      bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html

Selbstprüfliste

  • Wenn möglich, wurde die echte Online-Komponentenbibliothek/-spezifikation verwendet; wenn nicht, wurde die Ursache dokumentiert und die freie Auswahl als Fallback gewählt
  • Veröffentlichung bevorzugt im Intranet; wenn Intranet nicht verfügbar, nach Autorisierung auf persönlichem GitHub veröffentlicht
  • Bildschirm-für-Bildschirm mit Online-Version verglichen (falls vorhanden: Spaltenbreite, fixierte Spalten, Aktionsspalte, Paginierung, Kopfzeile)
  • Anfangs keine Anker/Verbindungen; Module nicht ausgewählt; neue Module für wiederkehrende Besucher standardmäßig sichtbar
  • Auswahl eines Moduls zeigt nur die entsprechende Karte/Anker/Verbindung und positioniert automatisch; Änderungen innerhalb eines Popups öffnen das Popup automatisch und die Verbindung liegt über dem Popup
  • Kein Anker-Drift beim Scrollen; normal keine Linien, bei Fixierung/Hover nur eine Linie; fixierter Zustand wird nicht von Hover überschrieben
  • Bei geöffnetem Anmerkungsbalken kann horizontal gescrollt werden, um die rechte Seite vollständig zu sehen; horizontale Scrollposition springt nicht durch DOM-Updates zurück; Popup scrollt mit der zugrunde liegenden Seite mit
  • target:null hat keinen Anker, Karte in „Prozesse & Abläufe“ und weiter hinten; „Vorher“ ist immer der aktuelle Online-Zustand, keine übersehenen Markierungen
  • SDD-Deep-Link auf der Anmerkungskarte kann das entsprechende Kapitel öffnen und positionieren
  • Demo-Zustand nur im Anmerkungsbalken; Beispiele reproduzierbar; heruntergeladene Dateien im korrekten Format
  • Mehrseitenmenü erreichbar; Lesen/Schreiben/Aktualisieren/Tab-übergreifend/Zurücksetzen konsistent zwischen Prototypen
  • Eingeklappter Anmerkungsbalken ist sauber; Business-Interaktionen nicht beeinträchtigt

Referenzen

Verwandte Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community