CommunitySchreiben & Editierengithub.com

lukehalley/introspect

Agent-unabhängiger Selbstverbesserungs-Skill: Liest deine Claude Code-, Codex- und Cursor-Threads und wandelt wiederkehrende Korrekturen in Regeln für CLAUDE.md / AGENTS.md / .cursor/rules um – die Schreibhälfte von /insights.

Was ist introspect?

Introspect ist ein agent-unabhängiger Skill für selbstverbessernde KI-Assistenten in Entwicklungsumgebungen wie Claude Code, OpenAI Codex und Cursor. Er analysiert die Transkripte dieser Tools, identifiziert wiederkehrende Muster – also echte Gewohnheiten statt einmaliger Taktiken – und schlägt mit deiner Zustimmung Regeländerungen in den jeweiligen Konfigurationsdateien vor (z. B. CLAUDE.md, AGENTS.md, .cursor/rules). Der Fokus liegt auf Nachhaltigkeit: Nur Muster, die mehrfach auftreten, nicht bereits dokumentiert sind und einen signifikanten Einfluss hätten, werden berücksichtigt. So vermeidet Introspect Aufblähung und stellt sicher, dass sich dein Setup mit der Zeit verbessert, statt bei jeder Sitzung von neuem zu beginnen. Der Skill läuft wahlweise on demand, geplant über den nativen Scheduler oder optional nach einer festgelegten Anzahl von Sitzungen – stets mit menschlicher Zustimmung vor jeder Änderung.

Funktioniert mit✓Claude Code✓Codex CLI✓Cursor
npx skills add lukehalley/introspect

Installed? Explore more Schreiben & Editieren skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht introspect?

Mache aus dem, was in deinen KI-Coding-Threads passiert ist, Änderungen daran, wie deine Agenten für dich arbeiten – damit dein Setup sich aufbaut, statt bei jeder Sitzung zurückgesetzt zu werden.

Es ist agent-unabhängig. Es liest deine Threads von Claude Code, OpenAI Codex und Cursor, findet die wenigen Dinge, die es wert sind, geändert zu werden, und schreibt sie – mit deiner Zustimmung – zurück in die Konfiguration des Agenten, der zukünftige Sitzungen tatsächlich steuert. Claude Code hat bereits /insights, das die letzten 30 Tage liest und einen Bericht anzeigt. Das ist die Lese-Hälfte, nur für Claude. Introspect ist die Schreib-Hälfte, für alle Agenten, die du verwendest. Youssef hat es im Thread, aus dem dies stammt, treffend formuliert: repariere das System einmal, damit du das Ergebnis nicht tausendmal reparieren musst.

Die eine Idee, die dies zum Funktionieren bringt: Muster, nicht Taktiken

Der Fehlermodus von „Was hätte ich besser machen können?“ ist, dass er Taktiken an die Oberfläche bringt – ein besseres Flag für einen Befehl, eine klügere Herangehensweise an einen Fehler. Diese bauen sich nicht auf. Sie sind morgen weg.

Was sich aufbaut, ist eine Gewohnheit, die du immer wieder hast: dieselbe Korrektur, die du in drei verschiedenen Threads gibst, dieselbe Präferenz, die du jede Woche wiederholst, dieselbe falsche Abzweigung, die der Agent jedes Mal nimmt, wenn er dein Test-Setup berührt. Der gesamte Skill ist daher auf Wiederholung ausgelegt:

Eine Kandidatenänderung verdient nur dann ihren Platz, wenn sie mehr als einmal auftaucht, nicht bereits irgendwo aufgeschrieben ist und plausibel das Ergebnis verändert hätte. Alles andere ist Rauschen – protokollieren, nicht handeln.

Das ist auch die ehrliche Antwort auf die beiden Ängste, die in diesem Thread geäußert wurden:

  • „Ich habe Angst, dass sich schlechte Entscheidungen summieren / mein Workflow dumm wird.“ → Nichts wird ohne deine Einsicht in den exakten Diff und deine Zustimmung geschrieben. Jede angewandte Änderung wird protokolliert und ist umkehrbar. Im Zweifelsfall weniger vorschlagen.
  • „Aktualisiert der Skill einfach jeden Tag für immer den Skill – konvergiert er jemals?“ → Er sollte konvergieren. Wenn eine Regel bereits existiert, wird sie gestärkt oder zusammengeführt; es wird keine zweite hinzugefügt. Ein ruhiger Tag erzeugt einen leeren Änderungssatz, und das ist ein Erfolg, kein Misserfolg.

Die Pipeline

Sammeln  →  Extrahieren  →  Diff vs. bestehendes Setup  →  Änderungssatz vorschlagen  →  Genehmigen  →  Anwenden + Protokollieren
(Skript)    (du)           (du, lese aktuelle Konfiguration)    (du, mit Belegen)         (Benutzer)     (du, umkehrbar)

1. Sammeln – führe das Skript aus, parst nichts von Hand

scripts/collect_threads.py liest den Thread-Speicher jedes Agenten (Claudes JSONL, Codex' Rollout-Dateien, Cursors SQLite), filtert auf einen Zeitraum, schwärzt Geheimnisse und gibt EINEN gemeinsamen Digest aus: pro Sitzung wird markiert, welcher Agent es war, die eingegebenen Prompts des Menschen, die verwendeten Tools, wo Tools Fehler verursacht haben und leichte „Friktions“-Signale (Prompts, die wie Korrekturen aussehen, Tools, die viele Male hintereinander aufgerufen wurden).

python3 scripts/collect_threads.py --days 1               # heute, jeder installierte Agent (auto)
python3 scripts/collect_threads.py --agent all --days 7   # letzte Woche, erzwinge alle drei
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject   # ein Projekt
python3 scripts/collect_threads.py --selftest             # Plausibilitätsprüfung aller drei Parser

--agent standardmäßig auto (erkennt, welche Agenten installiert sind). Verwende --format md, wenn du es selbst liest; --format json für die Nachbearbeitung. Das Skript entscheidet nie – es liefert dir sauberes, normalisiertes Rohmaterial, damit du dein Urteilsvermögen für das Wesentliche einsetzt, nicht für das Parsen von drei verschiedenen Transkriptformaten.

2. Extrahieren – lies den Digest und extrahiere drei Arten von Dingen

Lies den Digest, als wärst du der Stabschef des Benutzers, der den Tag über alle seine Tools hinweg überprüft. Die Präferenzen des Benutzers haben Vorrang – dieser Skill dreht sich hauptsächlich darum, zu lernen, wie sie arbeiten möchten, nicht darum, das Basisverhalten eines Agenten zu überwachen. Trenne:

  1. Dauerhafte Präferenzen (das Hauptthema) – der Benutzer korrigiert einen Standard oder wiederholt, wie er Dinge mag („nein, verwende pnpm“, „hör auf, Kommentare hinzuzufügen“, „schneide immer zuerst einen Branch von Development ab“, „fasse das Worktree nicht an“). Eine Präferenz, die sowohl in deinen Claude- als auch in deinen Codex-Threads auftaucht, ist ein besonders starkes Signal – es geht um dich, nicht um das Tool.
  2. Setup-Lücken, die den Agenten zu wiederholter Arbeit zwangen – wo der Agent sessionübergreifend neu ableitete oder stecken blieb, weil etwas nicht aufgeschrieben war: einen Build-Befehl neu lernen, eine Datei wiederfinden, die immer am selben Ort liegt, fehlender Projektkontext. Die Lösung ist, das Fehlende in die Konfiguration des Benutzers zu schreiben – NICHT, eine Regel hinzuzufügen, die den Agenten tadelt. Wenn eine Wiederholung nur generisches Agentenverhalten ohne benutzerspezifische Lösung ist (z. B. „lese eine Datei, bevor du sie bearbeitest“), ist das keine Regel, sondern Rauschen; lass es weg.
  3. Wiederverwendbare Workflows – ein mehrschrittiger Vorgang, den der Benutzer mehr als einmal durchgeführt hat und der es verdient, ein Skill oder ein Befehl zu sein, damit es beim nächsten Mal ein Schritt ist.

Notiere für jeden Kandidaten die Belege: welcher Agent, welche Sitzungen, wie oft, ein kurzes Zitat. Keine Belege für Wiederholung → es ist eine Taktik, kein Muster → verwirf ihn.

3. Diff gegen das bestehende Setup – der Anti-Aufblähungs-/Konvergenzschritt

Bevor du etwas vorschlägst, lies, was bereits für den/die relevanten Agenten vorhanden ist, damit du das System stärkst, statt es aufzublähen. references/routing.md enthält die genauen Lese-/Schreiborte und -formate für jeden Agenten; die Kurzfassung:

AgentVorhandene Konfiguration zum Lesen (und später Schreiben)
Claude~/.claude/CLAUDE.md (global), ./CLAUDE.md, projektbezogener Speicher ~/.claude/projects/<verzeichnis>/memory/, ~/.claude/skills/, ~/.claude/commands/
Codex~/.codex/AGENTS.md (global), <repo>/AGENTS.md (Projekt), Skills in ~/.agents/skills/
Cursor.cursor/rules/*.mdc (Projekt), Legacy .cursorrules, AGENTS.md

Frage für jeden Kandidaten: Ist das bereits abgedeckt? Wenn ja → verwirf ihn oder schlage eine kleine Bearbeitung vor, die die bestehende Regel schärft. Füge niemals eine zweite Regel hinzu, die fast dasselbe sagt. Wenn sich zwei Kandidaten überschneiden, führe sie zusammen. Bevorzuge Bearbeitung gegenüber Hinzufügen.

Agentenübergreifender Tipp: AGENTS.md wird von Codex und Cursor gelesen, und viele Leute verlinken es symbolisch mit CLAUDE.md. Wenn eine Präferenz wirklich universell ist, schreibe sie bevorzugt dorthin, wo jeder Agent sie sieht (eine AGENTS.md oder ein CLAUDE.md↔AGENTS.md-Symlink), anstatt sie dreimal zu duplizieren. Löse immer Symlinks auf, bevor du schreibst, damit du weißt, welche Datei du wirklich bearbeitest.

4. Änderungssatz vorschlagen – konkrete Diffs mit Belegen, gedeckelt

Präsentiere einen Änderungssatz: eine geordnete, überfliegbare Liste, bei der jedes Element den Ziel-Agenten + die Datei, die genaue Bearbeitung (ein Diff oder ein klar markiertes Vorher/Nachher), die Belege und eine Konfidenz enthält. Verwende das Format in references/changeset-format.md. Zwei Regeln halten es vernünftig:

  • Deckele es. Zeige maximal ~5 Änderungen pro Durchlauf an, zuerst die mit der höchsten Konfidenz. Alles andere kommt in einen „Backlog“-Abschnitt – notiert, nicht angewendet. Eine Flut von Bearbeitungen ist der Weg, wie Workflows dumm werden.
  • Sortiere nach Wiederholung × Auswirkung. Eine Präferenz, die dreimal genannt wurde und jede Sitzung eine Korrektur spart, schlägt jederzeit eine clevere Einmaligkeit.

Speichere den Änderungssatz immer in einem datierten Bericht, auch wenn nichts angewendet wird, damit es eine Aufzeichnung zum Zurückblicken gibt (das beantwortet die Frage aus dem Thread: „Speicherst du die Ausgaben irgendwo oder liest du nur und machst weiter?“). Schreibe ihn nach ~/.introspect/reports/YYYY-MM-DD.md.

5. Genehmigen – das Tor

Zeige den Änderungssatz und lass den Benutzer wählen, was angewendet werden soll: alles, einiges oder nichts. Standardmäßig vorschlagen-und-genehmigen – bearbeite keine Konfiguration eines Agenten ohne explizite Zustimmung. Verwende AskUserQuestion (Mehrfachauswahl), um dem Benutzer die Auswahl von Elementen zu ermöglichen, wenn es mehrere gibt. Wenn der Benutzer explizit nach einem unbeaufsichtigten/geplanten Durchlauf gefragt hat, siehe „Unbeaufsichtigte Durchläufe“ unten.

6. Anwenden + protokollieren – umkehrbar

Schreibe für jedes genehmigte Element auf die richtige Oberfläche (vollständige Formate in references/routing.md):

  • Claude – CLAUDE.md: unter dem richtigen ##-Abschnitt anhängen oder die Regel direkt bearbeiten; den Hausstil beibehalten (kurz, imperativ, erklärt warum).
  • Claude – Speicher: eine Knotendatei erstellen/anhängen und eine Indexzeile zu MEMORY.md hinzufügen; die Konventionen feedback_* / project_* / reference_* und [[wikilink]]-Querverweise einhalten.
  • Claude – Skill/Befehl: ~/.claude/skills/<name>/SKILL.md oder ~/.claude/commands/<name>.md erstellen/bearbeiten. Wenn mehrere Sitzungen dasselbe Hilfsskript neu geschrieben haben, bündle es.
  • Codex – AGENTS.md: innerhalb eines verwalteten Blocks anhängen (<!-- introspect:begin --> … <!-- end -->), damit wiederholte Durchläufe idempotent sind; halte es kompakt (Codex kürzt AGENTS.md bei ~32 KiB). Bevorzuge das AGENTS.md im Projektstammverzeichnis (die Desktop-App lädt das globale nicht zuverlässig).
  • Cursor – .cursor/rules/*.mdc: eine Regeldatei mit YAML-Frontmatter schreiben (alwaysApply: true für immer aktive Präferenzen oder description: + alwaysApply: false). Versuche NICHT, Cursors Cloud-„Erinnerungen“ zu schreiben; verwende Regeldateien. Schreibe nicht in die Live-Datei state.vscdb, während Cursor läuft.

Füge dann eine Zeile zum Hauptbuch ~/.introspect/ledger.jsonl hinzu – ein JSON-Objekt pro angewendeter Änderung: {date, agent, target_file, kind, summary, evidence, sessions, undo_hint}. Das Hauptbuch ermöglicht es dir, (a) zu zeigen, wie sich das Setup im Laufe der Zeit aufgebaut hat, und (b) eine Änderung später rückgängig zu machen. Notiere vor dem Bearbeiten einer vorhandenen Datei ihren vorherigen Zustand in undo_hint (oder behalte eine .bak-Sicherung).

Sicherheitsmodell (lies das – es ist der einzige Grund, warum dies sicher täglich ausgeführt werden kann)

  • Vorschlagen, nicht aufzwingen. Genehmigungsschritt standardmäßig aktiviert. Der Benutzer sieht jeden Diff.
  • Wiederholungsschwelle. Nicht von einem einmaligen Auftreten vorschlagen. Gewohnheiten, nicht Taktiken.
  • Konvergieren, nicht durchwühlen. Bestehende Regeln stärken/zusammenführen, anstatt Fast-Duplikate hinzuzufügen. Ein Durchlauf, der nichts ändert, ist in Ordnung und an einem ruhigen Tag zu erwarten.
  • Deckele die Schadensbreite. Maximal ~5 Änderungen pro Durchlauf; der Rest in den Backlog.
  • Regeln drehen sich um den Benutzer, nicht um den Agenten. Erfasse, wie der Benutzer arbeiten möchte. Erfinde keine Regeln, die nur die Grundkompetenz des Agenten wiederholen (wie „lese vor dem Bearbeiten“) – das ist Aufblähung. Ein Signal „Der Agent steckte fest / wiederholte sich“ verdient eine Änderung nur dann, wenn das Aufschreiben eines Teils des Setups des Benutzers die Wiederholung verhindern würde.
  • Speichere niemals Geheimnisse. Der Sammler schwärzt gängige Schlüssel-/Token-Formen, aber bleibe wachsam: Kopiere niemals einen API-Schlüssel, ein Passwort, einen .env-Wert oder ein Token in eine Regel oder einen Bericht. Wenn du eines siehst, lass es weg und (wenn es live aussieht) markiere es für den Benutzer.
  • Umkehrbar. Alles Angewandte befindet sich mit einem Rückgängig-Hinweis im Hauptbuch.
  • Richtige Oberfläche, richtiger Geltungsbereich. Benutzerweite Präferenzen → die globale Datei für diesen Agenten. Projektspezifische Fakten → die Konfiguration dieses Projekts. Stecke keine Projekt-Belanglosigkeiten in eine globale Datei.

Auslöser – drei Möglichkeiten, es auszuführen

  1. Auf Abruf. „überprüfe meine Threads“, „führe introspect aus“, „was habe ich diese Woche immer wieder in Claude und Codex wiederholt?“, „mache die heutigen Korrekturen zu Regeln“. Standardfenster: heute.
  2. Täglich / geplant (Harness-nativ). Registriere den Durchlauf über den nativen Scheduler des Harnesses – den schedule-Skill oder das Routine-Tool CronCreate – NICHT über einen OS-Cron, launchd oder eine Shell-Schleife. Die native Planung führt die Routine innerhalb des Harnesses mit denselben Tools und Berechtigungen aus, und der Benutzer verwaltet sie mit /schedule. Ein guter Standard ist einmal täglich abends über das Fenster des Tages.
  3. Alle-N-Sitzungen / bei Reibung (optional). Manche Leute (siehe buildooor im Quellthread) ziehen es vor, dies auszulösen, wenn etwas schiefgelaufen ist, oder etwa alle 10 Sitzungen, anstatt nach der Uhr. Verdrahte es als einen Stop-Hook, der Aufrufe zählt und nach N einen Hinweis gibt. Biete es an; installiere niemals einen Hook ohne Zustimmung.

Unbeaufsichtigte Durchläufe

Wenn von einem Zeitplan/einer Routine ohne anwesenden Menschen aufgerufen, wende nicht stillschweigend Änderungen an der Konfiguration eines Agenten an. Führe stattdessen die Pipeline aus, schreibe den datierten Bericht mit dem vorgeschlagenen Änderungssatz nach ~/.introspect/reports/ und zeige eine kurze Zusammenfassung an (über die Benachrichtigung der Routine), damit der Benutzer bei seiner nächsten interaktiven Sitzung genehmigen kann. Die einzige Kategorie, die sicher unbeaufsichtigt automatisch angewendet werden kann, ist ein neuer Claude-Speicherknoten, der nichts dupliziert – und auch dann protokolliere ihn. Behalte die Aufbau unter menschlicher Kontrolle; das ist der Punkt.

Referenzen

  • references/routing.md – Lesequellen pro Agent + Schreiboberflächen + genaue On-Disk-Formate (CLAUDE.md, Speicher, AGENTS.md, .cursor/rules/*.mdc) und die Transkript-Schemas, die der Sammler verwendet.
  • references/changeset-format.md – die Vorlagen für Änderungssatz, Bericht und Hauptbuch.
  • scripts/collect_threads.py – der Multi-Agent-Sammler (führe --selftest aus, um ihn zu überprüfen).

Wiederholung der Kernschleife, denn das ist das Ganze: sammle die Threads von jedem Agenten → finde die wiederkehrenden Muster (keine einmaligen Taktiken) → überprüfe, dass sie nicht bereits aufgeschrieben sind → schlage einen kleinen, gedeckelten, belegbasierten Änderungssatz vor → wende nur das an, was genehmigt wurde, auf die Konfiguration des richtigen Agenten → protokolliere es umkehrbar.

Verwandte Skills