claude-skills/CONTRIBUTING.md

Mitarbeiten

Einen Skill ohne Git installieren: ZIP aus der Tabelle in der README laden und in Claude hochladen; für Cursor das Cursor-Plugin-ZIP. Dieser Text ist für alle, die einen Skill anlegen oder aktualisieren.

Aufbau eines Skills

skills/<name>/
├── SKILL.md        Pflicht – Anweisungen für den Agenten (liegt im ZIP; clientneutral)
├── README.md       Pflicht – Doku für Menschen (nicht im ZIP; Client-Details hier)
├── 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 der Agent ausführen kann
├── references/     optional – Nachschlagematerial
└── assets/         optional – Vorlagen, Bilder usw.

Grundsatz: SKILL.md enthält keine clientspezifischen Anweisungen (kein Claude Desktop, Cursor, Store-Pfad, Erweiterungs-UI, ToolSearch-Details). Solche Hinweise gehören in die Skill-README oder docs/. So nutzen Claude und Cursor dieselbe SKILL.md.

README.md hat dieselben Abschnitte wie templates/skill/README.md. Skills mit extension/ beschreiben die Claude-Installation über .mcpb + ZIP (docs/INSTALLATION.md) und verweisen für Cursor auf die Wurzel-README / docs/CURSOR.md. Sinnvolle Abschnitte in der SKILL.md: Rezepte, Abschlussprüfung, Datenschutz (Ampel), wenn der Skill MCP-Werkzeuge steuert.

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 – Auslöser und Abgrenzung."
  ---
  

  name muss dem Ordnernamen entsprechen. description ist Pflicht, höchstens 1024 Zeichen, ohne spitze Klammern. Keine clientspezifischen Zusatzfelder. Dieselbe description erscheint in der Wurzel-README: der Text vor „Verwenden“ als Kurztext, der Rest kursiv darunter.

• Kodierung: UTF-8 ohne BOM, Zeilenenden LF (regelt .gitattributes).

• CHANGELOG.md: Einträge als ## x.y.z (YYYY-MM-DD), neuester oben.

Cursor

Jedes Skill mit extension/ bekommt beim Build automatisch ein eigenes Cursor-Plugin (dist/<name>-cursor-v<ver>.zip) und einen Eintrag in der Wurzel-README inkl. 1-Klick-Deeplink. 1:1 zur Claude-Seite: eine .mcpb ↔ ein Cursor-Plugin. Keine Sammel-Plugins. Build: scripts/build-cursor (von package-all aufgerufen). Nur cursor/plugin-template/ liegt im Git; Ausgaben unter dist/cursor/.

Besonderheiten einzelner Server

• PdfCraft startet mit --compact. Ohne die Option sind es 171 Werkzeuge mit etwa 176 KB Beschreibung. Cursor begrenzt die aktiven Werkzeuge (siehe docs/CURSOR.md); dieselbe Option steht deshalb auch im Plugin.
• FigCraft: mcp --attach PORT hängt an der laufenden App (figcraft --control PORT) und lehnt die Ordner-Flags ab. Die Erweiterung setzt die Ordner und damit kein --attach.
• VectorCraft: ohne Ordner-Argumente versucht der Server zuerst 127.0.0.1:7979 und fällt sonst auf kopflos zurück. Mit Lese- und Schreib-Ordner läuft er kopflos. Die Cursor-Übersetzung muss diese Argumente übernehmen.
• SolidCraft: eigener Installer, nicht der ArtCraft-Launcher. Zwei --allow-path, kein --allow-any-path. Die Erweiterung startet ohne --connect (kopflos). --connect 127.0.0.1:PORT steuert die App (solidcraft --control PORT); ohne lauschende App scheitern die Entwurfswerkzeuge. solvecraft-cli.exe ist nur ein Alias.
• CADCraft: mcp kopflos. Optional mcp --connect HOST:PORT (--lazy, --launch). Keine Ordner-Flags.
• EffectCraft: mcp --empty mit Lese- und Schreib-Ordner. --autosave und --bridge PORT schließen sich aus.
• FilmCraft: mcp kopflos, keine Ordner-Flags. An die App: --bridge 127.0.0.1:PORT vor dem Unterbefehl mcp.
• Schreib-Ordner im Lese-Ordner (Standard: Dokumente und Dokumente/Claude). PdfCraft und VectorCraft öffnen eigene Ergebnisse sonst nicht wieder. Bei FigCraft ist die Lage egal; der Standard bleibt derselbe.

Neuer Skill

1. scripts/new-skill.sh <name> bzw. scripts\new-skill.ps1 -Name <name>
2. SKILL.md und README.md ausfüllen (SKILL clientneutral).
3. scripts/validate und scripts/update-index
4. Committen, Taggen, Release (ZIP, ggf. .mcpb, Cursor-ZIP).

Update eines Skills

1. SKILL.md / README.md / ggf. extension/ ändern.
2. CHANGELOG-Eintrag oben.
3. validate, update-index, committen, neuen Tag, Release.

Versionen

• Patch: Korrekturen, Doku
• Minor: neue Abschnitte, Fallen, Beispiele, Cursor-/Claude-Auslieferung
• Major: geänderte Voraussetzungen oder Arbeitsweise

Release

Pakete: dist/<name>-v<version>.zip (nur SKILL.md), ggf. dist/<name>-v<version>.mcpb, dist/<name>-cursor-v<version>.zip.

Die .mcpb enthält keine CLI-EXE: sie zeigt auf den ArtCraft-Launcher (C:\Program Files\…). Als entry_point dient server/README.txt (MCPB-Prüfung verlangt eine Datei im Paket; gestartet wird mcp_config.command).

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

Hinweise zu den Skripten

• Bash- und PowerShell-Varianten; .ps1 nur ASCII; Dateien über lib.ps1 als UTF-8 ohne BOM.
• Unter Windows: powershell -ExecutionPolicy Bypass -File scripts\<skript>.ps1