Communitygithub.com

CodeSoul-co/theta-skill

Portable THETA Agent-Workflow-Fähigkeit zur thematischen Modellierung.

Was ist theta-skill?

Diese portable Agent-Fähigkeit führt KI-Assistenten wie Claude Code, Cursor oder Codex durch den vollständigen THETA-Workflow zur thematischen Modellierung – von der Absichtsklärung bis zur Ergebnisinterpretation. Sie umfasst ein klares Sicherheitsprotokoll, das schreibgeschützte Inspektionen (z. B. Repository-Prüfung, Datenanalyse) von mutationsbehafteten, kostenintensiven oder GPU-lastigen Operationen trennt. Letztere erfordern eine explizite Benutzerbestätigung in einem standardisierten Format, um versehentliche Änderungen oder Kosten zu vermeiden. Der Workflow unterstützt sowohl lokale als auch Cloud-Embeddings, wobei Cloud-Embedding nur im Zero-Shot-Modus nach Bestätigung erlaubt ist. Der Agent prüft zuerst, ob ein nutzbares THETA-Repository existiert, und stoppt bei dessen Fehlen mit einem Klon-Bestätigungsschritt. Anschließend führt er schreibgeschützte Inspektionen durch, empfiehlt Modelle und Parameter, generiert Befehle zur Überprüfung und führt diese erst nach erneuter Bestätigung aus. Referenzdateien (workflow.md, commands.md, result-analysis.md, user-questions.md, confirmation-flow.*.md) liefern detaillierte Entscheidungsbäume, Befehlslisten und Bestätigungsformate.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add CodeSoul-co/theta-skill

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

THETA Workflow

Verwenden Sie diese portable Agent-Workflow-Fähigkeit, um Benutzer durch THETA-Topic-Modeling-Arbeiten von der Absichtsklärung bis zur Ergebnisinterpretation zu führen. Passen Sie die Sprache des Benutzers an: Verwenden Sie Deutsch für deutsche Anfragen und Englisch für englische Anfragen. Gehen Sie nicht von Codex-spezifischen APIs aus; der Kernworkflow basiert auf dem Lesen von Dateien, dem Nachfragen von Bestätigungen, der Ausführung normaler Shell-Befehle nach Bestätigung und der Verwendung des gebündelten schreibgeschützten Python-Preflight-Helfers.

Kern-Sicherheitsprotokoll

Unterscheiden Sie schreibgeschützte Inspektionen von Operationen, die Dateien, Umgebungen, Kosten, Rechenleistung oder den Git-Status ändern.

Schreibgeschützte Inspektionen und Ratschläge benötigen keine zusätzliche Bestätigung:

  • Lesen Sie README, Dokumentationen, Skripte, Konfigurationsvorlagen und Ergebnisdateien.
  • Überprüfen Sie die Repository-Struktur, Dateiexistenz, Python-Version, Conda-Verfügbarkeit, Vorhandensein von .env, Modellpfad, Git-Status und verfügbare Befehle.
  • Untersuchen Sie das Datensatzschema, die Zeilenanzahl, Spaltennamen, fehlende Texte, doppelte Texte, Textlängen, Zeitspalten und Kovariatenspalten.
  • Empfehlen Sie Modelle, Parameter, Experimentdesigns und Befehlszeilen.
  • Fassen Sie vorhandene Metriken, Themenwörter, Thematafeln, Visualisierungen und Optimierungsvorschläge zusammen.

Operationen, die vor der Ausführung eine explizite Benutzerbestätigung erfordern:

  • Klonen oder Pull des THETA-Repositorys, Wechseln von Branches, Committen, Mergen oder Pushen.
  • Erstellen von Conda-Umgebungen, Installieren von Abhängigkeiten oder Ausführen von scripts/env_setup.sh.
  • Erstellen oder Bearbeiten von .env; niemals API-Schlüssel im Chat ausgeben, speichern oder ausgeben.
  • Konfigurieren oder Verwenden von Cloud-Embedding-Anbietern; Cloud-API-Aufrufe können Kosten verursachen und Text an einen externen Dienst weitergeben.
  • Herunterladen von Qwen-, SBERT- oder anderen lokalen Modellen.
  • Ändern, Bereinigen, Konvertieren oder Schreiben von Datensätzen; bevorzugen Sie die Erstellung einer neuen abgeleiteten Datei und ändern Sie standardmäßig niemals Originaldaten.
  • Ausführen von THETA- oder Baseline-Training, Multimodell-Vergleichen, Optimierungsdurchläufen, großen lokalen Modellen, GPU-lastigen Jobs oder Befehlen, die Ergebnisse schreiben.
  • Generieren von Berichtsdateien, Überschreiben von Ausgaben, Löschen von Caches, Löschen von Modellen, Löschen von Daten oder Bereinigen von Ergebnisverzeichnissen.

Wenn eine Bestätigung erforderlich ist, verwenden Sie dieses Format:

Ich bereite die Ausführung der folgenden Aktion vor:

Aktion:
<kurze Aktion>

Befehl:
<Befehl, falls vorhanden>

Betroffene Dateien oder Verzeichnisse:
<Pfade>

Möglicher Ressourcenverbrauch:
<lokale Rechenleistung / GPU / Speicher / API-Kosten / keine>

Werden vorhandene Dateien überschrieben:
<ja / nein>

Bitte bestätigen Sie, ob fortgefahren werden soll.

Fahren Sie nur nach einer expliziten Bestätigung wie bestätigt, ok, weiter, ausführen, yes, proceed oder run it fort. Wenn die Antwort mehrdeutig ist, fragen Sie einmal in der Sprache des Benutzers nach.

Lesen Sie für vollständige Bestätigungsabläufe, Beispiele und Bestätigungstabellen die Datei references/confirmation-flow.de.md (oder references/confirmation-flow.en.md für Englisch). Lesen Sie für Eingangsfragen die Datei references/user-questions.md.

Embedding-Regel

Verwenden Sie Cloud-Embedding nur für zero_shot-Workflows und nur nach Bestätigung der API-Kosten, des Anbieters, des Vorhandenseins von Schlüsseln und des Datenexfiltrationsrisikos.

Für supervised, unsupervised oder jeden Workflow, der Feinabstimmung benötigt, sind lokale Embeddings und lokale Qwen-kompatible Modellpfade erforderlich. Wenn der Benutzer Cloud-Embedding für einen feinabstimmungsfähigen Modus anfordert, erklären Sie, dass THETA dafür lokale Modelle benötigt, und schlagen Sie stattdessen eine lokale Konfiguration vor.

Empfohlener Workflow

  1. Identifizieren Sie, ob die Anfrage zur THETA-Themenmodellierung gehört. Für diese Routingeinscheidung ist keine Bestätigung erforderlich.
  2. Überprüfen Sie sofort, ob ein nutzbares THETA-Repository existiert, bevor Sie die Umgebung einrichten, Daten konvertieren oder das Training planen. Prüfen Sie auf README.md, .env.example, scripts/ und src/models/run_pipeline.py. Diese schreibgeschützte Prüfung erfordert keine Bestätigung.
  3. Wenn kein THETA-Repository existiert, besteht die erste Aktion darin, eine Bestätigung zum Klonen von https://github.com/CodeSoul-co/THETA.git anzufordern. Konfigurieren Sie keine Umgebungen, installieren Sie keine Abhängigkeiten, erstellen Sie keine .env, untersuchen Sie keine Datensätze oder generieren Sie keine Trainingsbefehle, bis das Repository existiert.
  4. Nachdem das Repository existiert, stellen Sie nur die notwendigen Aufgabenfragen in der Sprache des Benutzers: Datenpfad, Textspalte, Sprache, Zeitspalte, Kovariaten, Zielergebnis und Ressourcenbeschränkungen.
  5. Untersuchen Sie die Umgebung, den .env-Status und den Datensatz schreibgeschützt. Verwenden Sie scripts/inspect_theta_env.py, wenn eine deterministische Vorabprüfung sinnvoll ist.
  6. Empfehlen Sie basierend auf Daten und Ziel die Modellfamilie und Parameter.
  7. Generieren Sie Befehle zur Überprüfung, ohne sie auszuführen.
  8. Holen Sie vor der Ausführung eines mutationsbehafteten, kostspieligen, langlaufenden, GPU-lastigen oder dateischreibenden Befehls eine explizite Bestätigung im Standardformat ein.
  9. Lesen Sie nach der Ausführung die Ausgaben und erklären Sie Themenqualität, Überlappung, Kohärenz, Diversität, Exklusivität und nächste Optimierungsschritte.
  10. Bestätigen Sie erneut, bevor Sie zusätzliche Optimierungsexperimente durchführen, Berichtsdateien schreiben, Ausgaben überschreiben oder etwas löschen.

Aufrufverhalten

Wenn ein Assistent diese Fähigkeit verwendet – sei es durch Lesen von SKILL.md, durch Laden des Verzeichnisses skills/theta-workflow/ oder durch einen benannten Aufruf wie $theta-workflow – behandeln Sie den aktuellen Arbeitsbereich als ersten Kandidaten für das THETA-Repository. Wenn der aktuelle Arbeitsbereich nicht THETA ist, untersuchen Sie einen vom Benutzer angegebenen Pfad. Wenn kein nutzbares Repository gefunden wird, stoppen Sie beim Klon-Bestätigungsschritt. Stellen Sie keine Datenfragen oder schlagen Sie keine Umgebungseinrichtung vor, bis die Repository-Hürde erfüllt ist.

Gute erste Benutzeraufforderungen:

Verwenden Sie die THETA Workflow-Fähigkeit in skills/theta-workflow, um mir bei der Durchführung von THETA-Topic-Modeling auf einem politischen Textdatensatz zu helfen.
Use the THETA Workflow skill in skills/theta-workflow to help me run THETA topic modeling on a policy-text dataset.

Wenn die Laufzeitumgebung die benannte Fähigkeitssyntax unterstützt, ist auch $theta-workflow akzeptabel.

Referenz-Routing

  • Lesen Sie references/workflow.md für den vollständigen End-to-End-Entscheidungsablauf.
  • Lesen Sie references/commands.md, bevor Sie THETA-Befehle generieren; es listet die aktuellen Repository-Einstiegspunkte und Bestätigungsanforderungen auf.
  • Lesen Sie references/result-analysis.md, wenn Sie Ausgabedateien interpretieren oder Optimierungen empfehlen.
  • Lesen Sie references/user-questions.md, wenn Sie den Benutzer nach Datensatz, Sprache, Ziel, Ressourcen oder Ausgabepräferenzen fragen.
  • Lesen Sie references/confirmation-flow.de.md, wenn detaillierte deutsche Bestätigungstexte oder Beispiele benötigt werden.
  • Lesen Sie references/confirmation-flow.en.md, wenn detaillierte englische Bestätigungstexte oder Beispiele benötigt werden.

Preflight-Skript

Führen Sie dieses Skript nur für schreibgeschützte Inspektionen aus:

python skills/theta-workflow/scripts/inspect_theta_env.py \
  --dataset path/to/data.csv \
  --text-column content \
  --mode zero_shot

Fügen Sie --json hinzu, wenn eine strukturierte Ausgabe benötigt wird. Das Skript darf keine Dateien schreiben, Abhängigkeiten installieren, APIs aufrufen oder Training starten.

Verwandte Skills