Mintlify: Mit mint migrate ziehen KI-Agenten Ihre Doku-Seite um

Leitfäden aus wiederholten Agentenfehlern

Mintlify nach eigenen Angaben hat Hunderte Doku-Seiten auf seine Plattform migriert. Die ersten Umzüge erfolgten von Hand, inzwischen übernehmen Agenten den Großteil der Arbeit. Dem Unternehmen fiel dabei auf, dass die Agenten immer wieder dieselben Fehler machten: Sie kopierten gemeinsam genutzte Inhalte in jede einzelne Seite, statt sie in einem einzigen Snippet zu halten. Sie übernahmen verkleinerte Bilder statt der Originale, sodass Screenshots unscharf wurden. Und sie verschoben Seiten, ohne dass die alten URLs weiter funktionierten.

Jedes Mal, wenn Mintlify eines dieser Probleme behoben hatte, schrieb es die Lösung in Leitfäden, die die internen Agenten nutzen. mint migrate liefert diese Leitfäden aus, damit auch der Agent eines Kunden sie verwenden kann.

Das Tool enthält Leitfäden für 21 Plattformen, darunter ReadMe, GitBook, Docusaurus, Confluence, Jekyll und PDFs. Jeder Leitfaden benennt, was mitgenommen wird und was nicht. So nennt das Unternehmen etwa den Try-It-API-Key-Status, Recipes und benutzerdefinierte HTML-Seiten als Elemente, die von ReadMe nicht übernommen werden, bei Docusaurus sind es Swizzled-Komponenten, benutzerdefinierte React-Seiten und die Algolia-Konfiguration. Fehlt in einem Export etwas, etwa die OpenAPI-Spezifikationen bei GitBook, weiß der Agent, dass er den Nutzer danach fragen muss.

Funktioniert mit Repo, Export oder Live-Seite

Die Doku muss nicht in einem Repository liegen. Laut Mintlify nutzt der Agent die beste verfügbare Quelle, und zwar in dieser Reihenfolge:

• Ihr Repo: Liegt die Doku in Git, arbeitet der Agent mit dem Quellcode, und Navigation, URLs und OpenAPI-Spezifikation werden so übernommen, wie die Konfiguration sie vorgibt.
• Ein Export: Bei Plattformen hinter einem Login, etwa Confluence, exportiert der Nutzer die Inhalte, und der Agent arbeitet mit diesem Ordner.
• Ihre Live-Seite: Bei gehosteten Plattformen ohne Repo speichert der Agent zunächst eine Kopie jeder veröffentlichten Seite und konvertiert dann aus diesen Dateien.

Steht eine Plattform nicht auf der Liste, folgt der Agent einem allgemeinen Ablauf, und die Anleitung zur manuellen Migration deckt den Rest ab. Wer mint migrate ohne Zusätze ausführt, sieht alle unterstützten Plattformen.

Agenten müssen ihre Arbeit selbst überprüfen

Die Leitfäden enthalten Regeln, die Mintlify aufgestellt hat, nachdem Agenten Migrationen falsch umgesetzt hatten. Wo die Quelle gemeinsame Dateien führt, wird jede zu einem einzigen Snippet, das überall importiert wird, wo die Quelle sie eingesetzt hat. Bilder kommen in Originalgröße mit, und für jede verschobene URL wird eine Weiterleitung angelegt.

Bevor der Agent die Seite zurückgibt, führt er Prüfungen durch. mint validate muss bestehen, sodass jede Seite geparst und gebaut werden kann. mint broken-links darf keine defekten Links finden. Ein Manifest muss jede Seite der Quelle als erledigt, ausgeschlossen oder blockiert aufführen, und zwar mit einer Begründung für jede Seite, die nicht erledigt ist. Anschließend meldet der Agent alles, was er nicht übertragen konnte, etwa eine individuelle Startseite oder eine Einbettung ohne Mintlify-Entsprechung, damit der Nutzer entscheiden kann, wie damit umzugehen ist.

Zum Datenschutz sagt Mintlify, die Migration laufe auf dem Rechner des Nutzers, in dessen Agenten und unter dessen eigenem Login. Laut dem Unternehmen laufen Inhalte nie über Mintlify, und es benötigt nie die API-Schlüssel des Nutzers. Die Regeln sind einsehbar: mint migrate --topic conversion zeigt, wie Seiten konvertiert werden, und mint migrate --from gitbook zeigt, wie eine GitBook-Seite behandelt wird.

Einstieg und Kosten

Nutzer installieren die Mintlify-CLI mit npm i -g mint oder führen npx mint@latest migrate aus. Nach dem Öffnen eines neuen Ordners für das Projekt starten sie mit einem Befehl wie mint migrate --agent claude. Das Flag --agent startet Claude Code, Codex, Cursor oder Gemini CLI, wobei die CLI des jeweiligen Agenten zuvor installiert sein muss. Andere Agenten können mint migrate ausführen und den ausgegebenen Anweisungen folgen. Mit --from, zum Beispiel --from gitbook, wird die Quellplattform ausgewählt. Danach teilt der Nutzer dem Agenten mit, wo die Doku liegt: ein Repo-Pfad, ein Export-Ordner oder eine URL.

Laut Mintlify ist mint migrate kostenlos, und die Migration läuft über das eigene Agenten-Abo des Nutzers. Für API-Referenzen verwendet der Agent eine vorhandene OpenAPI-Spezifikation. Gibt es keine, baut er nur mit Zustimmung des Nutzers eine aus den Referenzseiten und kennzeichnet sie im Bericht als rekonstruiert. Bei Versionen und Sprachen fragt der Agent, ob sie übernommen werden sollen, und ordnet sie den Versionen und Sprachen von Mintlify zu.

Sobald die Prüfungen bestanden sind, veröffentlicht mint deploy die Seite, und mint claim verknüpft sie mit einem Mintlify-Konto, sodass der gesamte Umzug im Terminal ablaufen kann. Mintlify bietet außerdem eine persönlich begleitete Migration für Teams an, die das lieber jemand anderem überlassen.