Technisches Buch in einen AI Skill verwandeln: Anleitung

Fehlendes Quellenregister und unklare Aufgaben führen bei langen Büchern schneller zu fehlerhaften Skills als die eigentliche Textextraktion. Die schnellste belastbare Lösung besteht deshalb nicht in einer einmaligen Zusammenfassung, sondern in einer kontrollierten Kette: Nutzungsrechte prüfen, Zielaufgaben definieren, Kapitel mit Fundstellen extrahieren, Wissen in Regeln und Abläufe zerlegen, SKILL.md schlank halten und den fertigen Skill mit realen Testfällen abnehmen.

Diese Anleitung richtet sich an Entwickler, die ein rechtmäßig verfügbares Fachbuch als persönliche Arbeitshilfe nutzen möchten, an Knowledge Engineers, die interne Schulungsunterlagen in Teamprozesse überführen, und an Skill-Autoren, die vermeiden wollen, dass beim Kürzen wichtige Bedingungen, Ausnahmen oder Versionsgrenzen verschwinden.

Ausgangslage und Zielaufgabe

Ein Buch ist zunächst ein lineares Dokument. Ein Agent Skill ist dagegen ein aufgabenorientiertes Wissensprodukt. Das Buch erklärt möglicherweise ein gesamtes Fachgebiet, während der Skill nur bestimmte Handlungen zuverlässig unterstützen soll: eine Architekturentscheidung vorbereiten, einen Debugging-Ablauf durchführen, eine technische Prüfung abarbeiten oder eine API-Integration nach festgelegten Regeln bewerten.

Diese beiden Formen dürfen Sie nicht gleichsetzen. Eine vollständige Buchzusammenfassung kann zwar inhaltlich beeindruckend wirken, löst aber mehrere technische Probleme:

• Unklare Aktivierung: Ein zu allgemeiner Skill wird bei Aufgaben geladen, für die er nicht gedacht ist, oder bei passenden Aufgaben nicht aktiviert.
• Verlust von Bedingungen: Aus „Wenn die Datenbank unter hoher Schreiblast steht, prüfen Sie zuerst …“ wird leicht die falsche allgemeine Regel „Prüfen Sie immer …“.
• Fehlende Rückverfolgbarkeit: Ohne Kapitel- und Seitenangabe lässt sich nicht feststellen, ob eine Aussage aus dem Buch stammt, falsch zusammengefasst oder nachträglich ergänzt wurde.
• Überladene Kernanweisungen: Wenn das komplette Fachwissen in SKILL.md landet, wird bei jeder Aktivierung unnötig viel Kontext geladen.
• Versionsrisiken: Ein Buch kann Beispiele für eine ältere Bibliotheksversion enthalten. Der Skill muss diese zeitliche Einordnung sichtbar machen, statt historische Aussagen als aktuelle Vorgaben auszugeben.
• Rechte- und Datenschutzrisiken: Eine rechtmäßige Nutzung der eigenen Kopie erlaubt nicht automatisch die Veröffentlichung, Weitergabe oder Ablage des vollständigen Buchinhalts in einem Team-Repository.

Die technische Definition eines Skills sieht mindestens eine SKILL.md mit YAML-Frontmatter und Markdown-Inhalt vor. Zusätzlich können scripts/, references/ und assets/ verwendet werden. Die offizielle Spezifikation für Skill-Verzeichnisse und SKILL.md beschreibt unter anderem die Pflichtfelder name und description, die optionalen Ressourcen und das Prinzip der schrittweisen Offenlegung.

Rechteprüfung vor der Verarbeitung

Verarbeiten Sie nur Material, das Sie tatsächlich nutzen dürfen. Das kann beispielsweise ein selbst gekauftes E-Book, ein intern freigegebenes Schulungsdokument oder ein Werk mit passender Lizenz sein. Die Besitz- oder Zugriffsberechtigung ist jedoch nicht automatisch eine Erlaubnis, den vollständigen Text in ein öffentliches Repository, einen Team-Workspace oder ein externes Verarbeitungssystem hochzuladen.

Vor dem ersten Extraktionslauf dokumentieren Sie daher:

1. Quelle und Lizenz: Woher stammt das Buch, und welche Nutzungsbedingungen gelten?
2. Verarbeitungszweck: Wird der Skill nur persönlich eingesetzt oder innerhalb eines Teams geteilt?
3. Speicherort: Werden PDF, Zwischendateien, OCR-Ergebnisse und Testprotokolle lokal oder in einer externen Umgebung gespeichert?
4. Ausgabegrenzen: Welche Textstellen dürfen in den Skill, in Logs oder in Fehlermeldungen übernommen werden?
5. Löschfrist: Wann werden Originaldatei, extrahierter Volltext und temporäre OCR-Dateien gelöscht?

Für Nutzer in Deutschland und der Europäischen Union ist außerdem relevant, ob eine Verarbeitung mit Text- und Data-Mining-Regeln vereinbar ist und ob ein Rechteinhaber bestimmte Nutzungen ausgeschlossen hat. Die EU-Dokumentation zu Text- und Data-Mining bei rechtmäßigem Zugang ist dafür eine bessere Ausgangsbasis als pauschale Aussagen aus Foren. Bei individuellen Lizenzverträgen oder kommerzieller Teamverwendung ersetzt sie keine juristische Prüfung.

Praktisch empfehlenswert ist ein Arbeitsverzeichnis, das das Original vom abgeleiteten Material trennt:

buch-skill-projekt/
├── original/
│   └── technisches-buch.pdf
├── extraction/
│   ├── toc.json
│   ├── pages.jsonl
│   └── ocr-report.md
├── knowledge/
│   ├── concepts.md
│   ├── procedures.md
│   └── exceptions.md
├── skill/
│   ├── SKILL.md
│   └── references/
└── evaluation/
    ├── test-cases.md
    └── results.md

Das Original sollte nicht in das fertige Skill-Paket kopiert werden. Speichern Sie stattdessen Fundstellen, kurze zulässige Notizen und eigene Formulierungen.

Entscheidungsweg für den richtigen Umfang

Bevor Sie Kapitel extrahieren, legen Sie fest, welche Art von Wissensprodukt Sie bauen. Die folgende Verzweigung verhindert, dass Sie unnötig ein komplettes Buch verarbeiten:

• Wenn der Agent einen wiederkehrenden Arbeitsablauf ausführen soll, wählen Sie einen prozeduralen Skill mit klaren Eingangsdaten, Prüfschritten und Ergebnissen.
• Wenn der Agent hauptsächlich Begriffe und Zusammenhänge erklären soll, wählen Sie einen Wissensskill mit strukturierten Referenzen und Quellenregister.
• Wenn der Agent eine Entscheidung vorbereiten soll, extrahieren Sie Alternativen, Kriterien, Voraussetzungen und Gegenargumente; übernehmen Sie nicht nur die Schlussfolgerung des Autors.
• Wenn nur ein einzelnes Kapitel für eine eng begrenzte Aufgabe benötigt wird, verarbeiten Sie zunächst dieses Kapitel und testen Sie den Nutzen, bevor Sie das gesamte Buch einbeziehen.
• Wenn das Buch stark versionsabhängige Beispiele enthält, legen Sie die Version im Skill ausdrücklich offen und markieren Sie Stellen, die gegen aktuelle Dokumentation geprüft werden müssen.
• Wenn der Skill sowohl erklären als auch automatisch Dateien verändern soll, trennen Sie Wissensregeln von ausführbaren Skripten. Ein Skript gehört nur dann in scripts/, wenn der Vorgang wiederholbar, deterministisch und technisch kontrollierbar ist.

Ein gutes Zielstatement lautet beispielsweise: „Dieser Skill unterstützt Sie dabei, Datenbankmigrationen anhand definierter Voraussetzungen zu planen, Risiken zu markieren und einen Prüfbericht mit Kapitelreferenzen zu erstellen.“ Ein schlechtes Zielstatement wäre: „Dieser Skill enthält das Wissen des Buches über Datenbanken.“

Extraktion mit Quellenregister

Die Extraktion ist nicht abgeschlossen, sobald Text aus einer PDF-Datei kopiert wurde. Sie benötigen eine Struktur, mit der Sie jede spätere Aussage zurückverfolgen können. Speichern Sie deshalb mindestens:

• Dokument-ID oder Dateiname,
• Kapitel und Unterkapitel,
• Seitenzahl oder interne Position,
• erkannte Überschrift,
• Absatztyp,
• Codeblock,
• Tabelle,
• Abbildung oder Bildunterschrift,
• OCR-Status,
• mögliche Extraktionsfehler.

Bei einer PDF mit echter Textebene sollten Sie zunächst die normale Textextraktion verwenden. Bei gescannten Seiten ist OCR ein nachgelagerter Fallback. Die offizielle Dokumentation zur PDF-Textextraktion weist darauf hin, dass aus Bildseiten zunächst eine OCR-Textseite erzeugt werden muss, bevor der Text normal weiterverarbeitet werden kann.

OCR darf nicht stillschweigend über das gesamte Dokument laufen. Die OCR-Dokumentation beschreibt OCR als ungefähr 1.000-mal langsamer als normale Textextraktion. Das ist ein konkreter Kosten- und Laufzeitgrund, zuerst Seiten mit brauchbarer Textebene zu verarbeiten und OCR nur für erkannte Scan- oder Bildseiten einzusetzen.

Ein robustes Extraktionsschema kann so aussehen:

Beachten Sie eine typische PDF-Falle: Die sichtbare Leserichtung entspricht nicht immer der Reihenfolge, in der Zeichen intern gespeichert sind. Die Dokumentation zur Textverarbeitung nennt genau diese Abweichung als häufiges Problem. Deshalb müssen mehrspaltige Seiten, Tabellen und Codebeispiele stichprobenartig visuell kontrolliert werden.

Wissensmodell für Regeln und Abläufe

Nach der Extraktion sollten Sie nicht sofort einen Fließtext zusammenfassen. Ordnen Sie jede relevante Information mindestens einer Kategorie zu:

• Definition: Was bedeutet ein Begriff?
• Voraussetzung: Was muss vorher gegeben sein?
• Prinzip: Welche allgemeine Idee erklärt das Vorgehen?
• Prozessschritt: Was soll in welcher Reihenfolge geschehen?
• Entscheidungsregel: Unter welcher Bedingung ist Option A besser als Option B?
• Ausnahme: Wann gilt die Regel nicht?
• Gegenbeispiel: Welche scheinbar passende Anwendung ist ungeeignet?
• Version: Für welche technische Umgebung gilt die Aussage?
• Beleg: Wo im Buch lässt sich die Aussage prüfen?

Diese Klassifikation ist der wichtigste Schutz gegen Wissensverfälschung. Ein Buch kann etwa schreiben, dass ein Verfahren „bei kleinen Datenmengen oft ausreichend“ ist. Daraus darf Ihr Skill nicht die uneingeschränkte Anweisung ableiten, dieses Verfahren immer zu verwenden.

Formulieren Sie Regeln außerdem mit ihren Bedingungen:

Nicht:
„Verwenden Sie immer Verfahren A.“

Besser:
„Wenn die Eingabedaten klein sind und keine parallele Verarbeitung benötigt wird,
prüfen Sie zuerst Verfahren A. Bei hohen Datenmengen oder strengen Latenzvorgaben
wechseln Sie zu Verfahren B und dokumentieren Sie die Entscheidung.“

Vermeiden Sie es, unbelegte Verbindungen zwischen zwei Kapiteln zu erfinden. Wenn das Buch Architektur und Monitoring getrennt behandelt, darf der Skill diese Themen nur dann als feste Kausalkette verbinden, wenn die Quelle dies ausdrücklich trägt oder Sie die Verbindung als eigene, zu prüfende Ableitung kennzeichnen.

Aufbau von SKILL.md und Referenzen

Der Kern von SKILL.md sollte nicht zum digitalen Ersatzbuch werden. Die Spezifikation empfiehlt, umfangreiche Details in Referenzdateien auszulagern. Für den Hauptteil werden weniger als 5.000 Tokens empfohlen; zusätzlich sollte die Datei unter 500 Zeilen bleiben. Diese Grenzen sind keine Qualitätsgarantie, aber ein nützlicher Kontrollpunkt gegen überladene Skills. Sie sind in der Dokumentation zur Progressive Disclosure beschrieben.

Eine sinnvolle Aufteilung sieht so aus:

technische-architektur/
├── SKILL.md
├── references/
│   ├── begriffe.md
│   ├── entscheidungsregeln.md
│   ├── versionen.md
│   └── quellenregister.md
├── scripts/
│   └── validate-output.py
└── assets/
    └── berichtsvorlage.md

In SKILL.md gehören:

1. der Name und eine präzise Beschreibung,
2. eindeutige Auslöser für die Aktivierung,
3. die erwarteten Eingaben,
4. der Kernprozess,
5. Regeln für Unsicherheit und fehlende Voraussetzungen,
6. Hinweise, wann eine Referenzdatei geladen werden soll,
7. das erwartete Ausgabeformat.

In references/ gehören ausführliche Begriffsdefinitionen, Kapitelzusammenfassungen, Tabellen, Gegenbeispiele, Versionsnotizen und das Quellenregister. Die offizielle Vorlage für SKILL.md zeigt die minimale Struktur mit YAML-Frontmatter und Markdown-Anweisungen.

Die Beschreibung im Frontmatter ist besonders wichtig, weil sie als primärer Aktivierungsmechanismus dient. Sie sollte nicht nur das Thema nennen, sondern auch die Aufgaben und typischen Eingaben beschreiben. Eine präzise Beschreibung verhindert, dass der Skill bei fachlich ähnlichen, aber nicht passenden Anfragen automatisch verwendet wird.

Skripte und deterministische Prüfschritte

Ein scripts/-Verzeichnis ist nur sinnvoll, wenn der Vorgang wiederholt und mit festen Regeln ausgeführt werden kann. Geeignet sind beispielsweise:

• Prüfung, ob jede Wissenskarte eine Fundstelle besitzt,
• Validierung von YAML-Frontmatter,
• Erkennung leerer Referenzlinks,
• Vergleich von Kapitelnummern zwischen Inhaltsverzeichnis und Extraktion,
• Erzeugung einer Testfallvorlage,
• Prüfung, ob eine Ausgabe definierte Pflichtfelder enthält.

Nicht geeignet ist ein Skript, das ohne klare Kriterien automatisch entscheidet, welche Aussage „wichtig“ ist. Diese Auswahl bleibt eine fachliche Prüfung. Die Dokumentation zur Verwendung von Skripten in Skills empfiehlt relative Pfade vom Skill-Verzeichnis und eine klare Beschreibung der Abhängigkeiten.

Wenn ein Skript Code aus dem Buch enthält, prüfen Sie Lizenz, Sicherheit und Aktualität separat. Ein Beispielbefehl aus einem älteren Kapitel sollte nicht ungeprüft in eine ausführbare Automatisierung übernommen werden.

Kompression und Faktenprüfung

Die erste Zusammenfassung ist nur ein Arbeitsentwurf. Gehen Sie anschließend Kapitel für Kapitel durch und stellen Sie fünf Fragen:

1. Wurde jede wichtige Voraussetzung übernommen?
2. Sind Empfehlungen weiterhin als Empfehlungen formuliert?
3. Sind Ausnahmen und Gegenbeispiele sichtbar?
4. Ist die Version oder der historische Kontext erhalten?
5. Ist die Aussage im Quellenregister auffindbar?

Nutzen Sie für die Prüfung eine Stichprobe statt nur einer abschließenden Gesamtlektüre. Wählen Sie beispielsweise Abschnitte mit vielen Tabellen, Fußnoten, Codeblöcken und einschränkenden Formulierungen. Gerade dort entstehen beim Komprimieren die meisten Fehler.

Löschen Sie Inhalte, die nicht zur definierten Zielaufgabe beitragen. Ein Kapitel kann fachlich interessant sein und trotzdem außerhalb des Skill-Scopes liegen. Wenn Sie alles aufnehmen, wird der Skill schwerer auszulösen, langsamer zu nutzen und schwieriger zu testen.

Ein nützlicher Qualitätsstatus für jede Wissenseinheit ist:

[geprüft] Aussage mit direkter Fundstelle und bestätigter Bedingung
[offen] Aussage extrahiert, aber noch nicht gegen die Quelle geprüft
[versionsabhängig] Aussage gilt nur für einen dokumentierten Stand
[abgeleitet] eigene Verbindung, nicht wörtlich aus der Quelle übernommen
[verworfen] außerhalb des Zielauftrags oder nicht belastbar

Damit sehen Sie auch Monate später, welche Teile aktualisiert werden müssen.

Abnahme mit realen Aufgaben

Ein Skill ist erst einsatzbereit, wenn er Aufgaben zuverlässig bearbeitet. Erstellen Sie Testfälle aus vier Gruppen:

• Direkte Quellenfragen: Eine Antwort lässt sich in einem einzelnen Kapitel finden.
• Kapitelübergreifende Aufgaben: Der Agent muss Definitionen, Bedingungen und Prozessschritte verbinden.
• Grenzfälle: Eine Voraussetzung fehlt oder ein Versionshinweis macht die Standardempfehlung unsicher.
• Nicht passende Aufgaben: Das Thema ähnelt dem Skill, liegt aber außerhalb seines Scopes.

Für jeden Testfall dokumentieren Sie Eingabe, erwartete Kernaussage, notwendige Fundstellen, erlaubte Unsicherheit und unerwünschte Schlussfolgerungen. Vergleichen Sie anschließend eine Ausführung ohne Skill mit einer Ausführung mit Skill.

Bewerten Sie mindestens diese Kriterien:

• fachliche Richtigkeit,
• vollständige Berücksichtigung von Bedingungen,
• nachvollziehbare Fundstellen,
• korrektes Laden von Referenzdateien,
• Einhaltung des Ausgabeformats,
• keine erfundenen Buchaussagen,
• angemessene Reaktion auf nicht passende Aufgaben.

Die Dokumentation zur Skill-Evaluierung beschreibt Tests als eigene Qualitätsstufe und betont, dass ein Skill nicht nur plausibel klingen, sondern anhand realer Eingaben geprüft werden muss.

Ein konkreter Abnahmesatz lautet: „Der Skill muss bei einer Aufgabe über zwei Kapitel hinweg beide notwendigen Bedingungen nennen, mindestens eine Fundstelle liefern und bei fehlender Voraussetzung nachfragen oder die Unsicherheit ausdrücklich markieren.“ Das ist messbarer als „Der Skill soll gute Antworten geben“.

Typische Fehlversuche

Volltext als Referenzpaket

Ein kopierter Volltext ist noch kein Wissensmodell. Er enthält redundante Erklärungen, Layoutfehler und möglicherweise unzulässige Textmengen. Besser sind thematisch getrennte Referenzdateien mit eigenen Formulierungen und Fundstellen.

Zusammenfassung ohne Bedingungen

Eine kurze Regel ist nicht automatisch eine gute Regel. Prüfen Sie jedes „immer“, „nie“, „direkt“ und „am besten“. Häufig muss dort eine Bedingung, ein Ausnahmefall oder ein Versionshinweis ergänzt werden.

OCR ohne Stichprobe

OCR kann Zeichen, Tabellen und Code verändern. Die technische Extraktion muss deshalb gegen das Seitenbild geprüft werden. Besonders kritisch sind Minuszeichen, Einrückungen, Kommata, Dezimalpunkte, Fußnoten und ähnliche Zeichen.

Zu breite Aktivierungsbeschreibung

Wenn die Beschreibung nur das Fachgebiet nennt, kann der Skill bei zu vielen Aufgaben aktiviert werden. Beschreiben Sie stattdessen konkrete Tätigkeiten, Eingaben und erwartete Ergebnisse.

Kein Negativtest

Ein Skill, der jede thematisch ähnliche Anfrage beantwortet, ist nicht zuverlässig. Testen Sie bewusst Aufgaben, bei denen der Skill nicht verwendet werden sollte. So erkennen Sie Überaktivierung und unzulässige Übertragung von Regeln.

Betrieb auf einer kontrollierten Umgebung

Bei einzelnen Kapiteln reicht oft ein lokaler Rechner. Sobald Sie mehrere Bücher, OCR-Läufe, Referenzgenerierung und wiederholte Evaluationen verarbeiten, entstehen jedoch Anforderungen an Speichertrennung, Zugriffsrechte, Protokollierung und reproduzierbare Laufzeitumgebungen.

Ihr aktueller Ansatz hat dann möglicherweise drei Nachteile: Der lokale Rechner wird während OCR und Testläufen blockiert, vertrauliche Dokumente landen in gemeinsam genutzten Verzeichnissen, und wiederholte Skill-Tests konkurrieren mit Ihrer normalen Entwicklungsarbeit. Eine beliebige öffentliche Cloud ist ebenfalls nicht automatisch besser, wenn Speicherort, Löschkonzept und Zugriffskontrolle nicht zu Ihren Datenschutzanforderungen passen.

Für temporäre oder teamweite Verarbeitung kann eine isolierte Mac-Umgebung von Macstripe sinnvoller sein als die Umrüstung Ihres Hauptrechners: Sie erhalten eine getrennte Arbeitsumgebung für Dokumentenverarbeitung, können Testläufe reproduzierbar organisieren und müssen nicht dauerhaft lokale Hardware für sporadische OCR- oder Evaluationsaufgaben vorhalten. Prüfen Sie vorab trotzdem, ob Ihre Unterlagen diese Verarbeitungsform erlauben, welche Zugriffsrechte benötigt werden und ob eine lokale Verarbeitung für Ihr Projekt vorzuziehen ist. Informationen zur verfügbaren Umgebung finden Sie im Macstripe-Hilfezentrum.

Wenn Sie die Umgebung für längere Verarbeitungsläufe einrichten, sollte die Reihenfolge klar bleiben: erst Zugriff und Löschfristen festlegen, dann Original und Ableitungen trennen, anschließend Extraktion und Skill-Evaluation protokollieren. Für die technische Einrichtung können Sie die Bestellung der passenden Konfiguration prüfen; das ist besonders dann relevant, wenn OCR und wiederholte Testläufe nicht auf Ihrem täglichen Arbeitsgerät laufen sollen.