121 lines
6.3 KiB
Markdown
121 lines
6.3 KiB
Markdown
# 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.
|
||
|
||
## 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)
|
||
├── CHANGELOG.md Pflicht – Versionen (nicht im ZIP)
|
||
├── extension/ optional – Claude-Desktop-Erweiterung (.mcpb)
|
||
│ ├── manifest.json
|
||
│ ├── icon.png optional
|
||
│ ├── 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
|
||
└── 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).
|
||
|
||
## Regeln
|
||
|
||
- **Name:** kebab-case, nur `a-z`, `0-9` und einzelne Bindestriche, höchstens 64 Zeichen, ohne „claude“ oder „anthropic“. Der Ordnername ist der Skill-Name.
|
||
- **Frontmatter:** `SKILL.md` beginnt mit
|
||
|
||
```yaml
|
||
---
|
||
name: <name>
|
||
description: "Wann dieser Skill verwendet werden soll – ein Satz."
|
||
---
|
||
```
|
||
|
||
`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.
|
||
- **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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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
|
||
|
||
## 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.
|
||
|
||
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. 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
|
||
```
|
||
|
||
```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`
|