SkillDo CLI

Was macht SkillDo CLI?

Skilldo ist eine 7-stufige LLM-Pipeline, die SKILL.md-Dateien für Softwarebibliotheken generiert: extrahieren → mappen → lernen → fakten → erstellen → überprüfen → testen

Die Stufen 1-3 sammeln Bibliotheks-Metadaten (Quelldateien, Dokumentation, Abhängigkeiten, Version). Stufe 4 (Fakten) extrahiert eine kompakte Wahrheitstabelle mit negativen Aussagen aus den Stufen 1-3. Stufe 5 generiert die SKILL.md. Stufe 6 überprüft auf Genauigkeit/Sicherheit. Stufe 7 validiert mit generiertem Testcode.

Installation

# Homebrew
brew install skilldoai/tap/skilldo

# Aus dem Quellcode
cargo install --path .

Schnellstart

# Generiert eine SKILL.md für das aktuelle Repository
skilldo generate

# Generiert für einen bestimmten Repository-Pfad
skilldo generate /pfad/zu/bibliothek

# Sprache explizit angeben
skilldo generate --language python

# Eine bestimmte Konfiguration verwenden
skilldo generate --config skilldo.toml

Konfiguration (skilldo.toml)

Skilldo verwendet TOML-Konfigurationsdateien. Platzieren Sie skilldo.toml im Repository-Stammverzeichnis oder verwenden Sie --config.

Minimale Konfiguration (ein Anbieter)

[llm]
provider_type = "anthropic"          # anthropic, openai, gemini, openai-compatible, chatgpt
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"  # Name der Umgebungsvariable, die den Schlüssel enthält

[generation]
max_retries = 10                # Wiederholungen bei Lint-/Testfehlern
# telemetry = true              # Opt-in: Loggt Läufe in ~/.skilldo/runs.csv

Überschreibungen pro Stufe (Modelle)

Verschiedene Modelle können für Überprüfungs- und Teststufen verwendet werden:

[llm]
provider_type = "anthropic"
model = "claude-sonnet-4-6"
api_key_env = "ANTHROPIC_API_KEY"

[generation]
enable_test = true
enable_review = true
test_mode = "thorough"          # thorough, quick, adaptive, minimal

[generation.review_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"

[generation.test_llm]
provider_type = "openai"
model = "gpt-5.2"
api_key_env = "OPENAI_API_KEY"

Lokale Modelle (Ollama)

[llm]
provider_type = "openai-compatible"
model = "qwen3-coder:latest"
base_url = "http://localhost:11434/v1"
api_key_env = "none"            # Ollama benötigt keinen Schlüssel

CLI-Anbieter (bestehende CLI-Tools als LLM-Backend verwenden)

[llm]
provider_type = "cli"
model = "claude-sonnet-4-6"
cli_command = "claude"
cli_args = ["-p", "--no-session-persistence", "--output-format", "text", "--dangerously-skip-permissions"]
request_timeout_secs = 900

Unterstützte CLI-Tools: claude, codex, gemini. Der Prompt wird über stdin geleitet; die Antwort von stdout erfasst.

Optional: Deklarieren, wie das CLI System-Prompts nativ akzeptiert:

cli_system_args = ["--system-prompt-file"]  # für claude (liest aus temporärer Datei)
# cli_system_args = ["-s"]            # für codex

Wenn cli_system_args gesetzt ist, werden Anweisungen über den nativen Systemkanal übermittelt, anstatt in stdin eingefügt zu werden.

Benutzerdefinierte Basis-URL (Bedrock, Vertex AI, Proxies)

Alle Anbieter unterstützen optionale base_url für benutzerdefinierte Endpunkte:

# Anthropic über AWS Bedrock
[llm]
provider_type = "anthropic"
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

# Gemini über Google Vertex AI
[llm]
provider_type = "gemini"
base_url = "https://us-central1-aiplatform.googleapis.com"

Container-Einstellungen (optional)

[generation.container]
runtime = "podman"              # docker oder podman
timeout = 120                   # Sekunden
cleanup = true
# setup_commands = ["apt-get update && apt-get install -y cmake"]  # Wird vor Abhängigkeiten/Tests ausgeführt

Befehle

skilldo generate [PFAD]

Generiert eine SKILL.md für ein Bibliotheks-Repository.

Wichtige Flags:

• --language <SPRACHE> — Sprache erzwingen (python, javascript, rust, go, java). Auto-Erkennung, falls weggelassen
• --config <PFAD> — Konfigurationsdateipfad (Standard: ./skilldo.toml oder ~/.config/skilldo/config.toml)
• --model <MODELL> — LLM-Modell überschreiben
• --provider <ANBIETER> — LLM-Anbieter: anthropic, openai, chatgpt, gemini, openai-compatible
• --base-url <URL> — Basis-URL für openai-compatible Anbieter
• -i, --input <PFAD> — Vorhandene SKILL.md als Referenz für Aktualisierungen verwenden
• -o <PFAD> — Ausgabedatei (Standard: SKILL.md)
• --debug-stage-files <VERZ> — Rohausgabe jeder Pipeline-Stufe zur Fehlerspeicherung speichern
• --replay-from <VERZ> — Zwischengespeicherte Ausgaben von Extrahieren/Kartieren/Lernen aus vorherigem --debug-stage-files-Lauf laden, überspringt diese LLM-Aufrufe. Reduziert Iterationszeit von ~15 min auf ~5 min
• --no-test — Testvalidierung überspringen
• --no-review — Überprüfungsvalidierung überspringen
• --no-security-scan — YARA/Unicode/Injection-Scan überspringen
• --no-parallel — Extrahieren/Kartieren/Lernen sequenziell ausführen (für lokale Modelle)
• --best-effort — Beenden mit 0 auch bei Fehlern
• --telemetry / --no-telemetry — Laufprotokollierung umschalten
• --container — Test-Agent in einem Container ausführen (Standard: direkt auf der Maschine mit uv/cargo)
• --install-source <MODUS> — Wie der Test-Agent die Bibliothek zur Code-Validierung installiert: registry (von crates.io/PyPI/npm, Standard), local-install (lokal repomounten und über Paketmanager bauen), local-mount (Repo mounten und Modulpfad direkt setzen, kein Build-Schritt)
• --source-path <PFAD> — Lokaler Quellpfad für die Modi local-install/local-mount
• --test-mode <MODUS> — thorough testet ALLE Muster (Standard), quick testet bis zu 3 für schnelle Iteration, minimal testet 1, adaptive startet mit 1 und erweitert
• --review-model <MODELL> / --review-provider <ANBIETER> — Modell/Anbieter nur für die Überprüfungsstufe überschreiben
• --test-model <MODELL> / --test-provider <ANBIETER> — Modell/Anbieter nur für die Testcode-Generierungsstufe überschreiben
• --max-retries <N> — Maximale Anzahl der Wiederholungen von Erstellen → Validieren, bevor aufgegeben wird (Standard: aus Konfiguration)
• --skill-version <VER> — Eine bestimmte Bibliotheksversion im Frontmatter erzwingen (z. B. "2.1.0") anstelle der Auto-Erkennung
• --version-from <STRATEGIE> — Wie die Version erkannt wird: package (Cargo.toml/pyproject.toml), git-tag, branch, commit
• -q, --quiet — Informationsausgabe unterdrücken (nur Warnungen/Fehler)
• -v, --verbose — Detaillierte Debug-Ausgabe anzeigen (entspricht RUST_LOG=debug)
• --request-timeout <SEK> — LLM-Request-Timeout in Sekunden überschreiben (Standard: 120)
• --dry-run — Mock-LLM-Client zum Testen verwenden (keine API-Aufrufe)

skilldo lint <PFAD>

Lintet eine SKILL.md auf strukturelle Fehler (Frontmatter, Abschnitte, Code-Blöcke).

skilldo review <PFAD>

LLM-gestützte Überprüfung einer vorhandenen SKILL.md auf Genauigkeit und Sicherheit.

Wichtige Flags:

• --config <PFAD> — Konfiguration mit LLM-Einstellungen

skilldo config check --config <PFAD>

Validiert eine Konfigurationsdatei auf Korrektheit.

skilldo auth login|status|logout

Verwaltet OAuth-Tokens für Anbieter, die OAuth verwenden (z. B. ChatGPT).

Unterstützte Sprachen

Sprache	Ökosystem	Erkennung
Python	pip/uv, pyproject.toml, setup.py	*.py, pyproject.toml
JavaScript/TypeScript	npm, package.json	*.js, *.ts, package.json
Go	go modules, go.mod	*.go, go.mod
Rust	cargo, Cargo.toml	*.rs, Cargo.toml
Java	Maven/Gradle, pom.xml, build.gradle	*.java, pom.xml, build.gradle

Konfiguration (skilldo.toml)

Wichtige [generation]-Felder:

Feld	Werte	Beschreibung
language	python, javascript (oder typescript/ts/js), rust, go, java	Überschreibt die Auto-Erkennung
security_context	"api-client" oder weglassen	Lockert den Sicherheitsscan für API-Client-SDKs, die Anmeldedaten/Auth diskutieren
redact_env_vars	["VAR_NAME", ...]	Umgebungsvariablenwerte werden in Testausgaben/Logs mit ***GESCHWÄRZT*** maskiert
custom_instructions	"""..."""	Repo-spezifische Anweisungen für die Erstellungsstufe (überschreibt Stil-/Inhaltsregeln)
enable_test	true/false	Testvalidierung ein-/ausschalten (Standard: true)
enable_review	true/false	Überprüfungsvalidierung ein-/ausschalten (Standard: true)
test_mode	thorough/quick/minimal/adaptive	Alle/bis zu 3/1/1+ Muster testen
max_retries	integer	Maximale Anzahl Wiederholungen Erstellen→Validieren (Standard: 10)

Modellkommunikation

Das Modell meldet Unsicherheiten über HTML-Kommentare in der Ausgabe (vor der endgültigen SKILL.md entfernt):

• <!-- SKILLDO-CONFLICT: beschreibung --> — Dokumentations- vs. Code-Konflikte gefunden
• <!-- SKILLDO-UNVERIFIED: beschreibung --> — APIs, die das Modell nicht aus dem Quellcode verifizieren konnte

Zeigen Sie diese mit RUST_LOG=info oder RUST_LOG=debug an. CONFLICT wird auf info, UNVERIFIED auf warn protokolliert.

Häufige Workflows

Mit Anthropic generieren

source ~/.anthropic
skilldo generate --provider anthropic --model claude-sonnet-4-6

Mit OpenAI generieren

source ~/.openai
skilldo generate --provider openai --model gpt-5.2

Mit lokalem Ollama generieren

skilldo generate --provider openai-compatible --model qwen3-coder:latest --base-url http://localhost:11434/v1

Batch-Generierung (mehrere Repos)

for repo in /pfad/zu/repos/*/; do
  skilldo generate "$repo" --config shared-config.toml --best-effort
done

Für ein API-Client-SDK generieren

# skilldo.toml — für Bibliotheken, die API-Schlüssel/Auth diskutieren
[generation]
security_context = "api-client"
redact_env_vars = ["MY_API_KEY"]

export MY_API_KEY="..."  # für Testvalidierung erforderlich
skilldo generate . --config skilldo.toml

Schnelle Prompt-Iteration mit Replay

# Cache einmal erfassen
skilldo generate /pfad/zu/bib --debug-stage-files /tmp/cache -o /tmp/baseline.md

# An Prompts iterieren (nur Erstellungsstufe läuft, ~5 min vs ~15 min)
skilldo generate /pfad/zu/bib --replay-from /tmp/cache -o /tmp/variant.md

Pipeline-Stufen debuggen

skilldo generate . --debug-stage-files ./debug-output/
# Schreibt: 1-extract.md, 2-map.md, 3-learn.md, 4-create-raw.md, 4-create-system.md, facts.md,
#          5-review-*.txt, 6-normalized.md

Eine vorhandene SKILL.md überprüfen

skilldo review SKILL.md --config skilldo.toml

Telemetrie

Wenn telemetry = true, hängt jeder Lauf eine Zeile an ~/.skilldo/runs.csv an:

• Zeitstempel, Sprache, Bibliotheksname, Version
• Verwendete Modelle und Anbieter (generieren, überprüfen, testen)
• Bestanden/fehlgeschlagen, Wiederholungsanzahl, Dauer, Fehlerdetails

Die Daten sind nur lokal – es wird nichts gesendet.

Fehlerbehebung

• "Keine Testdateien gefunden" — eine Warnung, kein Fehler. Die Pipeline wird ohne testabgeleitete Muster fortgesetzt. Verwenden Sie --language, um zu überschreiben, wenn die Erkennung falsch ist.
• Testfehler wiederholen sich — Versuchen Sie --test-mode minimal oder --no-test für einen ersten Durchlauf.
• Ratenbegrenzung — Erhöhen Sie retry_delay in der Konfiguration oder wechseln Sie zu einem lokalen Modell.
• OAuth-Fehler — Führen Sie skilldo auth status --config <pfad> aus, um den Token-Status zu überprüfen.
• install_source-Fehler bei Nicht-Python — local-install/local-mount funktioniert nur für Python. Verwenden Sie für andere Sprachen das Standard-registry.

Dokumentation

Vollständige Dokumentation – Konfiguration, Sprachen, Architektur, Authentifizierung, Best Practices und Telemetrie: docs/