Skript-Skills: Python-Skripte in Skills bauen, freigeben und nutzen

Admin

Ein Skript-Skill ist ein Skill, der neben seiner Anleitung (SKILL.md) ein eigenes Python-Skript mitbringt. Der Assistent ruft das Skript auf, statt die Arbeit selbst zu formulieren: Es liest Ihre Datei lokal, rechnet nach festen Regeln und legt das Ergebnis als Datei ab — etwa eine SEPA-Überweisungsdatei aus einer CSV-Zahlungsliste. Das Modell sieht dabei nur die kurze Zusammenfassung, die das Skript zurückgibt, nicht die Daten. Wie gewöhnliche Skills ohne Skript funktionieren, steht in Neue Skills per ZIP hochladen.

Voraussetzungen

Desktop-App auf macOS oder Windows. Unter Windows sind Skript-Skills auf Windows 11 (x64) erprobt; auf ARM64-Geräten bietet die App sie ebenfalls an, dort sind sie aber noch nicht erprobt. Bekannte Grenzen stehen unten im Abschnitt „Besonderheiten unter Windows“. Unter Linux werden sie nicht angeboten; die App zeigt dann „Skript-Skills sind auf diesem Betriebssystem noch nicht freigegeben.“ In der Web-Variante gibt es sie nicht.
Lizenz ab Pro (Pro oder Site). In Free zeigt die App stattdessen einen Hinweis auf das Upgrade.
Administratorrolle für Hochladen, Freigeben und Neubauen.
uv ist installiert (der Python-Paketmanager von Astral). CompanyWizard liefert uv nicht mit. Fehlt es, zeigt die Skills-Seite den Installationsbefehl:
- macOS:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- Windows (PowerShell):
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Internetzugang für den einmaligen Bau der Umgebung: github.com, objects.githubusercontent.com und release-assets.githubusercontent.com (Python-Interpreter) sowie pypi.org und files.pythonhosted.org (Pakete). Wenn eine Firewall nach außen filtert, geben Sie diese Hosts frei.

Mit dem Beispiel starten

Das Beispiel SEPA-Überweisungen aus CSV ist ein vollständiger Skript-Skill, nur mit der Python-Standardbibliothek:

sepa-ueberweisungen.zip (ca. 5 KB)

Es enthält das Skill, das Skript und die Zahlungsliste beispiel.csv mit einer absichtlich falschen IBAN.

Hochladen — auf der Skills-Seite Skills hochladen (.zip) wählen und sepa-ueberweisungen.zip auswählen. Das Skill erscheint im Katalog, das Skript ist aber noch nicht ausführbar.
Skill öffnen — im Skill-Baum sepa-ueberweisungen wählen. Über der Anleitung erscheint der Bereich Skripte mit dem Skript sepa_from_csv, dem Status Nicht freigegeben, dem Stand (Kurzform des Prüfwerts), den Paketen (hier: keine) und Kein Netzwerkzugriff.
Freigeben — prüfen Sie Beschreibung, Pakete und Netzwerk-Hosts, dann Freigeben. Optional Im Chat ohne Rückfrage anhaken; dann entfällt im Chat der Bestätigungsdialog für dieses Skript.
Umgebung abwarten — nach der Freigabe baut CompanyWizard die Python-Umgebung: Umgebung: wird gebaut, danach bereit. Erst dann wird das Skript angeboten.
Im Chat nutzen — beispiel.csv in einen Ordner legen, diesen Ordner im Chat über Arbeitsordner anhängen, das Skill sepa-ueberweisungen in der Skill-Auswahl der Sitzung aktivieren und schreiben: „Erzeuge aus beispiel.csv eine SEPA-Datei, Ausführung am 2026-11-02, Auftraggeber Beispiel Handel GmbH mit IBAN DE02120300000000202051.“
Bestätigen — ein Dialog zeigt Skript, Parameter, Eingabedateien und Netzwerkzugriff. Nach der Bestätigung läuft das Skript. Die Antwort nennt zwei Zahlungen, die Summe und die Warnung zur falschen IBAN in Zeile 4; die Datei sepa-2026-11-02.xml liegt im Arbeitsordner.

Ein eigenes Skript-Skill bauen

Ein Skript-Skill ist ein Ordner auf oberster Ebene des ZIP:

mein-skill/
  SKILL.md              Anleitung für den Assistenten: wann und wie er das Skript aufruft
  skill-scripts.yaml    Manifest: Skripte, Parameter, Ein- und Ausgaben, Netzwerk
  requirements.txt      optional: Pakete mit Prüfsummen
  scripts/*.py          die Skripte

Das Manifest `skill-scripts.yaml`

So sieht es im Beispiel aus:

python: "3.12"
scripts:
  - name: sepa_from_csv
    description: "Erzeugt eine SEPA-Sammelüberweisung (pain.001.001.09) aus einer CSV-Zahlungsliste"
    entry: scripts/sepa_from_csv.py
    parameters:
      properties:
        execution_date:
          type: string
          pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
        debtor_account:
          type: string
          pattern: "^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$"
        debtor_name:
          type: string
      required: [execution_date, debtor_account, debtor_name]
    inputs: { min: 1, max: 1, extensions: [".csv"], max_mb: 5 }
    outputs: { extensions: [".xml"] }
    timeout_seconds: 60
    network: deny

Feld	Bedeutung
`python`	Python-Version, die uv bereitstellt, z. B. `"3.12"`.
`name`, `description`	Name des Skripts und Beschreibung, die der Assistent sieht.
`entry`	Pfad zur `.py`-Datei, relativ zum Skill-Ordner, ohne `..`.
`parameters`	Parameter mit Typ `string`, `integer`, `number` oder `boolean`, optional mit `pattern`; `required` listet die Pflichtparameter. CompanyWizard prüft sie vor dem Start.
`inputs`	Anzahl (`min`, `max`), erlaubte Endungen und Größe je Datei (`max_mb`, höchstens 200, das ist auch der Standard).
`outputs`	Endungen der Dateien, die das Skript erzeugt.
`timeout_seconds`	Zeitlimit, Standard 60, höchstens 3600.
`network`	`deny` oder `allowlist:host1,host2` mit einfachen Hostnamen.

Ein Feld secrets wird abgelehnt. Fehler im Manifest zeigt die Skills-Seite direkt nach dem Hochladen an („Diese Skills enthalten Skripte, die noch nicht freigegeben werden können:“) und im Bereich Skripte unter „Probleme im Skript-Manifest“.

Was das Skript bekommt und liefern muss

Start: wie python scripts/<datei>.py in einem frischen Arbeitsverzeichnis, ohne stdin und ohne weitere Argumente — input() funktioniert nicht. Eigene Module im Skriptordner lassen sich wie gewohnt importieren.
Eingabe: Die Umgebungsvariable CW_REQUEST zeigt auf eine request.json mit {"parameters": {…}, "inputs": ["in/…"]}. Die Eingabedateien liegen als Kopie unter in/.
Ausgabe: Dateien schreibt das Skript in den Ordner aus CW_OUTPUT_DIR.
Ergebnis: Auf stdout gibt es genau ein JSON-Objekt aus: {"summary": "…", "warnings": […], "metrics": {…}, "files": […]}. Nur summary ist Pflicht. Das ist alles, was der Assistent vom Lauf sieht.
Grenzen: stdout darf höchstens 64 KiB groß sein, sonst wird das Ergebnis abgelehnt. summary wird nach 4000 Zeichen gekürzt, jede Warnung nach 500.
Fehler: Ein Exit-Code ungleich 0 gilt als Fehler. Was das Skript auf stderr schreibt, erreicht den Assistenten nie; es steht nur im Protokoll der App. Melden Sie fachliche Probleme deshalb als warnings — der Assistent nennt sie dem Benutzer.
Umgebungsvariablen: nur PATH, HOME, LANG, LC_*, TZ, TMPDIR sowie CW_REQUEST und CW_OUTPUT_DIR; unter Windows zusätzlich SystemRoot, SystemDrive, windir, PATHEXT, COMSPEC, LOCALAPPDATA, TEMP und TMP. Zugangsdaten von CompanyWizard erreichen das Skript nicht.

Pakete: `requirements.txt` mit Prüfsummen

Ohne requirements.txt steht nur die Standardbibliothek zur Verfügung. Brauchen Sie Pakete, erzeugen Sie die Datei mit Prüfsummen:

uv pip compile requirements.in --generate-hashes -o requirements.txt

Jeder Eintrag braucht --hash=sha256:…. Fehlt eine Prüfsumme, wird das Manifest abgelehnt.
Keine Optionszeilen wie --index-url, -e oder -r; auch sie werden abgelehnt. Was Sie in der Datei sehen, ist genau das, was installiert wird.
Nur Wheels. Gibt es ein Paket nur als Quellpaket, schlägt der Bau der Umgebung mit einem Hinweis auf das Quellpaket fehl. Wählen Sie eine Version, für die ein Wheel für Ihr Betriebssystem existiert.

Packen und hochladen

Packen Sie den Skill-Ordner so, dass er die oberste Ebene des ZIP ist, und laden Sie ihn wie oben hoch. Der Assistent selbst kann Skript-Skills weder anlegen noch ändern — sie kommen nur per ZIP-Upload ins System.

Freigabe und Stand

Die Freigabe gilt für genau den geprüften Stand. CompanyWizard bildet über alle Dateien des Skills einen Prüfwert (ohne __pycache__, __MACOSX, .DS_Store) und prüft ihn vor jedem Start. Ändert sich eine Datei — neuer Upload, Bearbeitung —, zeigt das Skript „Seit der Freigabe geändert - Freigabe ausstehend“ und läuft erst nach erneuter Freigabe.
Gleiche Pakete, gleiche Umgebung. Skripte mit identischer requirements.txt und Python-Version teilen sich eine Umgebung.
Umgebung neu bauen verwirft die Umgebung und baut sie frisch auf, etwa nachdem Sie uv installiert haben oder wenn der Bau fehlgeschlagen ist. Solange ein Skript in dieser Umgebung läuft, wird das abgelehnt.
Widerrufen nimmt die Freigabe zurück; das Skript wird sofort nicht mehr angeboten.

Im Chat nutzen

Das Skill muss in der Skill-Auswahl der Sitzung aktiv sein. → Skills aktivieren und im Chat nutzen
Eingabedateien kommen aus dem angehängten Arbeitsordner oder als kb:-Pfad aus einem Wissensbereich, den der Benutzer lesen darf.
Ergebnisdateien landen im Arbeitsordner, ohne Arbeitsordner im Ausgabeordner der Desktop-App. Eine vorhandene Datei wird nie überschrieben. → Wohin speichert CompanyWizard Dokumente?
Vor jedem Lauf erscheint der Bestätigungsdialog — außer das Skript ist Im Chat ohne Rückfrage freigegeben. Das geht nur bei Skripten ohne Netzwerk-Hosts. Im Plan-Modus fragt die App immer nach.

In Agenten nutzen

Den Agenten öffnen, Tab Tools. Im Abschnitt Skript-Skills die freigegebenen Skripte anhaken. Damit wird auch das Werkzeug run_skill_script eingeschaltet; wer es später in der Werkzeugliste abwählt, schaltet die Skripte für diesen Agenten ab.
Im selben Tab einen Arbeitsordner festlegen — nur aus diesem Ordner liest ein Skript Eingabedateien. Für das SEPA-Beispiel liegt dort die CSV.
Optional einen Ausgabeordner der Skripte wählen. Leer bedeutet: der Arbeitsordner. Hat der Agent ein Ablageziel „Arbeitsordner“ (Tab Geltungsbereich), schreiben Skripte dorthin — das Ziel hat Vorrang vor dem Ausgabeordner und genügt zum Speichern auch allein. Ohne Ablageziel und ohne beide Ordner lässt sich der Agent nicht speichern („Für Skripte braucht der Agent einen Ausgabe- oder Arbeitsordner.“). Mit einem Ablageziel „Tresor“ werden Skripte nicht angeboten. → Agenten verketten
Skripte mit Netzwerk-Hosts laufen im Agenten nur, wenn Skripte mit Netzwerkzugriff erlauben angehakt ist.
Zusätzlich das Skill im Tab Skills aktivieren, damit der Agent die Anleitung aus der SKILL.md kennt.

Agenten laufen ohne Bestätigungsdialog und dürfen keine kb:-Eingaben verwenden. Kann ein Skript nicht laufen, steht der Grund am Anfang der Zusammenfassung des Laufs: „⚠ Skripte konnten nicht ausgeführt werden: …“.

Sicherheit: was ein Skript sieht

Originaldaten. Ein Skript arbeitet mit den Originaldateien, nicht mit pseudonymisierten Daten — das ist sein Zweck. Darf es ins Netz, kann es diese Daten an seine freigegebenen Hosts senden. Die Skills-Seite und der Agent weisen darauf hin („Dieses Skript erhält Originaldaten (nicht pseudonymisiert) und darf sie an diese Hosts senden.“). Die Freigabe der Hosts ist Ihre Vertrauensentscheidung.
Sandbox. Jeder Lauf hat ein eigenes Arbeitsverzeichnis; nur dort darf das Skript schreiben. Netzwerk gibt es nur zu den freigegebenen Hosts.
Leseeinschränkung. Unter macOS und Windows liest das Skript nur sein Arbeitsverzeichnis, seine Python-Umgebung und feste Systempfade. Unter macOS kann es feststellen, dass eine Datei anderswo existiert, wie groß und wie alt sie ist — lesen oder auflisten kann es sie nicht.
Bau der Umgebung unter Windows. Die Python-Umgebung baut CompanyWizard unter Windows außerhalb der Sandbox, weil uv darin nicht arbeiten kann. Der Bau installiert nur die Pakete aus der requirements.txt mit ihren Prüfsummen, ohne Code des Skills auszuführen. Sein Netzwerkverkehr läuft über den Proxy der App, der ihn lenkt und protokolliert, aber nicht erzwingt. Unter macOS läuft auch der Bau in der Sandbox.
Keine virtuelle Maschine. Wie beim CLI-Werkzeug ist das ein Containment nach bestem Vermögen, keine VM-Isolation. → Befehlszeilen-Werkzeuge (CLI) im Assistenten — Überblick & Grenzen
Höchstens zwei Skripte laufen gleichzeitig; weitere warten.

Besonderheiten unter Windows

Kein os.devnull. Ein Skript, das subprocess.DEVNULL oder open(os.devnull) nutzt, scheitert unter Windows mit PermissionError. Leiten Sie Ausgaben stattdessen in eine Datei im Arbeitsverzeichnis um oder lesen Sie sie mit subprocess.PIPE ein.
Netzwerk-Skripte auf Standardkonten. Skripte mit Netzwerk-Hosts sind bisher nur unter einem Benutzerkonto mit Administratorrechten erprobt. Unter einem Standardkonto kann ein solches Skript scheitern, weil es den Proxy der App nicht erreicht. Skripte ohne Netzwerkzugriff sind davon nicht betroffen.

Wenn etwas nicht klappt

Meldung	Was zu tun ist
„uv ist nicht installiert. …“	uv mit dem angezeigten Befehl installieren, dann Umgebung neu bauen.
Umgebung: Bau fehlgeschlagen	Den angezeigten Grund lesen: oft ein Paket ohne Wheel oder eine Firewall, die die Hosts aus den Voraussetzungen sperrt. Beheben, dann Umgebung neu bauen.
„Seit der Freigabe geändert - Freigabe ausstehend“	Das Skill hat sich geändert. Änderungen prüfen und erneut Freigeben.
„Skript-Skills sind auf diesem Betriebssystem noch nicht freigegeben.“	Skript-Skills laufen auf macOS und Windows, nicht unter Linux.
Ein Skript, das unter macOS läuft, bricht unter Windows ab	Im Protokoll der App nach `PermissionError` suchen: Oft nutzt das Skript `subprocess.DEVNULL` oder `open(os.devnull)`, siehe „Besonderheiten unter Windows“.
„Die Lizenz ist abgelaufen und im Nur-Lese-Modus. …“	Freigeben, Neubauen und Ausführen gehen erst nach der Verlängerung wieder; Widerrufen geht immer.
Das Skript bricht ab, der Assistent nennt nur einen Exit-Code	Die Fehlerausgabe (stderr) steht im Protokoll der App. Fachliche Probleme besser als `warnings` melden.