Was macht skillctl?
Operatives Playbook zur Verwaltung von Agent Skills mit der skillctl CLI. Führe echte Befehle aus; simuliere keine Ausgaben und kopiere SKILL.md-Dateien nicht manuell zwischen Agentenverzeichnissen.
Goldene Regeln
- Ein kanonischer Speicher — Skills befinden sich in
~/.skillctl/skills/<name>/; Agenten erhalten Symlinks viasync. - Manifest + Lock committen —
agent-skills.jsonundagent-skills.lockfür Team-Reproduzierbarkeit in Git verfolgen. - Nur portable Spezifikationen verwenden —
file:./<pfad>,local:imported/<name>,github:,npm:oderskills.sh/; niemals absolute Home-Verzeichnis-Pfade committen. - Installieren vor Synchronisieren —
installmaterialisiert den Speicher;syncverlinkt nur die Agenten neu. - Nach Änderungen überprüfen —
skillctl doctor(undskillctl auditin CI) ausführen. - Import vor manuellem Kopieren bevorzugen —
import from-projectoderimport from-npxstatt Skill-Ordner zu duplizieren.
Entscheidungsbaum
| Situation | Befehl |
|---|---|
| Neues Projekt, kein Manifest | skillctl init oder skillctl init --with-skill |
| Remote- oder lokalen Skill hinzufügen | skillctl add <spezifikator> dann skillctl install |
Skills bereits in .claude/skills, .codex/skills, etc. | skillctl import from-project |
Migration von npx skills | skillctl import from-npx |
| Nur neu verlinken (Lock unverändert) | skillctl sync |
| Vom entfernten Quellort neu holen | skillctl update oder skillctl update <name> |
| CI-reproduzierbare Installation | skillctl install --frozen dann skillctl audit --strict |
| Nicht-portable Pfade im Lock | skillctl install zum Umschreiben; skillctl doctor-Warnungen prüfen |
Schnellrezepte
# Bootstrap
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# Projektlokaler Skill
skillctl add file:./my-skill
skillctl install
skillctl sync
# Vorhandene Agentenverzeichnisse importieren
skillctl import from-project --dry-run
skillctl import from-project
# Prüfen
skillctl list
skillctl doctor
skillctl audit --json
Erwartet nach add file:./my-skill + install: Manifest-Spezifikator file:./my-skill, Lock-canonicalPath wie ~/.skillctl/skills/my-skill.
Portabilität (0.3.1+)
- Portabel:
file:./rel,local:imported/<name>, entfernte Spezifikatoren,canonicalPath: ~/.skillctl/skills/<name>. - Nicht portabel: absolutes
file:/Users/...,local:/abs/pfad, absolutescanonicalPathvon einem anderen Rechner. - Wenn
doctorvor nicht-portablen Pfaden warnt,skillctl installausführen, um das Lock aus dem Manifest neu zu schreiben.
Fehlermodi
| Symptom | Aktion |
|---|---|
canonical path missing | skillctl install |
| Integritätskonflikt | skillctl update <name> oder skillctl install |
| Symlink schlägt fehl (Windows) | doctor-Notiz; Konfiguration defaultMode: copy |
| Keine Agenten verlinkt | skillctl sync; Agenten in ~/.skillctl/config.json aktivieren |
Frozen install failed | Speicher nicht synchron; install ohne --frozen ausführen |
Referenzen
- commands.md — vollständige Befehlsübersicht
- specifiers.md — Spezifikator-Grammatik
- manifest-lock.md — Manifest- und Lock-Semantik
- workflows.md — Team-Onboarding, Migration, CI
- troubleshooting.md — doctor, Windows, Koexistenz