minhtran3124/cursor-skills

Visual – Skill-Graph-Visualisierer

Bildet jeden Skill im Projekt als gerichteten Graphen ab: was jeder Skill konsumiert, was er produziert und wie Skills zu Workflows verknüpft sind. Erzeugt zwei Ausgaben – eine Mermaid-Markdown-Datei für die Dokumentation und einen interaktiven Browser-Graphen zur Erkundung.

Ankündigung zu Beginn: „Skill-Graph wird kartiert …“

Verwendung

Führe /visual aus, wenn du:

• Auf einen Blick verstehen möchtest, wie alle Skills zusammenhängen
• Neue Mitwirkende in das Skill-Ökosystem einarbeiten möchtest
• Den Graphen nach dem Hinzufügen oder Ändern eines Skills prüfen möchtest

Arbeitsablauf

Schritt 1: Alle Skills scannen

find skills/ -name "SKILL.md" 2>/dev/null | sort

Lesen aller SKILL.md-Dateien vollständig ein.

---

Schritt 2: Metadaten aus jedem Skill extrahieren

Für jede Skill-Datei folgende Felder extrahieren:

Feld	Quelle
id	Verzeichnisname (z.B. skills/walkthrough/ → walkthrough)
label	name-Frontmatter, ergänzt um das Emoji aus der README, falls bekannt
description	description-Frontmatter – nur erster Satz
triggers	Inhalt: im Text gefundene /command-Muster
inputs	Inhalt: vom Skill gelesene Dateien/Quellen (z.B. git diff, docs/plans/)
outputs	Inhalt: vom Skill geschriebene Dateien (z.B. .review/review.md)
relationships	relationships-Frontmatter-Array – siehe Schema unten

Schema des Relationships-Frontmatters (explizit, bevorzugt):

relationships:
  - target: <skill-id>         # Verzeichnisname eines anderen Skills
    type: <relationship-type>  # einer der unten stehenden Typen
    label: <kurzer Ausdruck>   # wird auf der Graph-Kante angezeigt (≤ 5 Wörter)

Beziehungstypen:

Typ	Bedeutung	Pfeil-Stil
leads-to	Empfohlener nächster Schritt nach diesem Skill	durchgehend -->
alternative	Alternative für denselben Zweck	gestrichelt -.->
complements	Anderer Zweck, passt gut zusammen	durchgehend -->
feeds-from	Dieser Skill konsumiert die Ausgabe des Ziels	durchgehend -->
analyzes	Dieser Skill liest und verarbeitet die Dateien des Ziels	durchgehend -->

---

Schritt 3: Beziehungen ableiten (nur als Fallback)

Für Skills ohne relationships-Frontmatter aus dem Inhalt ableiten:

1. Benannte Trigger-Referenzen: Der Inhalt erwähnt den /command oder Verzeichnisnamen eines anderen Skills → Kante vom Typ leads-to zum referenzierten Skill.
2. Gemeinsame I/O: Zwei Skills lesen/schreiben denselben Dateipfad → Kante vom Typ complements zwischen ihnen.
3. Workflow-Sprache: Der Inhalt enthält Ausdrücke wie „nachdem X ausgeführt wurde“, „vor der Verwendung von Y“, „funktioniert gut mit Z“ → gerichtete Kante entsprechend der Formulierung.
4. Wissenssenke-Muster: Ein Skill, der nur in einen Wissensspeicher schreibt, ohne dass ein anderer Skill dessen Ausgabe als Eingabe verwendet → andere Skills, die das Aufbewahren von Erkenntnissen erwähnen, zeigen mit leads-to darauf.

Alle abgeleiteten Kanten mit "inferred": true im Graph-Modell markieren. Diese werden in beiden Ausgaben als gestrichelte Linien dargestellt.

---

Schritt 4: Internes Graph-Modell erstellen

Diese JSON-Struktur intern erzeugen (nicht auf Disk schreiben):

{
  "skills": [
    {
      "id": "walkthrough",
      "label": "🚶 walkthrough",
      "description": "Ein Satz.",
      "triggers": ["/walkthrough"],
      "inputs": ["git diff"],
      "outputs": []
    }
  ],
  "edges": [
    {
      "source": "walkthrough",
      "target": "compound",
      "type": "leads-to",
      "label": "Sitzungserkenntnisse speichern",
      "inferred": false
    }
  ]
}

---

Schritt 5: docs/SKILL_GRAPH.md schreiben

docs/ anlegen, falls nicht vorhanden. docs/SKILL_GRAPH.md mit vier Abschnitten schreiben:

Abschnitt 1 – Übersichtsgraph

## Skill-Übersicht

\`\`\`mermaid
flowchart LR
    classDef skill fill:#1a1a2e,stroke:#4a90d9,color:#e0e0ff
    classDef terminal fill:#0d2618,stroke:#4a9d6f,color:#a0ffa0

    skill-a["emoji name\n/trigger"]:::skill
    skill-b["emoji name\n/trigger"]:::skill
    ...

    skill-a -->|"label"| skill-b
    skill-c -.->|"label"| skill-d
\`\`\`

Regeln:

• leads-to- und complements-Kanten: durchgehend -->
• alternative- und abgeleitete Kanten: gestrichelt -.->
• Knotenbeschriftungsformat: "emoji name\n/trigger" (\n für Zeilenumbruch verwenden)
• Skills ohne ausgehende leads-to-Kante erhalten die Klasse :::terminal
• Mermaid-Knoten-IDs müssen gültige Bezeichner sein – Bindestriche in IDs durch Unterstriche ersetzen, Beschriftung unverändert lassen

Abschnitt 2 – Workflow-Ketten

Alle Einstiegs-Skills finden (Skills ohne eingehende leads-to-Kanten). Für jeden den vollständigen leads-to-Pfad verfolgen und einen benannten Workflow schreiben:

## Workflows

### Code-Review-Workflow
\`\`\`mermaid
flowchart LR
    walkthrough -->|"Erkenntnisse speichern"| compound
\`\`\`

### Implementierungs-Workflow
...
\`\`\`

Wenn zwei Pfade denselben Endknoten teilen, können sie in einem Diagramm dargestellt werden.

Abschnitt 3 – Datenfluss

Eingabequellen, Skills und Ausgabeartefakte anzeigen. Nur Skills mit expliziten Ein- oder Ausgaben in ihren Metadaten aufnehmen:

## Datenfluss

\`\`\`mermaid
flowchart LR
    classDef artifact fill:#1a1a1a,stroke:#888,color:#ccc
    classDef ext fill:#2a1a0a,stroke:#d9904a,color:#ffd0a0

    git_diff[/"git diff"/]:::ext
    review_md[".review/review.md"]:::artifact

    git_diff --> review_diff
    review_diff --> review_md
\`\`\`

Abschnitt 4 – Skill-Index

Eine Tabelle: Skill | Trigger | Beschreibung | Liest | Schreibt

---

Schritt 6: Interaktive HTML-Ausgaben generieren

Das Graph-Modell aus Schritt 4 in einen einzeiligen, minimierten JSON-String serialisieren. Diesen JSON-String für beide unten stehenden Ausgaben verwenden (gleiche Daten, unterschiedliche Vorlagen).

6a – Skill-Dashboard (primäre Ausgabe)

skills/visual/references/dashboard-template.html öffnen. /* GRAPH_DATA_JSON */ durch den JSON-String ersetzen. In .docs/skill-dashboard.html schreiben.

Das Dashboard hat drei Tabs:

• Skills – Raster mit Karten für jeden Skill: Trigger, Beschreibung, Lese-/Schreibzugriffe, ausgehende Beziehungen
• Graph – interaktiver Cytoscape-Graph (lazy-initialisiert beim ersten Öffnen des Tabs)
• Workflows – automatisch abgeleitete Workflow-Ketten, Alternativen und Komplemente

6b – Eigenständiger Graph (sekundäre Ausgabe)

skills/visual/references/graph-template.html öffnen. /* GRAPH_DATA_JSON */ durch denselben JSON-String ersetzen. In .docs/skill-graph.html schreiben.

Falls eine der Vorlagendateien nicht gefunden wird, diese Ausgabe überspringen und im Bericht vermerken.

---

Schritt 7: Auffindbarkeitsprüfung

In CLAUDE.md nach SKILL_GRAPH suchen. Falls nicht gefunden, Folgendes vorschlagen:

Der Skill-Graph in docs/SKILL_GRAPH.md ist noch nicht in CLAUDE.md referenziert. Diesen Block hinzufügen, damit zukünftige Agenten ihn automatisch finden?

## Skill-Graph
Skill-Beziehungen und Workflows: `docs/SKILL_GRAPH.md`
Dashboard (Skills + Graph + Workflows): `.docs/skill-dashboard.html`
Eigenständiger Graph: `.docs/skill-graph.html`

Zu CLAUDE.md hinzufügen? (ja/nein)

Nicht automatisch schreiben. Vor der Änderung von CLAUDE.md auf Zustimmung warten.

---

Schritt 8: Abschlussbericht ausgeben

★ Skill-Graph kartiert
  Skills:        N
  Beziehungen:   M explizit, K abgeleitet
  → docs/SKILL_GRAPH.md              [Mermaid-Übersicht + Workflows + Datenfluss + Index]
  → .docs/skill-dashboard.html       [Dashboard: Skills-Karten + Graph + Workflows]
  → .docs/skill-graph.html           [Eigenständiger interaktiver Graph]
  CLAUDE.md: gefunden ✓ / noch nicht referenziert

---

Wichtige Einschränkungen

• Niemals automatisch in CLAUDE.md schreiben – immer zuerst fragen
• Explizit vor abgeleitet – relationships-Frontmatter hat immer Vorrang; abgeleitete Kanten in beiden Ausgaben gestrichelt
• Idempotent – erneutes Ausführen von /visual überschreibt beide Ausgabedateien vollständig
• Nicht destruktiv – niemals eine SKILL.md-Datei ändern; nur in docs/ und .docs/ schreiben
• Mermaid-Knoten-IDs: Bindestriche durch Unterstriche ersetzen, um Parse-Fehler zu vermeiden (z.B. review_diff statt review-diff)
• Knotenbeschriftungslänge: Zeilen durch \n geteilt auf jeweils maximal 20 Zeichen halten