Wie Sie ein Programmierbuch in einen AI-Agent-Skill verwandeln

Die Antworten Ihres AI Agent wirken plausibel, verweisen aber nicht zuverlässig auf Seiten, Versionen oder Voraussetzungen?

Die schnellste Lösung ist eine Dreiteilung: PDF-Parsing, Knowledge Base und Agent Skill bleiben getrennt. Speichern Sie Fakten, Code und Quellen in der Knowledge-Schicht. Lassen Sie den Skill nur Auslöser, Suchschritte, Ausführung und Prüfung definieren. Nur kurze, stabile Inhalte gehören direkt in einen Skill.

Für wen diese Vorgehensweise gedacht ist

Diese Anleitung richtet sich an Sie, wenn Sie Programmierbücher mit Code, Tabellen oder gescannten Seiten verarbeiten möchten. Sie vergleichen gerade eine vollständige Skill-Datei mit einer suchbaren Knowledge Base. Oder Sie wollen mehrere technische Bücher dauerhaft pflegen, ohne bei jeder neuen Ausgabe den gesamten AI Agent neu zu bauen.

Die Architektur für die Woche vom 17.08.2026

Empfehlung für diese Woche: Beginnen Sie nicht mit dem Schreiben der Skill-Datei. Nehmen Sie zuerst eine legale PDF mit drei unterschiedlichen Seitentypen: eine normale Textseite, eine Scan-Seite und eine Seite mit Code oder Tabelle. Wenn die Quellenzuordnung dort nicht funktioniert, wird sie bei einem vollständigen Buch nicht automatisch besser.

Erst die PDF klassifizieren, dann das passende Verfahren wählen

Eine PDF ist kein einheitliches Eingabeformat. Für Ihre Architektur sind mindestens drei Fälle relevant:

1. Textbasierte PDF: Der Text ist markierbar und lässt sich kopieren.
2. Scan-PDF: Die Seite besteht überwiegend aus einem Bild.
3. Komplexe oder gemischte PDF: Text, zweispaltiges Layout, Tabellen, Screenshots und Code stehen nebeneinander.

Für textbasierte Seiten eignet sich eine blockorientierte Extraktion. PyMuPDF kann Text unter anderem als Blöcke ausgeben. Dabei bleiben Textbereiche und ihre Positionen auf der Seite erhalten. Das ist für Kapitelüberschriften, Codeblöcke und Randspalten wichtiger als eine einfache Zeichenkette. Die offizielle Dokumentation zur blockbasierten Textextraktion beschreibt diesen Ansatz.

Prüfen Sie direkt nach der Extraktion vier Fehlerquellen:

• Wird eine zweispaltige Seite in der richtigen Lesereihenfolge ausgegeben?
• Sind Kopf- und Fußzeilen als wiederholte Inhalte enthalten?
• Werden Sonderzeichen, Operatoren und Einrückungen im Code korrekt übernommen?
• Bleibt die Seitenzahl als Quelleninformation erhalten?

Ein sauber extrahierter Text ist noch keine gute Knowledge Base. Wenn ein Kapitelname, ein Codebeispiel und die zugehörige Erklärung voneinander getrennt werden, kann der Agent später zwar Text finden, aber keine verlässliche Handlung daraus ableiten.

PDF sollte nicht automatisch direkt im Agent Skill landen

Die vollständige PDF direkt in den Agent Skill zu legen, ist nur bei kurzen und langfristig unveränderten Dokumenten sinnvoll. Ein umfangreiches Programmierbuch enthält dagegen Beispiele, Versionshinweise, Alternativen und Voraussetzungen. Diese Inhalte ändern sich nicht alle gleich schnell.

Die Entscheidung ist damit klar: Der Skill ist kein Ersatz für das Buch. Er ist eine Ausführungsschicht, die entscheidet, wann Wissen gesucht, wie es bewertet und wann ein Tool verwendet wird.

Erster Schritt: Textbasierte PDF mit Seitenbezug extrahieren

Legen Sie zunächst eine unveränderte Originaldatei ab. Vergeben Sie einen eindeutigen Dateinamen mit Titel, Ausgabe und Quelle. Erzeugen Sie danach eine Extraktionsfassung, aber überschreiben Sie niemals das Original.

Bei textbasierten PDFs sollten Sie mindestens folgende Felder je Textblock erhalten:

{
  "text": "Extrahierter Inhalt",
  "book_title": "Titel des Buches",
  "edition": "Ausgabe oder Versionsstand",
  "chapter": "Kapitelpfad",
  "page": 42,
  "block_type": "paragraph",
  "source_file": "buch-ausgabe-2.pdf"
}

Die Zahl im Beispiel ist lediglich ein Platzhalter für das Datenmodell. In Ihrer tatsächlichen Pipeline muss die Seitenzahl aus der Originalseite stammen.

Trennen Sie anschließend wiederkehrende Kopf- und Fußzeilen. Löschen Sie sie nicht blind. Markieren Sie zunächst, auf welchen Seiten sie erscheinen. Ein Abschnitt mit dem Namen einer API kann sonst fälschlich wie fachlicher Inhalt behandelt werden.

Für Code gelten strengere Regeln als für Fließtext. Bewahren Sie Sprache, Bibliotheksversion, Betriebssystemannahmen, Eingabedateien und erwartete Ausgabe gemeinsam auf. Die Zeile import allein ist kein verwertbares Wissenselement, wenn die Erklärung zur Installation oder zur verwendeten Version fehlt.

Zweiter Schritt: Scans und komplexe Layouts gezielt mit OCR prüfen

Bei einer Scan-PDF sollten Sie nicht sofort jede Seite durch OCR schicken. Prüfen Sie zuerst, welche Seiten tatsächlich keinen extrahierbaren Text enthalten. Das spart Verarbeitung und verringert die Zahl unnötiger Erkennungsfehler.

Eine geeignete Qualitätsprobe enthält:

• eine Seite mit normalem Fließtext,
• eine Seite mit Code und Einrückungen,
• eine Seite mit Tabelle,
• eine zweispaltige Seite,
• eine Seite mit Screenshot oder Diagramm.

Unstructured dokumentiert für PDFs die Strategien auto, fast, hi_res und ocr_only. Bei auto wird abhängig von den Eigenschaften des Dokuments zwischen Verfahren gewählt. Die offizielle Übersicht zur PDF-Partitionierung beschreibt außerdem Optionen für Seitenumbrüche, Tabellen, OCR-Sprachen und Layoutverarbeitung.

Für Ihre Entscheidung gilt:

• fast: sinnvoll, wenn der Text bereits maschinenlesbar ist.
• ocr_only: sinnvoll, wenn der Inhalt aus Bildern besteht und die Texterkennung im Vordergrund steht.
• hi_res: sinnvoll, wenn Layout, Tabellen oder Bildbereiche erhalten bleiben müssen.
• auto: sinnvoll für eine gemischte Eingangssammlung, aber nicht als Ersatz für eine Qualitätsprüfung.

Bei mehrspaltigen Scans ist die Reihenfolge besonders kritisch. Ein OCR-System kann die rechte Spalte vor der linken Spalte lesen. Bei Code kann schon ein falsch erkanntes Zeichen die Ausführung verändern. Prüfen Sie deshalb nicht nur, ob Wörter erkannt wurden, sondern ob die extrahierte Struktur der Originalseite entspricht.

Eine dokumentierte Grenze ist ebenfalls wichtig: Bei der OCR-Verarbeitung kann die Elementgröße begrenzt werden. In der offiziellen Dokumentation wird für ocr_only ein Standardwert von 1.500 Zeichen für max_partition beschrieben. Das ist eine technische Voreinstellung, keine optimale Chunk-Größe für jedes Buch. Die Details zu Partitionierungsstrategien und Elementgrenzen sollten Sie vor der Implementierung kontrollieren.

Dritter Schritt: Code, Erklärung und Laufzeitbedingungen gemeinsam speichern

Ein Codebeispiel wird erst dann zu brauchbarem Agent-Wissen, wenn seine Umgebung bekannt ist. Speichern Sie daher nicht nur den Code, sondern eine zusammengehörige Einheit aus:

• Aufgabe oder Ziel,
• Erklärung,
• Code,
• Programmiersprache,
• Bibliotheken,
• Versionsstand,
• Eingaben,
• erwarteter Ausgabe,
• bekannten Einschränkungen,
• Seiten- und Kapitelquelle.

Ein gutes Datenmodell kann so aussehen:

{
  "kind": "code_recipe",
  "task": "Datei einlesen und strukturieren",
  "language": "Python",
  "dependencies": [
    {"name": "bibliothek-x", "version": "aus der Quelle übernehmen"}
  ],
  "preconditions": [
    "Eingabedatei vorhanden",
    "passende Laufzeit installiert"
  ],
  "code": "…",
  "expected_result": "…",
  "source": {
    "book": "…",
    "chapter": "…",
    "page": "…",
    "edition": "…"
  }
}

Vermeiden Sie die automatische Behauptung, dass ein Beispiel noch aktuell ist. Wenn ein Buch eine ältere Bibliotheksversion beschreibt, muss diese Information erhalten bleiben. Der Agent kann dann entweder genau diese Version verwenden oder ausdrücklich melden, dass eine Anpassung erforderlich ist.

Das ist einer der wichtigsten Unterschiede zwischen einer Dokumentensammlung und einer ausführbaren Entwicklungsunterstützung: Die Knowledge Base bewahrt die Aussage der Quelle. Der Skill entscheidet, ob diese Aussage für die aktuelle Aufgabe ausreicht.

Vierter Schritt: Knowledge Base nach Bedeutung statt nach Zeichenlänge schneiden

Mechanisches Chunking mit immer gleich langen Textabschnitten erzeugt bei Programmierbüchern häufig unbrauchbare Einheiten. Ein Abschnitt beginnt dann mitten in einer Erklärung, während die zugehörige Codezeile im nächsten Abschnitt landet.

Besser ist eine hierarchische Struktur:

1. Buch
2. Teil oder Kapitel
3. Unterkapitel
4. Konzept, Rezept oder Fehlerfall
5. Codeblock mit Voraussetzungen und Ergebnis

LlamaIndex verwendet Dokument- und Node-Strukturen, die Metadaten und Beziehungen zwischen Wissenseinheiten abbilden können. Für Ihre Implementierung ist besonders wichtig, dass jede Einheit ihre Herkunft behält. Nutzen Sie dafür die offizielle Dokumentation zu Documents, Nodes und Metadaten.

Ein sinnvoller Retrieval-Schlüssel enthält nicht nur den Text. Ergänzen Sie Filter wie:

• Programmiersprache,
• Bibliothek,
• Versionsbereich,
• Kapitel,
• Inhaltstyp,
• Schwierigkeitsgrad,
• Quellenausgabe.

Bei einer Frage zur Fehlerbehebung sollte der Agent nicht wahllos Absätze aus dem gesamten Buch erhalten. Er sollte zunächst nach Sprache, Bibliotheksversion und Themenbereich einschränken. Erst danach folgt die semantische Suche.

Knowledge Base und Skill übernehmen unterschiedliche Aufgaben

Die Trennung lässt sich praktisch so prüfen:

Knowledge Base

• enthält extrahierte und geprüfte Inhalte,
• bewahrt Seiten- und Kapitelangaben,
• kann mehrere Ausgaben desselben Buches speichern,
• liefert Belegstellen für Antworten,
• wird bei neuen Quellen inkrementell aktualisiert.

Agent Skill

• definiert, wann der Ablauf ausgelöst wird,
• beschreibt die Suchreihenfolge,
• legt fest, welche Metadaten erforderlich sind,
• entscheidet, wann Code ausgeführt werden darf,
• prüft Ergebnis, Fehlermeldung und Quellenbezug.

Ein Skill sollte also nicht mehrere Kapitel in eigenen Worten nacherzählen. Er sollte beispielsweise anweisen: „Erkenne zuerst Sprache und Versionsanforderung, suche danach passende Rezepte, zeige die Quelle und führe Code nur in einer isolierten Umgebung aus.“

Fünfter Schritt: Den Agent Skill als kontrollierten Ablauf bauen

Beginnen Sie mit einem engen Anwendungsfall. „Hilf bei allen Programmierfragen“ ist zu breit. „Führe Python-Dateiverarbeitungsrezepte aus der Knowledge Base aus und prüfe die Ausgabe“ ist testbar.

Ein belastbarer Ablauf besteht aus sieben Stationen:

1. Trigger erkennen: Passt die Anfrage zum Themenbereich und zur unterstützten Sprache?
2. Anforderungen extrahieren: Welche Version, Eingabedatei und Laufzeit werden benötigt?
3. Knowledge Base durchsuchen: Erst Metadatenfilter, dann semantische Suche.
4. Quellen vergleichen: Stimmen Kapitel, Ausgabe und Voraussetzungen überein?
5. Lösung entwerfen: Code und Erklärung aus einer gemeinsamen Einheit verwenden.
6. Ausführung absichern: Sandbox, Dateirechte, Netzwerkzugriff und Abhängigkeiten prüfen.
7. Ergebnis validieren: Ausgabe, Fehlermeldungen und Quellenangabe kontrollieren.

Die offizielle Dokumentation zu Agent Skills und ihrer Verwendung in Agent-Systemen beschreibt Skills als wiederverwendbare Fähigkeiten, die bei Bedarf geladen werden können. Für Ihre Architektur folgt daraus ein wichtiger Grundsatz: Der Skill sollte klein genug bleiben, damit seine Regeln verständlich und testbar sind. Das Buchwissen gehört in referenzierbare Dateien oder eine Knowledge Base.

Sechster Schritt: Code nur in einer isolierten Umgebung ausführen

Sobald Ihr Agent Code aus einem Buch startet, entsteht ein anderes Risikoprofil. Eine Antwort zu erzeugen ist nicht dasselbe wie ein Skript auszuführen.

Legen Sie mindestens diese Grenzen fest:

• eigenes Arbeitsverzeichnis pro Aufgabe,
• keine geheimen Umgebungsvariablen im Prozess,
• standardmäßig kein ausgehender Netzwerkzugriff,
• begrenzter Zugriff auf Dateien,
• reproduzierbare Abhängigkeiten,
• Protokollierung von Eingabe, Version und Ergebnis,
• automatisches Löschen temporärer Dateien.

Die Ausführungsumgebung muss außerdem zwischen drei Zuständen unterscheiden:

• Code syntaktisch gültig, Ergebnis falsch
• Code wegen fehlender Abhängigkeit nicht ausführbar
• Code erfolgreich ausgeführt, aber Quelle oder Versionsannahme unpassend

Diese Unterscheidung gehört in den Skill. Sonst meldet der Agent bei jedem Fehler nur, dass der Code „nicht funktioniert“, obwohl möglicherweise die falsche Bibliotheksversion verwendet wurde.

Wenn Sie PDFs oder Code außerhalb Ihrer lokalen Umgebung verarbeiten, prüfen Sie zusätzlich DSGVO-Anforderungen. Legale Nutzungsrechte am Buch reichen nicht automatisch aus, um Inhalte an einen externen Dienst zu übertragen. Definieren Sie Speicherfristen, Zugriffskontrollen und Löschprozesse, bevor Sie interne oder lizenzierte Fachliteratur hochladen.

Siebter Schritt: Mehrere Bücher versionssicher zusammenführen

Bei mehreren Programmierbüchern sollten Sie thematisch zusammenführen, aber Quellen nicht vermischen. Zwei Bücher können dieselbe API unterschiedlich erklären, weil sie verschiedene Versionen behandeln.

Speichern Sie daher pro Knowledge-Einheit:

• eindeutige Quellen-ID,
• Titel und Ausgabe,
• Veröffentlichungs- oder Versionsangabe, sofern vorhanden,
• Kapitel und Seite,
• Extraktionsmethode,
• Prüfstatus,
• bekannte Konflikte.

Bei einer neuen Ausgabe müssen Sie nicht zwangsläufig alles neu aufbauen. Ermitteln Sie zunächst, welche Kapitel, Seitenbereiche und Code-Rezepte betroffen sind. Danach aktualisieren Sie die abhängigen Knowledge-Einheiten und führen die zugehörigen Skill-Tests erneut aus.

Ein einfacher Regressionstest enthält typische Fragen und Aufgaben:

• eine reine Begriffsfrage,
• eine Frage mit Quellenverlangen,
• eine Versionsfrage,
• ein Code-Rezept,
• ein absichtlich fehlerhafter Anwendungsfall,
• ein Ausführungsversuch mit fehlender Abhängigkeit.

Die Bewertung sollte nicht nur die sprachliche Qualität messen. Prüfen Sie auch Seitenbezug, Versionstreue, Sicherheitsentscheidung und tatsächliches Ergebnis.

Achtung beim Offline-Betrieb und bei sensiblen PDFs

Für interne Bücher, Kundendokumentation oder lizenzierte Unterlagen kann eine lokale Verarbeitung sinnvoll sein. Sie reduzieren damit die Übertragung sensibler Inhalte, müssen aber selbst für Laufzeit, OCR, Abhängigkeiten, Backups und Zugriffsschutz sorgen.

Offline bedeutet nicht automatisch sicher. Temporäre OCR-Dateien, Cache-Verzeichnisse und Debug-Protokolle können weiterhin den vollständigen Buchinhalt enthalten. Legen Sie fest, welche Dateien nach der Verarbeitung gelöscht werden. Verschlüsseln Sie Datenträger und beschränken Sie den Zugriff auf die Verzeichnisse der Knowledge Base.

Für wiederholbare Verarbeitung sollte die Umgebung versioniert werden. Halten Sie Parser, OCR-Komponenten, Embedding-Modell und Skill-Dateien getrennt fest. Ein späterer Parserwechsel kann die Segmentierung verändern, selbst wenn sich die PDF nicht geändert hat.

Bewertungsmatrix für Ihre endgültige Entscheidung

Die Bewertung ist keine Messung einer bestimmten Softwareleistung. Sie ist ein Architekturvergleich für Ihre Wartungs- und Prüfkosten.

Typische Fehler, die Sie vor dem ersten produktiven Lauf vermeiden

Sie extrahieren alles mit OCR.
Das erhöht nicht automatisch die Qualität. Bei einer textbasierten PDF kann die vorhandene Textschicht genauer sein als eine neue Bilderkennung.

Sie entfernen Seitenzahlen.
Damit verlieren Sie die wichtigste Rückverbindung zur Originalquelle. Speichern Sie Seitenzahlen auch dann, wenn sie nicht in den sichtbaren Antworttext gelangen.

Sie trennen Code von Erklärung.
Ein Codeblock ohne Voraussetzungen ist kein vollständiges Rezept.

Sie verwenden feste Chunks für jedes Kapitel.
Struktur und Bedeutung sind bei technischen Büchern wichtiger als eine einheitliche Zeichenlänge.

Sie schreiben Versionsannahmen in den Skill.
Solche Angaben veralten. Legen Sie sie in die Knowledge-Einheit und lassen Sie den Skill danach filtern.

Sie testen nur erfolgreiche Beispiele.
Ein produktiver Agent muss auch fehlende Abhängigkeiten, widersprüchliche Quellen und nicht passende Versionen korrekt behandeln.

Fazit: Erst Wissen beweisen, dann Aktionen erlauben

Wenn Sie ein Programmierbuch in einen AI-Agent-Skill verwandeln, sollten Sie nicht mit einer großen Markdown-Datei beginnen. Bauen Sie zuerst eine geprüfte Pipeline aus Original-PDF, strukturierter Knowledge Base und ausführbarem Skill. Die Knowledge-Schicht bewahrt Fakten, Seiten, Versionen und Konflikte. Der Skill definiert den Ablauf und begrenzt die Aktionen.

Ihre lokale Notebook- oder gemeinsame Cloud-Lösung kann für einzelne Experimente ausreichen. In der Praxis entstehen dort jedoch schnell drei Nachteile: schwankende Abhängigkeiten, unklare Dateirechte und fehlende Isolation zwischen Testläufen. Wenn Sie viele PDF-Dateien verarbeiten oder Beispiele reproduzierbar ausführen müssen, bietet eine gemietete Mac-Umgebung von VPSSpark einen kontrollierteren Arbeitsort für temporäre Parser-, OCR- und Sandbox-Tests. Das ersetzt keine Sicherheitsprüfung und ist nicht automatisch die beste Lösung für dauerhaft hohe Last oder Anforderungen an physische Schnittstellen. Für zeitlich begrenzte Verarbeitung, Versionsvergleiche und isolierte Entwicklungsumgebungen ist es jedoch oft sinnvoller, einen klar abgegrenzten Rechner zu mieten, statt Ihre tägliche Arbeitsmaschine mit wechselnden Toolchains zu belasten.

Wenn Sie die Umgebung zunächst organisatorisch prüfen möchten, finden Sie auf der VPSSpark-Übersicht zu den verfügbaren Angeboten den passenden Einstieg. Bei individuellen Anforderungen an PDF-Verarbeitung, Codeausführung oder Zugriffsschutz können Sie außerdem direkt eine technische Anfrage an VPSSpark stellen.