docs: improve mac cowork plugin installation guidance

2026-06-09 10:03:19 +00:00 · 2026-05-31 17:32:13 +02:00
parent 90d0cbc8c6
commit 8d64f183ef
3 changed files with 82 additions and 36 deletions
@@ -6,7 +6,7 @@

 ## Kurzfassung

-> 📆 **Hinweis Release vs. Entwicklungsstand:** Die ZIPs in der Releases-Seite entsprechen einem **getaggten, validierten Stand** (zur Zeit `v7.0.0`). Der `main`-Branch des Repos kann **neuer** sein — mit weiteren Fixes, kleinen Ergänzungen oder neuen Tests. Für stabile Tagung → ZIPs aus dem Release; für neueste Korrekturen → Marketplace-Sync über den GitHub-Pfad (siehe README.md, Weg 1).
+> 📆 **Hinweis Release vs. Entwicklungsstand:** Die ZIPs in der Releases-Seite entsprechen einem **getaggten, validierten Stand** (aktuell siehe [latest Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest)). Der `main`-Branch des Repos kann **neuer** sein — mit weiteren Fixes, kleinen Ergänzungen oder neuen Tests. Für stabile Nutzung → ZIPs aus dem Release; für neueste Korrekturen → Marketplace-Sync über den GitHub-Pfad (siehe README.md, Weg 1).

 1. Auf [die Releases-Seite](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) gehen.
 2. Pro gewünschtem Rechtsgebiet **eine ZIP-Datei** herunterladen, z. B. `liquiditaetsplanung.zip`.
@@ -23,9 +23,31 @@ Das war's. In der Plugin-Liste erscheint das Plugin direkt, kann aktiviert werde
 >
 > Es ist nichts Schlimmes, wenn das versehentlich passiert. Die ZIP wird einfach abgelehnt; nichts geht kaputt.

+## Mac / Cowork: wenn der ZIP-Upload zickt
+
+Auf dem Mac scheitert der Upload meistens nicht am Plugin, sondern am Weg, wie die Datei gespeichert oder ausgewählt wurde. Diese Reihenfolge ist am robustesten:
+
+1. **Einzelnes Plugin-ZIP aus dem Release laden**, z. B. `liquiditaetsplanung.zip`. GitHub unterstützt stabile Links nach dem Muster `.../releases/latest/download/<dateiname>.zip`; die Links im README verwenden genau dieses Schema.
+2. **Safari-Falle prüfen:** Safari kann ZIP-Dateien nach dem Download automatisch entpacken. Wenn im Download-Ordner statt `liquiditaetsplanung.zip` nur ein Ordner liegt, diesen Ordner **nicht** hochladen. Entweder die ZIP-Datei erneut laden, Safari → Einstellungen → Allgemein → "Sichere Dateien nach dem Laden öffnen" deaktivieren, oder Chrome/Firefox nutzen.
+3. **Nicht aus iCloud-Platzhaltern hochladen.** Die Datei erst lokal greifbar machen, z. B. in `~/Downloads/claude-plugins/`. Wenn neben der Datei noch ein Cloud-/Downloadsymbol steht, erst vollständig laden.
+4. **Nur eine Plugin-ZIP auswählen.** `alle-plugins-megazip.zip` ist ein Sammelarchiv; es muss zuerst entpackt werden. Danach werden die darin liegenden Einzel-ZIPs nacheinander hochgeladen.
+5. **Cowork-Limits beachten.** Beim Organisations-Upload müssen Plugin-ZIPs gültige ZIP-Dateien unter 50 MB sein. Wer wirklich alle 110 Plugins organisationsweit verteilen will, sollte nicht alle manuell in einen einzelnen manuellen Marketplace drücken; dafür ist der GitHub-Sync/Marketplace-Weg robuster.
+6. **Datei wirklich als ZIP prüfen.** Im Finder darf es nicht `liquiditaetsplanung.zip.zip` oder ein entpackter Ordner sein. Im Zweifel im Terminal:
+
+```bash
+file ~/Downloads/claude-plugins/liquiditaetsplanung.zip
+unzip -l ~/Downloads/claude-plugins/liquiditaetsplanung.zip | head
+```
+
+In der Ausgabe sollte direkt `.claude-plugin/plugin.json` und ein `skills/`-Ordner sichtbar sein. Wenn das nicht der Fall ist, ist es nicht das richtige Upload-ZIP.
+
+7. **Nach dem Upload neue Konversation starten.** In Claude Code kann man nach Installation oder Aktivierung zusätzlich `/reload-plugins` ausführen; in Desktop/Cowork reicht normalerweise ein neuer Chat oder ein Reload der Oberfläche.
+
+Wenn der Mac-Dialog weiterhin hakelt, ist der pragmatische Weg: auf einem PC in Cowork unter **Customize → Skills / Plugins → Personal plugins → Upload from .zip** hochladen. Das Ergebnis hängt am Account bzw. an der Organisation, nicht daran, dass die ZIP zwingend auf dem Mac hochgeladen wurde.
+
 ## Welches ZIP brauche ich?

-Auf der [Releases-Seite](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) liegen **102 Plugin-ZIPs** — eines pro Rechtsgebiet bzw. Werkzeug. Es muss nicht alles installiert werden; nur das, was gerade gebraucht wird.
+Auf der [Releases-Seite](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) liegen **110 Plugin-ZIPs** — eines pro Rechtsgebiet bzw. Werkzeug. Es muss nicht alles installiert werden; nur das, was gerade gebraucht wird.

 ### Kanzlei-Backoffice und Querschnitt

@@ -160,7 +182,7 @@ In aktuelleren Claude-Code- / Cowork-Versionen geht auch direkt der Marketplace-

 ```text
 /plugin marketplace add Klotzkette/claude-fuer-deutsches-recht
-/plugin install liquiditaetsplanung
+/plugin install liquiditaetsplanung@klotzkette-german-legal-skills
 ```

 Falls das ebenfalls kein Dialogfeld findet, ist die Cowork-Version zu alt für Marketplaces — dann ist der ZIP-Upload oben der einzige Weg, und das ist völlig in Ordnung. Er funktioniert in jeder Version, die Plugin-Upload überhaupt kennt.
@@ -12,11 +12,11 @@ Diese Anleitung führt in 5 Minuten zur ersten produktiven Nutzung der Plugins i

 ### Option A – Marketplace direkt aus GitHub

-```bash
+```text
 /plugin marketplace add Klotzkette/claude-fuer-deutsches-recht
-/plugin install arbeitsrecht
-/plugin install vertragsrecht
-/plugin install datenschutzrecht
+/plugin install arbeitsrecht@klotzkette-german-legal-skills
+/plugin install vertragsrecht@klotzkette-german-legal-skills
+/plugin install datenschutzrecht@klotzkette-german-legal-skills
 ```

 ### Option B – Lokal aus Klon
@@ -24,13 +24,19 @@ Diese Anleitung führt in 5 Minuten zur ersten produktiven Nutzung der Plugins i
 ```bash
 git clone https://github.com/Klotzkette/claude-fuer-deutsches-recht.git
 cd claude-fuer-deutsches-recht
+claude
+```
+
+Danach im Claude-Code-Prompt:
+
+```text
 /plugin marketplace add .
-/plugin install arbeitsrecht
+/plugin install arbeitsrecht@klotzkette-german-legal-skills
 ```

 ### Option C – Einzelnes Plugin direkt

-```bash
+```text
 /plugin install ./prozessrecht
 ```

@@ -59,13 +59,13 @@ Die vollständige Plugin-Liste findest du in [`.claude-plugin/marketplace.json`]

 ## Quickstart

-```bash
-# Marketplace im Claude-Code-CLI hinzufügen
+```text
+# Marketplace im Claude-Code-Prompt hinzufügen
 /plugin marketplace add Klotzkette/claude-fuer-deutsches-recht
-/plugin install <plugin-name>@claude-fuer-deutsches-recht
+/plugin install <plugin-name>@klotzkette-german-legal-skills
 ```

-Alternativ: über die Claude-Desktop-GUI unter **Customize → Skills** → ZIP aus dem [aktuellen Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) hochladen. Schritt-für-Schritt unter [Schnellstart](#schnellstart) und [Für Einsteiger](#für-einsteiger-schritt-für-schritt-anleitung).
+Alternativ: über die Claude-Desktop-/Cowork-GUI unter **Customize → Skills / Plugins** → ZIP aus dem [aktuellen Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) hochladen. Schritt-für-Schritt unter [Schnellstart](#schnellstart), [Für Einsteiger](#für-einsteiger-schritt-für-schritt-anleitung) und besonders für Mac-Probleme in [INSTALLATION_EINFACH.md](./INSTALLATION_EINFACH.md).

 ## 🚨 KEINE Aussage über Berufsrecht, Datenschutz, KI-VO oder Beschlagnahmeverbote

@@ -299,7 +299,7 @@ Dieses Skill-Set lässt sich auf drei Wegen einbinden. Empfohlen ist **Weg 1**

 > 📆 **Release- vs. main-Stand.** Den **letzten Release-Tag** findest du auf der Seite [Releases](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest). Über **Weg 1 (Marketplace-Sync)** und **Weg 3 (Marketplace-Kommando)** wird der `main`-Branch geladen — das ist meist **neuer** als der letzte Release-Tag (Zwischen-Commits mit Fixes, neuen Tests, kleinen Ergänzungen). Über **Weg 2 (ZIP-Upload aus Release)** bekommst du den **getaggten, validierten Stand**. Für Stabilität → Weg 2; für neueste Korrekturen → Weg 1/3.

-> 💡 **Findest du in Cowork kein Feld für den GitHub-Pfad?** Dann ist in deiner Oberfläche der Marketplace-Weg vermutlich noch nicht freigeschaltet. Lade die Plugin-ZIPs einzeln aus dem [Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) herunter und installiere sie über denselben Dialog, mit dem du z. B. "Legal Plugin" installierst. Schritt für Schritt erklärt: **[INSTALLATION_EINFACH.md](./INSTALLATION_EINFACH.md)**.
+> 💡 **Findest du in Cowork kein Feld für den GitHub-Pfad oder macht der Mac beim ZIP-Upload Ärger?** Dann ist in deiner Oberfläche der Marketplace-Weg vermutlich noch nicht freigeschaltet oder macOS hat die ZIP anders behandelt als erwartet. Lade die Plugin-ZIPs einzeln aus dem [Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest) herunter und installiere sie über denselben Dialog, mit dem du z. B. "Legal Plugin" installierst. Mac-Hinweise zu Safari-Auto-Entpacken, iCloud-Platzhaltern, MegaZIP vs. Einzel-ZIP und Terminal-Check: **[INSTALLATION_EINFACH.md](./INSTALLATION_EINFACH.md)**.

 ### Voraussetzungen

@@ -323,7 +323,7 @@ Einfachster Weg in Claude Desktop oder der Cowork-Oberfläche:
 Wenn kein Marketplace-Manifest verwendet werden soll oder eine bestimmte Version festgehalten werden muss:

 1. Das gewünschte einzelne Plugin-ZIP aus dem neuesten Release herunterladen, z. B. `liquiditaetsplanung.zip` von https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest.
-2. In Cowork **Customize → Plugin** öffnen und über **+ → Create → Upload plugin** dieses einzelne Plugin-ZIP hochladen.
+2. In Cowork **Customize → Skills / Plugins** öffnen und über **+ → Create → Upload plugin** dieses einzelne Plugin-ZIP hochladen.
 3. Nach dem Upload erscheint das Plugin in der Plugin-Liste und kann aktiviert werden.

 **Wichtig:** Nicht das komplette Repository-ZIP aus **Code → Download ZIP** hochladen. Ein Upload-ZIP muss direkt `.claude-plugin/plugin.json`, `skills/`, `assets/` usw. im ZIP-Root enthalten.
@@ -334,14 +334,14 @@ Claude Code starten (`claude` im Terminal) und dann:

 ```text
 /plugin marketplace add Klotzkette/claude-fuer-deutsches-recht
-/plugin install arbeitsrecht
-/plugin install vertragsrecht
-/plugin install liquiditaetsplanung
-/plugin install insolvenzrecht
-/plugin install steuerrecht-anwalt-und-berater
+/plugin install arbeitsrecht@klotzkette-german-legal-skills
+/plugin install vertragsrecht@klotzkette-german-legal-skills
+/plugin install liquiditaetsplanung@klotzkette-german-legal-skills
+/plugin install insolvenzrecht@klotzkette-german-legal-skills
+/plugin install steuerrecht-anwalt-und-berater@klotzkette-german-legal-skills
 ```

-Einzelne Plugins lassen sich auch später mit `/plugin install <name>` nachinstallieren; `/plugin list` zeigt den aktuellen Stand.
+Einzelne Plugins lassen sich auch später mit `/plugin install <name>@klotzkette-german-legal-skills` nachinstallieren; `/plugin list` zeigt den aktuellen Stand.

 Alternativ ein lokal geklontes Repository nutzen:

@@ -355,9 +355,27 @@ Und dann im Claude-Code-Prompt:

 ```text
 /plugin marketplace add .
-/plugin install <plugin-name>
+/plugin install <plugin-name>@klotzkette-german-legal-skills
 ```

+### Mac-Hinweise für Cowork / Claude Desktop
+
+Wenn Nutzerinnen und Nutzer auf dem Mac scheitern, liegt es häufig an der heruntergeladenen Datei:
+
+- Safari kann ZIP-Dateien nach dem Download automatisch entpacken. Für Cowork muss aber die **einzelne Plugin-ZIP** hochgeladen werden, nicht der entpackte Ordner.
+- `alle-plugins-megazip.zip` ist nur ein Sammelarchiv. Es muss zuerst entpackt werden; anschließend die darin enthaltenen Plugin-ZIPs einzeln hochladen.
+- Nicht das GitHub-Repository-ZIP aus **Code → Download ZIP** verwenden. Das ist Quellcode, kein direkt installierbares Plugin-ZIP.
+- Bei iCloud-Desktop/Downloads die ZIP erst lokal vollständig laden. Im Zweifel nach `~/Downloads/claude-plugins/` verschieben und dann aus diesem lokalen Ordner auswählen.
+- Beim Cowork-Organisations-Upload müssen Plugin-ZIPs gültige ZIP-Dateien unter 50 MB sein; für alle 110 Plugins ist GitHub-Sync/Marketplace robuster als manueller Einzelupload.
+- Technischer Check im Terminal:
+
+```bash
+file ~/Downloads/claude-plugins/liquiditaetsplanung.zip
+unzip -l ~/Downloads/claude-plugins/liquiditaetsplanung.zip | head
+```
+
+Der ZIP-Root muss `.claude-plugin/plugin.json` und `skills/` enthalten. Wenn das Upload-Fenster stattdessen einen GitHub-Pfad verlangt, ist das der Marketplace-Dialog; für ZIPs zurückgehen und **Upload from .zip / Create → Upload plugin** wählen.
+
 ### Überprüfen, ob die Installation funktioniert hat

 - In Claude Desktop: in der Plugin-Liste muss neben dem Plugin **Manage** statt **Install** stehen.
@@ -434,7 +452,7 @@ Aktivierung in Cowork: `Customize → Skills → Persönliche Plugins → +` und

 1. **Einen Claude-Account** (kostenlos oder Pro) – Registrierung unter https://claude.ai
 2. **Claude Desktop** (empfohlen) oder **Claude Code** – Download: https://claude.com/download
-3. **Dieses Repository** – als ZIP herunterladen oder mit Git klonen
+3. **Für GUI-Installation:** ein einzelnes Plugin-ZIP aus dem [aktuellen Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest). **Für Entwickler:** dieses Repository mit Git klonen.

 ### Installation in Claude Desktop (für absolute Einsteiger)

@@ -444,11 +462,11 @@ Aktivierung in Cowork: `Customize → Skills → Persönliche Plugins → +` und
 2. Lade die Version für dein Betriebssystem herunter (Windows / Mac / Linux)
 3. Installiere die Anwendung und melde dich mit deinem Claude-Account an

-**Schritt 2: Repository herunterladen**
+**Schritt 2: Plugin-ZIP herunterladen**

-1. Klicke oben auf dieser GitHub-Seite auf den grünen Button "Code"
-2. Wähle "Download ZIP"
-3. Entpacke die ZIP-Datei an einem Ort deiner Wahl (z. B. `Dokumente/Claude-Skills`)
+1. Öffne den [aktuellen Release](https://github.com/Klotzkette/claude-fuer-deutsches-recht/releases/latest).
+2. Lade **ein einzelnes Plugin-ZIP** herunter, z. B. `arbeitsrecht.zip`, `vertragsrecht.zip` oder `liquiditaetsplanung.zip`.
+3. Auf dem Mac darauf achten: die ZIP nicht entpacken; falls Safari sie automatisch entpackt, erneut als ZIP laden oder die Safari-Auto-Entpackung deaktivieren.

 **Schritt 3: Skills in Claude Desktop aktivieren**

@@ -459,11 +477,11 @@ Aktivierung in Cowork: `Customize → Skills → Persönliche Plugins → +` und

 **Schritt 4: Einen Skill hochladen**

-1. In den Einstellungen: gehe zu **Skills**
-2. Klicke auf **Upload skill**
-3. Navigiere zum entpackten Ordner `claude-fuer-deutsches-recht`
-4. Wähle einen Skill-Ordner aus (z. B. `arbeitsrecht` oder `vertragsrecht`)
-5. Bestätige – fertig. Der Skill ist jetzt aktiv.
+1. In den Einstellungen: gehe zu **Skills / Plugins**.
+2. Öffne **Personal plugins / Persönliche Plugins**.
+3. Klicke auf **+** und wähle **Upload from .zip** bzw. **Create → Upload plugin**.
+4. Wähle das einzelne Plugin-ZIP aus, z. B. `arbeitsrecht.zip` oder `vertragsrecht.zip`.
+5. Bestätige und starte danach eine neue Konversation.

 **Schritt 5: Skill verwenden**

@@ -479,12 +497,12 @@ git clone https://github.com/Klotzkette/claude-fuer-deutsches-recht.git
 cd claude-fuer-deutsches-recht

 # Als Marketplace hinzufügen
-claude /plugin marketplace add .
+claude plugin marketplace add .

 # Skills installieren
-claude /plugin install arbeitsrecht
-claude /plugin install vertragsrecht
-claude /plugin install prozessrecht
+claude plugin install arbeitsrecht@klotzkette-german-legal-skills
+claude plugin install vertragsrecht@klotzkette-german-legal-skills
+claude plugin install prozessrecht@klotzkette-german-legal-skills
 ```

 ## FAQ für Einsteiger