62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# Mitarbeiten
|
||
|
||
## Aufbau eines Skills
|
||
|
||
```
|
||
skills/<name>/
|
||
├── SKILL.md Pflicht – Anweisungen für Claude
|
||
├── CHANGELOG.md Pflicht – Versionen (wird nicht ins ZIP gepackt)
|
||
├── scripts/ optional – Hilfsskripte, die Claude ausführen kann
|
||
├── references/ optional – Nachschlagematerial, das Claude bei Bedarf liest
|
||
└── assets/ optional – Vorlagen, Bilder usw.
|
||
```
|
||
|
||
## 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.
|
||
- **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.
|
||
|
||
## Ablauf
|
||
|
||
1. Skill anlegen:
|
||
`scripts/new-skill.sh <name>` bzw. `scripts\new-skill.ps1 -Name <name>`
|
||
2. `SKILL.md` ausfüllen.
|
||
3. Prüfen:
|
||
`scripts/validate.sh <name>` bzw. `scripts\validate.ps1 -Name <name>`
|
||
4. Version im `CHANGELOG.md` des Skills erhöhen und Änderungen beschreiben.
|
||
5. Skill-Tabelle in der README aktualisieren:
|
||
`scripts/update-readme.sh` bzw. `scripts\update-readme.ps1`
|
||
6. Committen.
|
||
7. Tag setzen und pushen – das Release entsteht automatisch:
|
||
|
||
```sh
|
||
git tag <name>/v<version>
|
||
git push origin main <name>/v<version>
|
||
```
|
||
|
||
Die GitHub Action prüft, dass die Tag-Version zur obersten CHANGELOG-Version passt, baut das ZIP und hängt es an ein Release mit dem CHANGELOG-Abschnitt als Text.
|
||
|
||
## Versionen
|
||
|
||
- **Patch** (0.1.0 → 0.1.1): Korrekturen, Tippfehler, präzisere Formulierungen
|
||
- **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
|
||
|
||
## 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.
|
||
- `.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`
|