# Mitarbeiten

Einen Skill ohne Git installieren: ZIP aus der Tabelle in der [README](README.md) 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](templates/skill/README.md). Skills mit `extension/` beschreiben die Claude-Installation über `.mcpb` + ZIP ([docs/INSTALLATION.md](docs/INSTALLATION.md)) und verweisen für Cursor auf die Wurzel-README / [docs/CURSOR.md](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

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

## Cursor

Jedes Skill mit `extension/` bekommt beim Build **automatisch ein eigenes Cursor-Plugin** (`dist/<name>-cursor-v<ver>.zip`) und eine Tabellenzeile 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](docs/CURSOR.md)); dieselbe Option steht deshalb auch im Plugin.
- **FigCraft:** kein `--attach`. Mit Lese- und Schreib-Ordner ist die Anbindung an eine laufende App nicht erlaubt.
- **VectorCraft:** ohne Ordner-Argumente versucht der Server zuerst `127.0.0.1:7979`. Mit Lese- und Schreib-Ordner läuft er ohne Fenster. Die Cursor-Übersetzung muss diese Argumente übernehmen.
- **SolidCraft:** eigener Installer, nicht der ArtCraft-Launcher. Zwei `--allow-path` (Lese- und Schreib-Ordner), der Server läuft ohne Fenster. Kein `--connect`, kein `--allow-any-path`.
- **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
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`