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 vom eigenen Rechner anlegen (siehe unten). Auf git.gundel.dev läuft kein Actions-Runner.

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

Vom eigenen Rechner

Auf git.gundel.dev ist kein Actions-Runner registriert. Das Release legt deshalb ein Skript auf dem Rechner an, der das ZIP schon gebaut hat. Es spricht die Gitea-API an (Release anlegen, Anhang hochladen):

• POST /api/v1/repos/dg/claude-skills/releases
• POST /api/v1/repos/dg/claude-skills/releases/{id}/assets

Dafür braucht es ein persönliches Zugangs-Token mit Schreibrecht auf dieses Repository (write:repository). Anlegen unter Profil → Einstellungen → Applications. Authentifizierung: Authorization: token …. Das Token nur in die Umgebung legen, nicht ins Repository.

Der Tag <name>/v<version> muss lokal existieren und schon auf dem Server liegen. Das Skript verschiebt keine Tags und pusht nichts.

$env:GITEA_TOKEN = '<Token>'
powershell -ExecutionPolicy Bypass -File scripts\release.ps1 -Name <name>

GITEA_TOKEN='<Token>' scripts/release.sh <name>

Manuell, ohne Token

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. Unter Releases ein neues Release anlegen.
3. Tag: <name>/v<version> (der Tag muss schon auf dem Server liegen). Titel: <name> <version>.
4. Als Text den Abschnitt dieser Version aus skills/<name>/CHANGELOG.md einfügen.
5. dist/<name>-v<version>.zip als Anhang hochladen.
6. Falls vorhanden: dist/<name>-v<version>.mcpb ebenfalls hochladen (oder scripts/release.ps1 nutzen – hängt beides an).

Nur die .mcpb nachträglich an ein bestehendes Release hängen (Token nur in der Umgebung):

$env:GITEA_TOKEN = '<Token>'
$id = <Release-ID>
$name = 'wordcraft-mcp-v0.2.0.mcpb'
$bytes = [IO.File]::ReadAllBytes("dist\$name")
$req = [Net.HttpWebRequest]::Create("https://git.gundel.dev/api/v1/repos/dg/claude-skills/releases/$id/assets?name=$name")
$req.Method = 'POST'
$req.Headers.Add('Authorization', "token $env:GITEA_TOKEN")
$req.ContentType = 'application/octet-stream'
$req.ContentLength = $bytes.LongLength
$s = $req.GetRequestStream(); $s.Write($bytes, 0, $bytes.Length); $s.Close()
$resp = $req.GetResponse(); (New-Object IO.StreamReader($resp.GetResponseStream())).ReadToEnd()

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