dg/claude-skills
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 20 Wiki Activity

Release wordcraft-mcp and gridcraft-mcp 0.3.0: client-neutral skills, Cursor plugins.

Browse Source
This commit is contained in:
Dominic Gundel committed 2026-10-19 23:27:06 +02:00
1 parent debdf92877
commit 4c7e3ff720
26 files changed
+1008 -236
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CONTRIBUTING.md
+29 -69
View File
@@ -1,13 +1,13 @@
# Mitarbeiten
Einen Skill ohne Git installieren: ZIP aus der Tabelle in der [README](README.md) laden und in Claude hochladen. Dieser Text ist für alle, die einen Skill anlegen oder aktualisieren.
Einen Skill ohne Git installieren: ZIP aus der Tabelle in der [README](README.md) laden und in Claude hochladen; für Cursor das Cursor-Plugin-ZIP. Dieser Text ist für alle, die einen Skill anlegen oder aktualisieren.
## Aufbau eines Skills
```
skills/<name>/
├── SKILL.md Pflicht – Anweisungen für Claude (liegt im ZIP)
├── README.md Pflicht – Doku für Menschen (nicht im ZIP)
├── SKILL.md Pflicht – Anweisungen für den Agenten (liegt im ZIP; clientneutral)
├── README.md Pflicht – Doku für Menschen (nicht im ZIP; Client-Details hier)
├── CHANGELOG.md Pflicht – Versionen (nicht im ZIP)
├── extension/ optional – Claude-Desktop-Erweiterung (.mcpb)
│ ├── manifest.json
@@ -15,12 +15,14 @@ skills/<name>/
│ ├── upstream.json von scripts/fetch-cli geschrieben
│ ├── LICENSES/ Upstream-Lizenztexte
│ └── server/ CLI-exe nur beim Bauen (nicht committen)
├── scripts/ optional – Hilfsskripte, die Claude ausführen kann
├── references/ optional – Nachschlagematerial, das Claude bei Bedarf liest
├── scripts/ optional – Hilfsskripte, die der Agent ausführen kann
├── references/ optional – Nachschlagematerial
└── assets/ optional – Vorlagen, Bilder usw.
```
`README.md` hat dieselben Abschnitte wie [templates/skill/README.md](templates/skill/README.md): Zweck, Voraussetzungen, Installation, Einrichtung, Stolpersteine, Test, Deinstallation/Update, Link zum Changelog. Skills mit `extension/` beschreiben die Installation über `.mcpb` + ZIP und verweisen auf [docs/INSTALLATION.md](docs/INSTALLATION.md).
**Grundsatz:** `SKILL.md` enthält keine clientspezifischen Anweisungen (kein Claude Desktop, Cursor, Store-Pfad, Erweiterungs-UI, ToolSearch-Details). Solche Hinweise gehören in die Skill-README oder `docs/`. So nutzen Claude und Cursor dieselbe `SKILL.md`.
`README.md` hat dieselben Abschnitte wie [templates/skill/README.md](templates/skill/README.md). Skills mit `extension/` beschreiben die Claude-Installation über `.mcpb` + ZIP ([docs/INSTALLATION.md](docs/INSTALLATION.md)) und verweisen für Cursor auf die Wurzel-README / [docs/CURSOR.md](docs/CURSOR.md). Sinnvolle Abschnitte in der SKILL.md: Rezepte, Abschlussprüfung, Datenschutz (Ampel), wenn der Skill MCP-Werkzeuge steuert.
## Regeln
@@ -30,91 +32,49 @@ skills/<name>/
```yaml
---
name: <name>
description: "Wann dieser Skill verwendet werden soll – ein Satz."
description: "Wann dieser Skill verwendet werden soll – Auslöser und Abgrenzung."
---
```
`name` muss dem Ordnernamen entsprechen. `description` ist Pflicht, höchstens 1024 Zeichen, ohne spitze Klammern. Sie entscheidet, wann Claude den Skill benutzt – also beschreiben, *wann* er gebraucht wird, nicht nur *was* er ist. Enthält sie „: “, in Anführungszeichen setzen. Dieselbe `description` erscheint als Kurzbeschreibung in der Tabelle der Wurzel-README.
`name` muss dem Ordnernamen entsprechen. `description` ist Pflicht, höchstens 1024 Zeichen, ohne spitze Klammern. Keine clientspezifischen Zusatzfelder. Dieselbe `description` erscheint in der Tabelle der Wurzel-README.
- **Kodierung:** UTF-8 ohne BOM, Zeilenenden LF (regelt `.gitattributes`).
- **CHANGELOG.md:** Einträge als `## x.y.z (YYYY-MM-DD)`, neuester oben. Der oberste Eintrag ist die aktuelle Version.
- **CHANGELOG.md:** Einträge als `## x.y.z (YYYY-MM-DD)`, neuester oben.
## Cursor
Jedes Skill mit `extension/` bekommt beim Build **automatisch ein eigenes Cursor-Plugin** (`dist/<name>-cursor-v<ver>.zip`) und eine Tabellenzeile inkl. 1-Klick-Deeplink. 1:1 zur Claude-Seite: eine `.mcpb` ↔ ein Cursor-Plugin. **Keine Sammel-Plugins.** Build: `scripts/build-cursor` (von `package-all` aufgerufen). Nur `cursor/plugin-template/` liegt im Git; Ausgaben unter `dist/cursor/`.
## Neuer Skill
1. Ordner aus der Vorlage anlegen:
`scripts/new-skill.sh <name>` bzw. `scripts\new-skill.ps1 -Name <name>`
2. `SKILL.md` und `README.md` ausfüllen.
3. Prüfen:
`scripts/validate.sh <name>` bzw. `scripts\validate.ps1 -Name <name>`
4. Tabelle in der Wurzel-README neu erzeugen:
`scripts/update-index.sh` bzw. `scripts\update-index.ps1`
5. Committen und nach `main` pushen.
6. Tag setzen und pushen. Bestehende Tags nicht verschieben und nicht löschen. Der Push allein legt kein Release an.
```sh
git tag <name>/v<version>
git push origin main <name>/v<version>
```
7. Release anlegen (siehe unten): Pakete bauen und dem Tag als Anhänge hinzufügen.
1. `scripts/new-skill.sh <name>` bzw. `scripts\new-skill.ps1 -Name <name>`
2. `SKILL.md` und `README.md` ausfüllen (SKILL clientneutral).
3. `scripts/validate` und `scripts/update-index`
4. Committen, Taggen, Release (ZIP, ggf. `.mcpb`, Cursor-ZIP).
## Update eines Skills
1. `SKILL.md` und `README.md` ändern.
2. Im `CHANGELOG.md` einen neuen Eintrag `## x.y.z (YYYY-MM-DD)` oben einfügen.
3. Prüfen (`validate`), dann `update-index` ausführen.
4. Committen und nach `main` pushen.
5. Neuen Tag `<name>/v<version>` setzen und pushen. Der Tag muss exakt zur obersten CHANGELOG-Version passen. Danach das Release vom eigenen Rechner anlegen.
1. `SKILL.md` / `README.md` / ggf. `extension/` ändern.
2. CHANGELOG-Eintrag oben.
3. `validate`, `update-index`, committen, neuen Tag, Release.
## Versionen
- **Patch** (0.1.0 → 0.1.1): Korrekturen, Tippfehler, präzisere Formulierungen, Doku
- **Minor** (0.1.0 → 0.2.0): neue Abschnitte, neue bekannte Fallen, neue Beispiele
- **Major** (0.x → 1.0.0): geänderte Voraussetzungen oder Arbeitsweise, die bestehende Einrichtungen betreffen
- **Patch:** Korrekturen, Doku
- **Minor:** neue Abschnitte, Fallen, Beispiele, Cursor-/Claude-Auslieferung
- **Major:** geänderte Voraussetzungen oder Arbeitsweise
## Release
Ein Paket pro Skill, Dateiname `dist/<name>-v<version>.zip`. Im ZIP liegt der Ordner `<name>/` mit `SKILL.md` auf oberster Ebene. `README.md` und `CHANGELOG.md` werden nicht eingepackt.
Pakete: `dist/<name>-v<version>.zip` (nur SKILL.md), ggf. `dist/<name>-v<version>.mcpb`, `dist/<name>-cursor-v<version>.zip`.
Skills mit `extension/` liefern zusätzlich `dist/<name>-v<version>.mcpb`. Die `.mcpb` enthält **keine** CLI-EXE: sie zeigt auf die Installation aus dem ArtCraft-Launcher (`C:\Program Files\…`). `scripts/fetch-cli` prüft nur, dass die EXE lokal vorhanden ist, und aktualisiert `upstream.json` sowie die Lizenztexte. Als `entry_point` dient `server/README.txt`: die MCPB-Prüfung verlangt eine Datei im Paket; gestartet wird der Befehl aus `mcp_config.command`. `mcpb validate` besteht damit, und die Erweiterung startet so. Die `.mcpb` bleibt unsigniert, solange kein Code-Signing-Zertifikat vorliegt (`mcpb sign` braucht `--cert` / `--key`; `--self-signed` hilft nicht gegen Defender).
```sh
scripts/package.sh # nur Skill-ZIPs
scripts/package.sh <name>
scripts/package-mcpb.sh <name> # eine .mcpb
scripts/package-all.sh # ZIP + .mcpb wo extension/ existiert
```
Die `.mcpb` enthält **keine** CLI-EXE: sie zeigt auf den ArtCraft-Launcher (`C:\Program Files\…`). Als `entry_point` dient `server/README.txt` (MCPB-Prüfung verlangt eine Datei im Paket; gestartet wird `mcp_config.command`).
```powershell
powershell -ExecutionPolicy Bypass -File scripts\package.ps1
powershell -ExecutionPolicy Bypass -File scripts\package.ps1 -Name <name>
powershell -ExecutionPolicy Bypass -File scripts\package-mcpb.ps1 -Name <name>
powershell -ExecutionPolicy Bypass -File scripts\package-all.ps1
```
### Release veröffentlichen
Der Tag `<name>/v<version>` muss lokal und remote existieren. Danach entweder:
**Skript** (baut ZIP/`.mcpb` und hängt sie ans Release; nutzt dieselbe Anmeldung wie `git push`):
```powershell
powershell -ExecutionPolicy Bypass -File scripts\release.ps1 -Name <name>
```
```sh
scripts/release.sh <name>
```
**Oder manuell** in der Release-Oberfläche des Remotes:
1. Paket bauen (Befehle oben). Prüfen, dass `dist/<name>-v<version>.zip` die Einträge `<name>/` und `<name>/SKILL.md` enthält und weder `README.md` noch `CHANGELOG.md`.
2. Neues Release zum Tag `<name>/v<version>` anlegen, Titel `<name> <version>`.
3. Als Text den Abschnitt dieser Version aus `skills/<name>/CHANGELOG.md` einfügen.
4. `dist/<name>-v<version>.zip` und – falls vorhanden – `dist/<name>-v<version>.mcpb` anhängen.
## Hinweise zu den Skripten
- Für jedes Skript gibt es eine Bash- (`.sh`) und eine PowerShell-Variante (`.ps1`). Die Bash-Skripte brauchen `zip` und `unzip`, die PowerShell-Skripte laufen ohne Zusatztools unter Windows PowerShell 5.1 und PowerShell 7. `release.sh` braucht zusätzlich `curl` und `python3`; unter Windows genügt `release.ps1`.
- `.ps1`-Dateien enthalten nur ASCII-Zeichen. Windows PowerShell 5.1 liest UTF-8 ohne BOM als ANSI; Umlaute oder Gedankenstriche können ein Skript dort unbrauchbar machen.
- `package.ps1` baut ZIPs mit `System.IO.Compression` statt `Compress-Archive`, weil `Compress-Archive` unter 5.1 Pfade mit `\` schreibt.
- Unter Windows bei gesperrter Ausführungsrichtlinie: `powershell -ExecutionPolicy Bypass -File scripts\<skript>.ps1`
- Bash- und PowerShell-Varianten; `.ps1` nur ASCII; Dateien über `lib.ps1` als UTF-8 ohne BOM.
- Unter Windows: `powershell -ExecutionPolicy Bypass -File scripts\<skript>.ps1`