JMBargueno/skanvil

Was macht skanvil?

Ziel

Ändere Skill-Bibliotheken über die skanvil CLI, sodass Skill-Ordner, das SKILL.md Frontmatter, der README-Index und die Bibliothekskonventionen konsistent bleiben und die Validierung grün bleibt.

Wann dieses Skill aktiviert werden soll

• Das Repository enthält eine .skanvilrc.json, einen skills/-Ordner mit SKILL.md-Dateien oder skanvil in seiner package.json.
• Der Benutzer bittet um das Hinzufügen, Schreiben, Umbenennen, Verschieben, Neubenennen, Neubeschreiben, Löschen, Auflisten, Validieren oder Indizieren von Skills.
• skanvil validate, npm test oder CI schlägt mit skanvil-Diagnose fehl.
• Der Benutzer möchte, dass die Skills einer Bibliothek für Claude Code, GitHub Copilot oder Codex in einem anderen Projekt verfügbar sind.

Anleitung

1. Orientieren

1. Lies .skanvilrc.json. Es definiert die Kategorien (id, Ordner-prefix, README-title, aliases), die erforderlichen Abschnitte, Platzhalter und Regel-Schweregrade. Fehlt die Datei, gilt das Standard-Preset: front-, back-, prefixloses transversal (Standard) und _internal.
2. Führe npx skanvil list --json aus, um jeden Skill mit seiner Kategorie, README-Präsenz und Gültigkeit zu sehen.
3. Führe vor jeder Änderung npx skanvil validate --json aus, damit du weißt, welche Probleme bereits bestanden.

2. Goldene Regeln

• Benenne, verschiebe oder lösche Skill-Ordner niemals von Hand und bearbeite den README-Index niemals manuell. Verwende skanvil edit, das den Ordner, den Frontmatter-name, die # Überschrift und den README-Eintrag synchron hält und bei Fehlern rückgängig macht.
• Erstelle Skill-Ordner niemals von Hand. Verwende skanvil add, das das Kategorie-Präfix, die Vorlage, die Frontmatter-Metadaten und den README-Eintrag anwendet.
• Übergebe in nicht-interaktiven Shells immer alle Optionen. add benötigt --type, --name und --description. edit --remove benötigt --yes. Andernfalls fragt der Befehl nach oder schlägt ohne TTY fehl.
• Führe skanvil niemals ohne Argumente oder skanvil wizard aus. Diese öffnen ein interaktives Menü für Menschen. Verwende die expliziten Befehle unten. Wenn der Benutzer Menüs bevorzugt, schlage vor, dass er npx skanvil selbst ausführt.
• Füge --json hinzu, wann immer du die Ausgabe parsen musst. Daten gehen nach stdout; Warnungen und Fehler nach stderr.
• Führe nach jeder Änderung npx skanvil validate aus und beende ohne Fehler. Exit-Code 1 bedeutet Fehler oder Warnungen, wenn --strict verwendet wird.
• Stelle jedem Befehl npx voran, es sei denn, skanvil ist im PATH. Verwende -C <Pfad>, um eine Bibliothek in einem anderen Ordner anzusprechen.

3. Häufige Aufgaben

Einen Skill erstellen und dann seinen Inhalt schreiben.

npx skanvil add --type <Kategorie> --name "<Kurzname>" \
  --description "<Was er tut>. Verwende ihn, wenn <Auslösesituationen>."

Bearbeite dann skills/<Präfix><Name>/SKILL.md:

• Fülle jeden erforderlichen Abschnitt mit konkretem, handlungsorientiertem Inhalt.
• Ersetze alle generischen Vorlagensätze. Solange du das nicht tust, meldet validate eine template-unchanged-Warnung und validate --strict (der npm test der Bibliothek) schlägt fehl.
• Verschiebe langes Material in references/ und verlinke nur auf Dateien, die existieren (broken-references).

Verwende --no-scripts, --no-assets oder --no-references, wenn diese Ordner leer bleiben würden. Verwende --template <Name> für eine benutzerdefinierte Vorlage in .skanvil/templates/.

Einen Skill umbenennen oder verschieben.

npx skanvil edit <Skill> --rename <neuer-Name>          # Präfix wird automatisch neu angewendet
npx skanvil edit <Skill> --type <andere-Kategorie>      # neues Präfix, README-Abschnitt, Metadaten
npx skanvil edit <Skill> --title "<Titel>" --description "<Text>"

--rename erwartet den Basisnamen: edit front-a --rename b ergibt front-b.

Einen Skill löschen. Bestätige zuerst mit dem Benutzer; dies ist endgültig.

npx skanvil edit <Skill> --remove --yes

Validierungsfehler beheben.

1. Führe npx skanvil doctor --fix aus. Es repariert README-Einträge, name-Konflikte, Tabs im Frontmatter und wandelt tools in allowed-tools um.
2. Behebe, was übrig bleibt, indem du SKILL.md bearbeitest. Verwende die Diagnosetabelle unten.
3. Führe erneut npx skanvil validate aus.

Den README-Index neu erstellen nach Änderungen an Kategorietiteln in .skanvilrc.json:

npx skanvil index          # schreibt die Index-Abschnitte neu
npx skanvil index --check  # nur überprüfen (CI)

Die Skills in ein Projekt installieren.

npx skanvil sync <Projektverzeichnis> -C <Bibliotheksverzeichnis> --target claude,copilot --dry-run   # Vorschau
npx skanvil sync <Projektverzeichnis> -C <Bibliotheksverzeichnis> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # installiertes Paket

Ziele:

• claude installiert in .claude/skills;
• copilot installiert in .github/skills;
• agents und codex installieren in .agents/skills.
• Ein benutzerdefinierter Pfad muss ein Ordner innerhalb des Projekts sein.
• --global (ohne Projektverzeichnis) installiert stattdessen in ~/.claude/skills, ~/.copilot/skills oder ~/.agents/skills des Benutzers. Verwende dies nur, wenn der Benutzer Skills wünscht, die in jedem Projekt verfügbar sind.

Wie sync funktioniert:

• Es überschreibt niemals Ordner, die es nicht installiert hat.
• Es entfernt Skills, die aus der Bibliothek gelöscht wurden.
• Es überspringt Skills mit Validierungsfehlern, es sei denn, --force wird angegeben.
• Es veröffentlicht niemals _internal-Skills.

Kategorien hinzufügen oder ändern. Bearbeite categories in .skanvilrc.json:

• genau eine Kategorie hat "default": true und kein Präfix;
• jede andere Kategorie hat ein Präfix, das _ oder kebab-case ist und auf - endet;
• kein Präfix darf mit einem anderen Präfix beginnen.

Verschiebe dann vorhandene Skills mit edit --type und führe skanvil index aus.

4. Guten Skill-Inhalt schreiben

• description sagt, was der Skill tut und wann er verwendet werden soll, mit den Auslöseschlüsselwörtern, die ein Agent sehen würde. Er darf maximal 1024 Zeichen lang sein.
• name entspricht dem Ordnernamen: Kleinbuchstaben, Ziffern und einzelne Bindestriche, maximal 64 Zeichen.
• Textkörper: halte SKILL.md unter 500 Zeilen. Schreibe Anweisungen als nummerierte, überprüfbare Schritte und platziere Beispiele, Randfälle und lange Checklisten in references/ (eine Ebene tief).
• Platzhalter: hinterlasse niemals Fülltext. Jeder Eintrag von validation.placeholders (To-do-Markierungen, Platzhalter-Latein-Text, „noch zu entscheiden“-Notizen) schlägt bei der Validierung fehl.
• metadata: nur Zeichenfolgenwerte, also setze Zahlen in Anführungszeichen, wie in version: "1.0".
• allowed-tools: eine durch Leerzeichen getrennte Zeichenfolge, keine Liste.

5. Diagnose → Fehlerbehebung

Regel	Fehlerbehebung
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix, oder edit --rename, wenn der Ordnername falsch ist
frontmatter-tabs, tools-field	doctor --fix
frontmatter	Repariere das YAML zwischen den ----Zeilen (setze Werte in Anführungszeichen, die : oder # enthalten).
required-sections	Füge den fehlenden ## Abschnitt hinzu, der in validation.requiredSections aufgeführt ist.
placeholders	Ersetze den Platzhaltertext durch echten Inhalt.
description-length, max-lines	Kürze; verschiebe Details nach references/.
metadata-format	Setze Nicht-Zeichenfolgen-Werte in Anführungszeichen.
duplicate-name	Zwei Ordner teilen sich einen name: benenne einen mit edit --rename um.
broken-references	Erstelle die referenzierte Datei oder korrigiere den Link (Pfade sind relativ zum Skill).
template-unchanged	Schreibe die generischen Gerüstsätze durch Skillspezifische Anweisungen um.

Siehe references/REFERENCE.md für alle Befehlsoptionen, das Konfigurationsschema und JSON-Ausgabeformate.

Ausgabeformat

Melde dem Benutzer:

• die von dir ausgeführten skanvil-Befehle;
• die erstellten, geänderten oder entfernten Skills mit ihren Ordnernamen;
• das endgültige skanvil validate-Ergebnis (Fehler und Warnungen) und alles, was er selbst entscheiden muss.

Qualitätskriterien

• Jede strukturelle Änderung erfolgte über skanvil add oder skanvil edit. Es gibt keine manuellen Ordnerumbenennungen oder README-Index-Bearbeitungen.
• npx skanvil validate meldet keine Fehler und npx skanvil index --check ist erfolgreich.
• Neue oder bearbeitete Skills haben spezifische Beschreibungen mit Auslösern und keine Vorlagenfüller oder Platzhalter.
• Löschungen und Synchronisationen in andere Projekte wurden mit dem Benutzer bestätigt.