92 lines
5.8 KiB
Markdown
92 lines
5.8 KiB
Markdown
# 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 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](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
|
||
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`
|