Buch-zu-Skill-Konverter

Was macht Buch-zu-Skill-Konverter?

Wandle geschriebenes Wissen in handlungsorientierte Agenten-Skills um, indem du Struktur extrahierst – keine Zusammenfassungen erstellst.

Philosophie

Bücher enthalten kristallisiertes Fachwissen: Frameworks, Prinzipien und Techniken, deren Entwicklung Jahre gedauert hat. Dieser Skill extrahiert dieses Wissen in ein Format, das GitHub Copilot CLI, Amp, Claude Code, Hermes Agent oder ein anderer kompatibler Agent wiederholt nutzen kann.

Extrahiere Struktur, keine Zusammenfassungen. Ein Skill ist kein Buchbericht. Es ist ein Werkzeugkasten aus:

• Benannten Frameworks (mentale Modelle mit klarer Anwendung)
• Handlungsorientierten Prinzipien (Regeln, die Entscheidungen leiten)
• Techniken (Schritt-für-Schritt-Methoden)
• Anti-Patterns (was zu vermeiden ist und warum)
• Sprachkalibrierung (wie der Autor denkt und kommuniziert)

Bewahre die Präzision des Autors. Frameworks haben oft aus bestimmten Gründen spezifische Namen. "Die 5 Warums" ist nicht austauschbar mit "frage mehrmals warum." Erfasse die genaue Formulierung.

Schichte die Tiefe angemessen. Einfache Bücher → einfache Skills. Komplexe Bücher mit 10+ Frameworks → Skills mit Referenzdateien und bedarfsgesteuerten Kapiteln.

---

Betriebsmodi

Vier Pfade verfügbar. Entscheide basierend auf dem, was der Benutzer fragt:

1. Vollständige Konvertierung (Standard)

Auslöser: Benutzer gibt einen oder mehrere Dokument-/Verzeichnis-/Glob-Pfade ohne spezielle Anweisungen an Aktion: Führe alle untenstehenden Schritte aus (Schritte 0–9) Ausgabe: Kompletter Skill mit SKILL.md, chapters/, Glossar, Mustern, Spickzettel

2. Nur-Analyse

Auslöser: Benutzer sagt "analysieren", "nur extrahieren" oder "ich möchte vor der Generierung prüfen" Aktion: Führe Schritte 0–3 aus, erstelle dann einen strukturierten Extraktionsbericht (gefundene Frameworks, Prinzipien, Techniken). Stoppe – generiere KEINE Skill-Dateien. Ausgabe: Analysebericht zur Prüfung durch den Benutzer

3. Generierung aus vorheriger Analyse

Auslöser: Benutzer hat vorhandene Analyse-Notizen oder hat zuvor den Nur-Analyse-Modus ausgeführt Aktion: Überspringe Schritte 0–3, verwende die bereitgestellte Analyse als Eingabe, führe Schritte 4–9 aus Ausgabe: Skill-Dateien aus der bereitgestellten Analyse

4. Aktualisieren / Einpflegen (vorhandener Skill)

Auslöser: Benutzer gibt einen oder mehrere neue Quellpfade an und gibt an, einen vorhandenen Skill aktualisieren zu wollen (entweder durch Verweis auf den vorhandenen Skill-Ordner, Angabe eines Skill-Slugs, der bereits in SKILLS_HOME existiert, oder explizite Anfrage zur Aktualisierung). Aktion: Führe Schritt 0 (Nicht-zum-Bereich-Prüfung), Schritt 1 (Eingaben validieren), Schritt 1.5 (Buchtyp identifizieren) und Schritt 2 (neue Dateien extrahieren) aus. Fahre dann mit Schritt 5 fort (vorhandenen Skill-Pfad identifizieren/erkennen) und führe den Aktualisieren-/Einpflegen-Workflow aus, um die neuen Inhalte in die vorhandenen Skill-Dateien zu integrieren. Ausgabe: Aktualisierter vorhandener Skill mit neuen/überarbeiteten Kapitelzusammenfassungen und integrierten Indizes/Glossaren.

---

Skill-Speicherorte

Dieser Konverter kann von mehreren Skill-Systemen aus ausgeführt werden. Beim Suchen nach dem Hilfsskript dieses Converters oder beim Schreiben des generierten Buch-Skills bevorzuge diese Speicherorte in der angegebenen Reihenfolge:

1. GitHub Copilot CLI persönliche Skills: ~/.copilot/skills/
2. Agentenübergreifende persönliche Skills (Copilot, Amp, Codex): ~/.agents/skills/
3. Claude Code persönliche Skills: ~/.claude/skills/
4. Projekt-lokale Copilot Skills: .github/skills/
5. Projekt-lokale Claude Skills: .claude/skills/
6. Projekt-lokale Amp / Copilot Skills: .agents/skills/
7. Amp globale Skills: ~/.config/agents/skills/
8. Amp Legacy globale Skills: ~/.config/amp/skills/
9. Hermes Agent persönliche Skills: $HERMES_HOME/skills/ (Standardmäßig ~/.hermes/skills/)
10. Hermes Agent Projekt-Skills: .hermes/skills/ oder .agents/skills/

Für generierte Buch-Skills bevorzuge das benutzerbezogene agentenübergreifende Root ~/.agents/skills/ – eine physische Kopie bedient jeden unterstützten Host. Copilot CLI und Amp erkennen es nativ; Claude Code benötigt einen Symlink von ~/.claude/skills/<Skill-Name> (erstellt in Schritt 10, siehe Schritt 5 für die Regeln). Wähle ein host-privates oder projekt-lokales Root nur, wenn der Benutzer danach fragt.

---

Schritt 0 – Nicht-zum-Bereich-Prüfung

Wenn keine Argumente angegeben werden, stoppe und antworte:

"book-to-skill erfordert einen unterstützten Dokumentpfad, Ordner oder ein Glob-Muster. Verwendung: book-to-skill <Pfad-zum-Dokumentenordner-oder-glob>... [Skill-Name-Slug]"

Während des gesamten Workflows:

• Identifiziere die Eingabepfade und den optionalen Skill-Slug.
• Wenn das letzte Argument keine Datei, kein Ordner oder kein existierendes/einem Dateien entsprechendes Glob-Muster ist und wie ein Skill-Slug aussieht (z.B. Kleinbuchstaben-Bindestriche, alphanumerisch), behandele es als SKILL_NAME.
• Behandle alle anderen Argumente als die Liste der INPUT_PATHS.
• Wenn einer der Eingabepfade ein vorhandenes Skill-Verzeichnis ist (enthält SKILL.md und einen chapters/-Unterordner), oder wenn SKILL_NAME mit einem vorhandenen Skill-Slug in SKILLS_HOME übereinstimmt, kennzeichne diesen Durchlauf als Aktualisieren-/Einpflegen-Operation (Modus 4).

---

Schritt 1 – Eingabe validieren

Stelle sicher, dass sich unter den INPUT_PATHS mindestens eine unterstützte Datei, ein Verzeichnis oder ein Glob-Muster befindet. Für Verzeichnisse und Globs erweitere sie, um passende unterstützte Dateien zu finden (.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3).

Wenn keine unterstützten Dateien gefunden werden, stoppe mit einer klaren Fehlermeldung.

---

Schritt 1.5 – Inhaltstyp identifizieren

Frage den Benutzer vor der Extraktion:

"Welche Art von Inhalt haben diese Quellen? Dies hilft mir, die beste Extraktionsmethode zu wählen.

1. Technisch – enthält Code-Blöcke, Tabellen, Formeln, Diagramme (z.B. Programmierbücher, wissenschaftliche Arbeiten, Architekturanleitungen)
2. Textlastig – meist Prosa, wenige oder keine Tabellen/Code (z.B. Management, Produktivität, erzählende Sachbücher)
3. Nicht sicher – Ich verwende die schnelle Methode und warne dich, wenn die Qualität begrenzt erscheint"

Speichere die Antwort als BOOK_TYPE:

• Option 1 → BOOK_TYPE=technical
• Option 2 → BOOK_TYPE=text
• Option 3 → BOOK_TYPE=text

Wenn BOOK_TYPE=technical, informiere den Benutzer vor dem Fortfahren:

"📐 Technischer Modus ausgewählt – Verwende Docling für strukturierte Extraktion (Tabellen, Code-Blöcke, Formeln als Markdown erhalten). Dies dauert ~1,5s pro Seite, also erwarte ein paar Minuten für längere Quellen. Starte jetzt …"

Wenn BOOK_TYPE=text, informiere:

"📄 Textmodus ausgewählt – Verwende den schnellsten geeigneten Extraktor für jeden Dateityp. Klartext/Markdown/HTML sind meist in Sekunden bereit; PDFs verwenden pdftotext, wenn verfügbar."

---

Schritt 2 – Text aus den Quelldokumenten extrahieren

Führe das Extraktionsskript aus und übergib die Eingabepfade:

SCRIPT_PATH=""
HERMES_HOME_RESOLVED="${HERMES_HOME:-$HOME/.hermes}"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
HERMES_PROJECT_TRUSTED=false
if [ -n "$PROJECT_ROOT" ] && [ "${HERMES_AGENT:-}" = true ] && \
  command -v hermes >/dev/null 2>&1 && \
  command -v python3 >/dev/null 2>&1 && \
  hermes config get skills.trusted_project_dirs --json 2>/dev/null | PROJECT_ROOT="$PROJECT_ROOT" python3 -c 'import json, os, pathlib, sys; root=pathlib.Path(os.environ["PROJECT_ROOT"]).resolve(); sys.exit(not any(pathlib.Path(p).expanduser().resolve() == root for p in json.load(sys.stdin)))' 2>/dev/null
then
  HERMES_PROJECT_TRUSTED=true
fi

CANDIDATES=(
  "$HOME/.copilot/skills/book-to-skill/scripts/extract.py"
  "$HOME/.agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.claude/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED"/skills/*/book-to-skill/scripts/extract.py
)
if [ "${HERMES_AGENT:-}" != true ]; then
  CANDIDATES+=(
    ".github/skills/book-to-skill/scripts/extract.py"
    ".claude/skills/book-to-skill/scripts/extract.py"
    ".agents/skills/book-to-skill/scripts/extract.py"
  )
fi
CANDIDATES+=(
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
)
if [ "$HERMES_PROJECT_TRUSTED" = true ]; then
  CANDIDATES=(
    "$PROJECT_ROOT/.hermes/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.hermes/skills"/*/book-to-skill/scripts/extract.py
    "$PROJECT_ROOT/.agents/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.agents/skills"/*/book-to-skill/scripts/extract.py
    "${CANDIDATES[@]}"
  )
fi
for candidate in "${CANDIDATES[@]}"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "Konnte scripts/extract.py für book-to-skill nicht finden" >&2
  exit 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask

Vor der Extraktion prüft das Skript optionale Python-Pakete, die für das erkannte Format benötigt werden. Wenn ein besserer Extraktor fehlt, fordert es den Benutzer mit dem verfügbaren Fallback auf. Nicht-interaktive Sitzungen verwenden standardmäßig den Fallback, es sei denn, der Installationsmodus ist explizit yes.

Tipp – Umgebung vorbereiten: Führe "$PYTHON_BIN" "$SCRIPT_PATH" --check aus, um einen formatbezogenen Bericht zu erhalten, welche Extraktoren installiert sind und welcher Befehl zum Installieren fehlender Komponenten benötigt wird, ohne eine Datei zu verarbeiten. Nützlich, wenn ein Benutzer ein Einrichtungs- oder Qualitätsproblem meldet.

Dies erstellt ein durchlaufbezogenes Arbeitsverzeichnis – <tempdir>/book_skill_work-<pid>/ standardmäßig oder genau der Pfad, den du in BOOK_SKILL_WORKDIR gesetzt hast – das Folgendes enthält:

• full_text.txt – kombinierter extrahierter Text aller Quellen mit klar visuell abgegrenzten Grenzen.
• metadata.json – Gesamtgröße, Wörter, Seiten, Token-Anzahlen, verworfene EPUB-Bildanzahlen, das aufgelöste workdir und eine detaillierte Liste der einzelnen verarbeiteten sources.

Der Durchlauf gibt alle drei Pfade bei Abschluss aus (Workdir ->, Text ->, Meta ->). Übernimm die Pfade aus dieser Ausgabe (oder aus dem workdir-Feld von metadata.json) anstatt einen festen Speicherort anzunehmen – der Verzeichnisname unterscheidet sich pro Durchlauf, sodass gleichzeitige Extraktionen auf einem Rechner sich nicht gegenseitig überschreiben können.

Lies das metadata.json dieses Durchlaufs, um die Ergebnisse zu überprüfen.

Bestätige immer, dass die Extraktion das angeforderte Dokument ist, bevor du etwas generierst: Überprüfe filename / source_file in metadata.json oder den SOURCE:-Header in der ersten Zeile von full_text.txt. Wenn du auf einen Hintergrunddurchlauf wartest, warte auf dessen spezifisches Arbeitsverzeichnis – das Abfragen eines gemeinsamen Pfads könnte die Ausgabe eines anderen Durchlaufs anzeigen.

---

Schritt 2.5 – Kostenabschätzung vor dem Start

Lies das metadata.json dieses Durchlaufs (den Meta ->-Pfad aus der Extraktionsausgabe) und präsentiere dem Benutzer eine Schätzung vor der Generierung:

📖 Erkannte Quellen: <total_sources> Quelle(n)
<Liste der einzelnen Quelldateinamen und Formate aus der Quellen-Metadatenliste>
<wenn images_dropped > 5: warne, dass N Quellbilder nicht gelesen wurden>
📄 Kombinierte Seiten/Abschnitte: ~<N> | Wörter: ~<N> | Gesamte Token: ~<N>K

💰 Geschätzte Token-Kosten (Vollständige Konvertierung / Aktualisierung):
   Eingabe (Lesen + Prompts): ~<N>K Token
   Ausgabe (generierte/aktualisierte Skill-Dateien):  ~<N>K Token
   Gesamt:                           ~<N>K Token

   Kosten: Multipliziere die Token-Anzahlen oben mit den aktuellen
   Eingabe-/Ausgabe-pro-1M-Token-Raten deines Modells (Preise und Modellnamen ändern sich häufig –
   kodiere sie nicht hart; zitiere den heutigen Satz und kennzeichne ihn als Schätzung).

   ⏱  Geschätzte Zeit: ~<N> Minuten

📁 Zu generierende/aktualisierende Dateien:
   SKILL.md + Kapiteldateien + Glossar + Muster + Spickzettel

➡  Mit vollständiger Konvertierung / Aktualisierung fortfahren? (oder "nur analysieren" eingeben, um zuerst eine Vorschau zu erhalten)

So schätzt du ab:

• Eingabe-Token ≈ estimated_tokens aus Metadaten × 1,3 (Prompt-Overhead pro Kapiteldurchlauf)
• Ausgabe-Token ≈ Kapitel × Budget pro Kapitel + 4.000 (SKILL.md) + 4.500 (Glossar + Muster + Spickzettel)
  • Budget-Mittelwert pro Kapitel nach BOOK_TYPE (TIEFE wird später in Schritt 4 entschieden und kann es erhöhen): text ≈ 1.000, technical ≈ 1.800. Wenn der Benutzer bereits referenzorientiert vs. tiefes Studium angegeben hat, verwende die entsprechende Zeile der Schritt-7-Matrix.
• Kosten: Gib die Token-Anzahlen an und multipliziere sie mit den aktuellen Eingabe-/Ausgabe-pro-1M-Token-Raten des Benutzers. Kodiere KEINE Dollar-Beträge hart – Modellnamen und Preise ändern sich; wenn du einen anzeigst, kennzeichne ihn als Schätzung und datiere ihn.

Warte auf die Bestätigung des Benutzers, bevor du fortfährst. Wenn er "nur analysieren" sagt, wechsle zu Modus 2.

---

Schritt 2.6 – REPL-artiger Zugriff für große Bücher (> 50k Token)

Inspiriert vom Rekursiven Sprachmodell (RLM)-Paradigma: Behandle full_text.txt als abfragbares Korpus, nicht als einzelne Lektüre. Das Laden der gesamten Datei in den Kontext verbraucht Budget, das du später für die Generierung benötigst.

Für Bücher über ~50k Token bevorzuge programmatische Sonden gegenüber Read(full_text.txt) ohne Begrenzungen:

# Größenprüfung vor jedem Read
wc -w "$FULL_TEXT_PATH"

# Finde Kapitel-Offsets ohne die gesamte Datei zu laden
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# Rufe nur das benötigte Kapitel ab (Zeilen start..end inklusive)
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# Überprüfe, ob ein Framework tatsächlich erwähnt wird, bevor du es in SKILL.md beanspruchst
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# Gezieltes Read mit offset/limit vermeidet das Ausgeben der gesamten Datei
# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)

Verwende diesen Ansatz für Schritt 3 (Strukturanalyse), Schritt 7 (Kapitelzusammenfassungen) und Schritt 8 (Glossar / Muster-Extraktion). Bei Büchern unter 50k Token ist ein einzelnes Read in Ordnung.

Warum das wichtig ist: Ein 200-seitiges Buch entspricht ~75k Token. Es einmal pro Kapitel erneut zu lesen (28 Durchläufe) kostet ...