claude-workflow/skills/script/SKILL.md

---

description: Bash-Script-Lifecycle nach Best Practices — Aufgabenklärung → Scope-Einschätzung → Schnell- oder Vollpfad → shellcheck → PR → Merge. Aktivieren für jede Bash-Script-Aufgabe: neues Script, Feature, Bugfix, Refactoring. Nicht verwenden für andere Shells (sh/zsh/fish), Python-/Node-Scripts oder einfache Einzeiler/Aliase. model: claude-opus-4-6

/script — Bash-Script-Lifecycle

Nicht-verhandelbare Mindeststandards — gelten für beide Pfade:

• Feature-Branch
• shellcheck (alle Befunde beheben)
• PR erstellen, Approval abwarten, mergen

Vorab: Repository-Check

git rev-parse --show-toplevel

Scheitert der Befehl: Abbruch. Der Skill arbeitet ausschließlich innerhalb eines Repos. Meldung an den User:

"Kein Git-Repository gefunden. Starte /script erst nach git init oder aus einem bestehenden Repo."

---

Phase 0: Aufgabenklärung + Scope-Einschätzung

0a: Aufgabe klären

Lies das betroffene Script (falls vorhanden) und den Request. Stelle offene Fragen, falls nötig — aber nur solche, die den Lösungsweg beeinflussen:

• Bei Bugfixes: Was ist das erwartete Verhalten? Was passiert stattdessen? Wie lässt sich der Fehler reproduzieren?
• Bei neuen Features: Was soll das Script leisten, was es heute nicht kann? Gibt es Randbedingungen (Umgebung, Eingaben, Abhängigkeiten)?
• Bei neuen Scripts: Welches Problem wird gelöst? Wer ruft das Script auf und in welchem Kontext?

Wenn der Request eindeutig genug ist, diese Fragen überspringen.

Warte auf Antwort des Users, bevor du mit 0b fortfährst.

0b: Scope einschätzen

Entscheide anhand dieser Heuristiken:

Schnellpfad wenn alle Punkte zutreffen:

• Kein neues CLI-Interface (kein neues Flag, kein neuer Subcommand, keine neue Abhängigkeit)
• Änderung betrifft nur internen Ablauf (Bugfix, Ausgabe, Logik)
• Geschätzter Diff: < 20 Zeilen

Vollpfad wenn mindestens eines zutrifft:

• Neues Script
• Neues Flag, Subcommand oder externe Abhängigkeit
• Strukturelle Änderung (Error-Handling, Trap, Exit-Codes, Logging-Schema)
• Geschätzter Diff: ≥ 20 Zeilen

Präsentiere dem User in einem Satz: Pfad + Begründung. Warte auf Bestätigung oder Korrektur.

---

Schnellpfad

S1: Branch + Implementierung

git checkout -b fix/script-<name>   # oder feat/ je nach Typ

Änderungen direkt implementieren. Bash-Leitplanken einhalten:

• Quoting: "$var", Arrays als "${array[@]}"
• Keine neuen Magic Numbers ohne benannte Konstante
• set -euo pipefail muss gesetzt bleiben

S2: shellcheck (Pflicht)

shellcheck <script>

Alle Befunde beheben. Falls nicht installiert: User informieren (sudo apt install shellcheck) und in bootstrap.sh aufnehmen.

S3: Review-Checkliste

Auch bei kleinen Änderungen prüfen:

• Vertauschte oder irreführende Variablennamen
• Unmögliche Shell-Operationen (z.B. tar -rf auf .gz)
• Gleiche Daten mehrfach abfragen statt Variable wiederverwenden
• Ausgaben die Erfolg suggerieren obwohl nichts passiert ist

S4: Test-Empfehlungen

Gib dem User konkrete Kommandos zum Verifizieren der Änderung. Warte auf Rückmeldung.

S5: Abschluss via /ship

Rufe /ship auf (Commit → Push → PR → Merge → Cleanup).

---

Vollpfad

V1: Planung (Opus)

Aktiviere den Plan-Modus (EnterPlanMode).

Wenn das Script auf spezifische Tools/Libraries aufsetzt (z.B. jq, gh, yq), Dokumentation via Context-7 abrufen — nur wenn inhaltlich nützlich:

mcp__plugin_context7_context7__resolve-library-id
mcp__plugin_context7_context7__query-docs

Plan-Inhalt:

• Zweck: Was das Script löst, ein bis zwei Sätze
• CLI-Interface: Positionsargumente und Flags (--help, --dry-run Pflicht bei destruktiven Aktionen, --verbose, ggf. --yes)
• Abhängigkeiten: Externe CLI-Tools, werden am Script-Start per command -v geprüft
• Error-Handling: Cleanup-Strategie (trap), definierte Exit-Codes (0 Erfolg, 1 Fehler, 2 Usage, weitere dokumentiert)
• Konsolenausgabe: Eine Zeile pro Hauptschritt ( Schritt ... ok (Details)). Keine Farben außer Gelb (Warnungen) und Rot (Fehler). Keine Querlinien, Tabellen oder Raw-Ausgabe. Ergebnis in die Hauptzeile, nicht als separater Block. "Erfolgreich" nur wenn tatsächlich etwas passiert ist — keine irreführenden Meldungen
• Output-Beispiel: Exakte Zeile-für-Zeile-Ausgabe für den typischen Ablauf, so wie der User sie sehen soll
• Code-Skelett: Hauptfunktion als Ablauf von Funktionsaufrufen, Hilfsfunktionen als Signatur mit Kommentar. Sonnet füllt die Funktionskörper
• Dry-Run: Welche Aktionen werden durch Log-Ausgabe ersetzt
• User-Einbindung: Rückfragen bei irreversiblen Operationen (read -p), --yes für nicht-interaktive Ausführung
• Explizite Verbote: Bekannte Pitfalls, Redundanzen und Stilfehler benennen, die Sonnet vermeiden muss
• Randfälle: Für jeden Hauptschritt: "Was kann hier schiefgehen oder sinnlos sein?"
• Test-Szenarien: Konkrete Aufrufe für die spätere Verifikation

Speichere den Plan unter <repo-root>/plans/script-<name>.md (Verzeichnis bei Bedarf anlegen).

Präsentiere den Plan dem User. Warte auf Bestätigung bevor V2 startet.

V2: Implementierung (Sonnet)

Wechsle das Modell: /model claude-sonnet-4-6.

Feature-Branch anlegen:

git checkout -b feat/script-<name>

Bash-spezifische Leitplanken:

• Shebang #!/usr/bin/env bash, direkt danach set -euo pipefail und IFS=$'\n\t'
• Quoting konsequent: "$var", Arrays als "${array[@]}"
• main()-Funktion am Dateiende, aufgerufen mit main "$@"
• Script ausführbar machen: chmod +x <pfad>

V3: shellcheck (Pflicht)

shellcheck <script>

Alle Befunde beheben. Falls nicht installiert: User informieren (sudo apt install shellcheck) und in bootstrap.sh aufnehmen.

V4: Review-Checkliste

Prüfe Sonnets Implementierung auf typische Fehler:

• Vertauschte oder irreführende Variablennamen
• Unmögliche Shell-Operationen (z.B. tar -rf auf .gz)
• Syntax die bash -n nicht findet aber zur Laufzeit crasht
• Gleiche Daten mehrfach abfragen statt Variable wiederverwenden
• Variablen die geschrieben aber nie gelesen werden
• Funktionen die nur einmal aufgerufen werden und keinen Mehrwert bieten
• Ausgaben die Erfolg suggerieren obwohl nichts passiert ist

Alle Befunde beheben, dann erneut shellcheck laufen lassen.

V5: Test-Empfehlungen

# Hilfe
<script> --help

# Happy Path
<script> <typische Argumente>

# Dry-Run (falls implementiert)
<script> --dry-run <typische Argumente>

# Fehlerfall — erwartet Exit-Code ≠ 0 und klare Meldung
<script> <ungültiger Aufruf>

Warte auf Rückmeldung des Users. Bei Problemen: Fehler beheben, Tests erneut empfehlen.

V6: Abschluss via /ship

Rufe /ship auf (Commit → Push → PR → Merge → Cleanup).

Abschlussmeldung:

• PR-URL
• Script-Pfad
• Kurze Zusammenfassung der implementierten Funktionen