Mitarbeiten

Kollegen installieren einen Skill ohne Git: 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)
├── 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.

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

Ordner aus der Vorlage anlegen: scripts/new-skill.sh <name> bzw. scripts\new-skill.ps1 -Name <name>
SKILL.md und README.md ausfüllen.
Prüfen: scripts/validate.sh <name> bzw. scripts\validate.ps1 -Name <name>
Tabelle in der Wurzel-README neu erzeugen: scripts/update-index.sh bzw. scripts\update-index.ps1
Committen und nach main pushen.
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>
```
Release vom eigenen Rechner anlegen (siehe unten). Auf git.gundel.dev läuft kein Actions-Runner.

Update eines Skills

SKILL.md und README.md ändern.
Im CHANGELOG.md einen neuen Eintrag ## x.y.z (YYYY-MM-DD) oben einfügen.
Prüfen (validate), dann update-index ausführen.
Committen und nach main pushen.
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.

scripts/package.sh              # alle Skills
scripts/package.sh <name>

powershell -ExecutionPolicy Bypass -File scripts\package.ps1
powershell -ExecutionPolicy Bypass -File scripts\package.ps1 -Name <name>

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

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.
Unter Releases ein neues Release anlegen.
Tag: <name>/v<version> (der Tag muss schon auf dem Server liegen). Titel: <name> <version>.
Als Text den Abschnitt dieser Version aus skills/<name>/CHANGELOG.md einfügen.
dist/<name>-v<version>.zip als Anhang hochladen.

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

6.0 KiB Raw Blame History Unescape Escape