claude-skills/CONTRIBUTING.md

Mitarbeiten

Einen Skill ohne Git installieren: ZIP aus der Tabelle in der README 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: 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.

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

  ---
  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.

   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).

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 -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 -ExecutionPolicy Bypass -File scripts\release.ps1 -Name <name>

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