Technisch boek omzetten naar een agent-skill

Een technisch boek omzetten naar een agent-skill: wat u krijgt

Om een technisch boek om te zetten naar een agent-skill, wijst u een converter aan naar een PDF, een EPUB, een DOCX-export of een map met interne documenten die u al bezit. Deze schrijft een skill-directory: één invoerbestand met de benoemde frameworks en een index van de hoofdstukken, en één bestand per hoofdstuk dat de agent alleen leest wanneer uw vraag daarom vraagt. Het boek komt nooit in het contextvenster terecht. De index wel.

Dit is het tegenovergestelde van het vanaf nul schrijven van een agent-skill, waarbij u een procedure codeert die u al kent. Hier bestaat de kennis al en kan niemand erbij: een PDF van een leverancier van 800 pagina's, of een handboek dat niet meer is geopend sinds de auteur ervan vertrok. Het werk bestaat uit compressie en indexering. Als de term skill nieuw voor u is, lees dan eerst wat een agent-skill daadwerkelijk is.

De converter die hier wordt gebruikt is book-to-skill, een onder de MIT-licentie uitgebrachte skill die op uw eigen machine draait. De huidige tag per augustus 2026 is v1.4.0. De structuur die deze produceert is belangrijker dan de tool zelf, en de laatste sectie voor de FAQ laat zien hoe u dezelfde structuur handmatig opbouwt.

Waarom het tokenbudget de basis vormt van het ontwerp

Een boek dat in een contextvenster wordt geplakt, verbruikt bij elk gesprek de volledige omvang ervan. Een skill kost eenmalig het invoerbestand, plus de hoofdstukken die de vraag daadwerkelijk aansnijden. Het project hanteert een budget voor elk gegenereerd bestand.

[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

Het invoerbestand, SKILL.md, is beperkt tot 4,000 tokens en bevat de benoemde frameworks en de hoofdstukindex. Elk hoofdstukbestand is ongeveer 1,000 tokens groot en blijft op de schijf staan totdat erom wordt gevraagd. De ondersteunende bestanden zijn vergelijkbaar: 1,500 tokens voor glossary.md, 2,000 voor patterns.md, 1,000 voor cheatsheet.md.

Deze budgetten sluiten aan bij de manier waarop Claude Code daadwerkelijk context verbruikt. Het description-bestand van een skill staat in de skill-lijst, zodat het model weet dat de skill bestaat. De inhoud wordt geladen wanneer de skill wordt aangeroepen en blijft na het laden voor de rest van de sessie in de context aanwezig; elke regel in het invoerbestand is dus een terugkerende kostenpost. Ondersteunende bestanden worden alleen geladen wanneer de agent ze leest, wat de per-hoofdstuk-bestanden goedkoop maakt.

Er is een hardere limiet voor het aantal tokens in het invoerbestand. Wanneer automatische compressie een lang gesprek samenvat, voegt Claude Code na de samenvatting de meest recente aanroep van elke skill opnieuw toe. Het behoudt de eerste 5.000 tokens van elke skill, binnen een gezamenlijk budget van 25.000 tokens voor alle opnieuw toegevoegde skills. Een invoerbestand dat binnen 5.000 tokens past, overleeft de compressie volledig. Een invoerbestand van 20.000 tokens keert terug als het eerste kwart, en er is geen indicatie welke drie kwart zijn verdwenen.

Dit is progressieve onthulling: een kleine index die zijn kosten altijd waard is, en het grootste deel van de informatie achter een deur die de agent bewust opent. Hoe Claude Code het contextvenster beheert behandelt de rest van deze verantwoording.

Installeer de converter op uw VPS, vastgezet op een release

De skill is een git-repository. Kloon deze naar de directory met skills van de agent die u gebruikt. De naam van de directory wordt het slash-commando, dus het pad voor het klonen is geen kwestie van persoonlijke voorkeur.

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch accepteert een tag, dus dit checkt v1.4.0 uit en niets daarna. Zet dit vast, want een skill is een set instructies die uw agent volgt, en een ongecontroleerde wijziging in die instructies is een wijziging in wat er op uw server draait. GitHub Copilot CLI leest in plaats daarvan ~/.copilot/skills/, en Amp leest ~/.agents/skills/.

Er is ook een installatie via één regel, npx skills add virgiliojr94/book-to-skill, die de huidige versie ophaalt. Gebruik deze om de tool uit te proberen. Gebruik de vastgezette kloon voor alles wat u opnieuw uitvoert.

Bevestig nu welke extractors de server heeft:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check rapporteert welke extractors zijn geïnstalleerd en print het installatiecommando voor elk exemplaar dat ontbreekt. Het pakket vereist Python 3.9 of nieuwer.

Als /book-to-skill niet verschijnt in de automatische aanvulling na het klonen, herstart dan uw agent. Claude Code houdt de skill-directories in de gaten die bestonden toen de sessie startte, dus een ~/.claude/skills/ die u twee minuten geleden hebt aangemaakt, wordt nog niet gecontroleerd.

Welke extractors heeft u daadwerkelijk nodig?

Er is niets vereist buiten Python, omdat elk formaat een fallback in de standaardbibliotheek heeft. De fallbacks presteren minder goed, en op een kleine server is het zonde van de tijd om extractors te installeren die u niet gebruikt.

• pdftotext, uit het poppler-utils-pakket, verwerkt tekstrijke PDF's en is vrijwel onmiddellijk klaar. Installeer dit met sudo apt install poppler-utils.
• pypdf en pdfminer.six zijn de Python-fallbacks voor PDF.
• docling is bedoeld voor technische PDF's waarvan de waarde in de tabellen en codelists zit. Het project meet een verwerkingstijd van ongeveer 1,5 seconde per pagina.
• ebooklib met beautifulsoup4 leest EPUB correct. Zonder deze tools valt de software terug op de zipfile-lezer uit de standaardbibliotheek.
• python-docx leest DOCX en striprtf leest RTF.
• Calibre's ebook-convert is vereist voor MOBI- en AZW-bestanden.
• ocrmypdf voert OCR (optische tekenherkenning) uit op een gescand boek dat geen tekstlaag bevat.

Op Ubuntu 24.04 stopt een standaard pip3 install pypdf met de volgende melding:

error: externally-managed-environment

Dit betekent niet dat pip defect is. Ubuntu en Debian markeren de systeem-Python als beheerd door apt, waardoor pip weigert hierin te schrijven. Twee oplossingen werken. sudo apt install poppler-utils installeert een binary en heeft helemaal geen pip nodig, en pdftotext verwerkt de meeste tekst-PDF's zelfstandig. Voor de Python-extractors bouwt u een virtuele omgeving en start u uw agent vanuit die omgeving, zodat de python3 die de skill aanroept de interpreter is die de pakketten bevat.

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

De repository declareert de extra's pdf, epub, docx, rtf, technical en all, waarbij technical gelijk is aan docling. De installatiepagina van het project toont ook pip install "book-to-skill[pdf,epub,docx]", maar die naam is per augustus 2026 niet gepubliceerd op PyPI; installeer deze daarom vanaf uw eigen checkout zoals hierboven beschreven.

Laat docling achterwege totdat een boek dit vereist. Het trekt een machine learning-stack aan, dus controleer de vrije schijfruimte op een klein abonnement voordat u het installeert.

Uitvoeren op een map met documenten, inclusief headless

Het commando accepteert een bestand, een map, een glob tussen aanhalingstekens of meerdere paden tegelijk, gevolgd door een optionele skill-naam. Alles wat u in één map kunt plaatsen werkt, inclusief een RFC-set (Request for Comments, de documenten die internetprotocollen definiëren).

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

Plaats de glob tussen aanhalingstekens zodat uw shell deze niet uitbreidt voordat de skill deze ziet. Als u het commando naar een bestaande skill-map wijst, worden de nieuwe bronnen aan die skill toegevoegd in plaats van dat er een tweede wordt aangemaakt.

Een interactieve run stelt u vragen. Is het materiaal technisch of tekstintensief? Dit bepaalt de extractor. Wilt u referentiediepte of studiediepte? Dit bepaalt het budget per hoofdstuk. Hoe moet de skill heten en in welke skill-root moet deze worden geplaatst? Het toont ook een schatting van het aantal tokens en de tijd vóór de generatie en wacht op uw bevestiging.

Een headless run heeft niemand om deze vragen te beantwoorden. Door de gebruiker aanroepbare skills werken in claude -p: plaats het slash-commando in de prompt-string en Claude Code breidt dit uit voordat de run start. Beantwoord de vragen dus in dezelfde prompt.

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools keurt de tools die de run nodig heeft vooraf goed, omdat een toestemmingsvraag zonder gekoppelde terminal een run is die nooit eindigt. Het toevoegen van --output-format json plaatst total_cost_usd in het resultaat; dit is een schatting aan de client-zijde in plaats van uw factuur.

Extractie consolideert elke bron in een tijdelijke werkmap onder /tmp voordat een model deze leest, en de laatste stap van de run verwijdert die map. Een bron die niet kan worden geëxtraheerd, wordt overgeslagen zodat de batch behouden blijft. Dit betekent dat een run succes kan rapporteren terwijl er minder bestanden zijn gelezen dan u heeft aangeleverd. Vergelijk de bestandsinventaris in het eindrapport met wat er in de map staat. Een ontbrekend hoofdstuk is meestal een ontbrekende bron.

Geef de run een server die u met een gerust hart aan een agent toevertrouwt. Veilig uitvoeren van Claude Code op een VPS behandelt de kant van de rechten hiervoor.

Waar de output terechtkomt zodat uw coding agent deze vindt

De gegenereerde skill wordt in een skills-root geplaatst. Twee daarvan zijn van belang.

• ~/.claude/skills/<skill-name>/ is persoonlijk en beschikbaar in elk project op die machine.
• .claude/skills/<skill-name>/ bevindt zich in een repository en reist daarmee mee.

In beide gevallen krijgt u SKILL.md, een chapters/-directory met één bestand per hoofdstuk, en de ondersteunende bestanden. De directorynaam is het commando, dus ~/.claude/skills/platform-handbook/ geeft u /platform-handbook, en u kunt dit laten volgen door een onderwerp of een eenvoudige vraag.

Kies de root op basis van licenties in plaats van gemak. Een skill die is gebouwd op basis van een boek dat u heeft gekocht, hoort in uw persoonlijke directory. Een skill die is gebouwd op basis van documentatie die uw eigen team heeft geschreven, hoort in de repository, wat het delen van één skill over meerdere repositories tot het volgende op te lossen probleem maakt.

Eén kostenpost groeit met elke skill die u toevoegt. De beschrijving van elke skill blijft in de skill-lijst staan zodat het model kan besluiten deze te gebruiken, de gecombineerde beschrijvingstekst wordt afgekapt op 1.536 tekens per item, en de lijst als geheel heeft een budget. Tien boek-skills betekent tien beschrijvingen die daarom strijden. Voor de skills die u altijd bij naam aanroept, voegt u één regel toe aan de gegenereerde frontmatter:

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

Met disable-model-invocation: true blijft de beschrijving volledig buiten de context, en de skill wordt nog steeds volledig geladen wanneer u /platform-handbook typt. U geeft automatische detectie op en krijgt een rustiger contextvenster.

Licenties: MIT is van toepassing op de converter, niet op het boek

Wees hier nauwkeurig in, want het falen op dit punt is geen technisch probleem.

• De MIT-licentie is van toepassing op de code van de converter en de definitie van de skill. Deze zegt niets over het document dat u invoert.
• Het uitvoeren van de converter op een boek dat u heeft gekocht, op hardware die u beheert, is het maken van aantekeningen uit uw eigen exemplaar.
• Het publiceren van het resultaat is distributie, en de MIT-licentie op de tool verleent u geen enkel recht om materiaal te distribueren dat is afgeleid van het boek van iemand anders.
• De output is een afgeleid werk. Frameworks en samenvattingen van hoofdstukken worden nog steeds gevormd door de bron, en een afgeleid werk valt nog steeds onder het auteursrecht van de bron.
• Een skill die is gebouwd op basis van materiaal dat u niet mag herdistribueren, blijft op de machine staan waarop deze is gebouwd. Niet in een openbare repository. Niet in een gedeelde team-marketplace.
• Publiceer alleen wanneer de bron van u is of openlijk gelicentieerd: documentatie die uw team heeft geschreven, of een standaard waarvan de voorwaarden herdistributie toestaan.

De tool is hieromheen gebouwd. Deze levert geen boekinhoud mee, extractie vindt lokaal plaats en de publicatiestap vraagt naar de zichtbaarheid van de repository als een afzonderlijke vraag die alleen het letterlijke woord public of private accepteert in plaats van dit zelf te bepalen. Behandel die prompt als de beslissing over de licentie, want dat is wat het is.

Interne handboeken brengen een tweede probleem met zich mee. Ze bevatten vaker inloggegevens dan men toegeeft, en een converter verandert een PDF die niemand opent in een bestand dat uw agent op verzoek leest. Lees de gegenereerde bestanden eenmaal door voordat u ze commit, en bekijk geheimen buiten uw AI-agents houden.

Wat kost één conversie?

De onderstaande cijfers zijn de eigen gepubliceerde metingen van het project en niet die van ons.

[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

Over de 4 boeken die het project heeft gemeten, kostte één conversie tussen de 0.88 en 1.42 Amerikaanse dollar, waarbij Pro Git op 1.23 uitkwam. De cijfers zijn gemeten op Claude Sonnet 4.5, met tokentellingen van tiktoken met gebruik van cl100k_base, en ze zijn gepubliceerd in de docs/performance.md van het project per augustus 2026. Uw eigen getal varieert afhankelijk van uw model en uw prijzen.

Het project documenteert ook 24 tot 51 keer minder tokens om een enkele vraag te beantwoorden op basis van de vaardigheid dan wanneer het hele boek in de context wordt geplakt. Zie dit als een indicatie van de besparing in plaats van een garantie, aangezien het afhangt van het boek en de vraag. Het structurele punt blijft in beide gevallen staan: voor conversie wordt eenmalig betaald, terwijl voor een context-dump bij elk gesprek dat het boek nodig heeft opnieuw wordt betaald.

Waarom niet de PDF plakken of een RAG-index bouwen?

Plakken werkt, en het is het juiste antwoord voor één vraag over één document. Het is niet langer het juiste antwoord wanneer hetzelfde boek op dinsdag en opnieuw op vrijdag nodig is, omdat u elke keer voor de volledige omvang betaalt.

Retrieval, of RAG (retrieval augmented generation), zoekt op het moment van de query en geeft de passages terug die overeenkomen met uw woorden. Dat is sterk wanneer u de exacte zin nodig heeft. Het is zwak wanneer het nuttige onderdeel een framework is dat over een hoofdstuk verspreid staat, omdat geen enkele passage dit volledig bevat. Een skill voert die extractie één keer uit, op het moment van conversie, en slaat de structuur op in plaats van de passages.

De eerlijke grens: een gegenereerde skill is een verlieslatende samenvatting geschreven door een model. Het is een studiehulpmiddel, en de bron blijft de bron. Wanneer de exacte bewoording juridisch of protocolair gewicht draagt, behoud dan de PDF en citeer daaruit. Skills vergeleken met MCP-servers en rules-bestanden behandelt waar elke aanpak thuishoort.

Foutmodi en de meldingen die u zult zien

Een gescande PDF levert niets op. De extractor controleert de eerste pagina's op een tekstlaag en stopt met een uitleg in plaats van 400 pagina's aan afbeeldingen te verwerken. Voer eerst ocrmypdf input.pdf output.pdf uit en voer daarna het resulterende bestand in.

pip weigert te installeren. error: externally-managed-environment op Ubuntu 24.04 is apt dat de systeem-Python beschermt. Gebruik de bovenstaande virtuele omgeving of installeer poppler-utils en sla pip volledig over.

De hoofdstukken komen verkeerd naar voren. Hoofdstukdetectie zoekt naar expliciete koppen zoals Chapter 7 en de taalvarianten daarvan. Een boek dat gebruikmaakt van kale sectietitels of Romeinse cijfers zorgt voor een slechte splitsing; de oplossing is om tijdens de uitvoering aan te geven waar de hoofdstukken beginnen in plaats van te hopen dat het systeem dit correct raadt.

Het commando bestaat niet. Als /book-to-skill ontbreekt in de autocomplete, betekent dit dat de directory met skills is aangemaakt nadat uw sessie was gestart. Start de agent opnieuw.

Docling duurt erg lang. Met ongeveer 1,5 seconde per pagina kost het minuten aan CPU-tijd voor een lang boek, en op een gedeelde server concurreert die taak met alles wat u verder host. Antwoord "text-heavy" wanneer de uitvoering vraagt naar het inhoudstype, of geef --mode text mee wanneer u scripts/extract.py zelf aanstuurt. --mode technical is het antwoord waarmee u docling selecteert.

Een bron verdwijnt geruisloos. Een bestand dat niet gelezen kan worden, wordt overgeslagen zodat de batch kan voltooien. De uitvoering rapporteert vervolgens succes over minder bronnen dan u had aangeleverd, en de enige plek waar dit zichtbaar is, is de bestandsinventaris in het eindrapport.

Pas hetzelfde patroon handmatig toe

De tool is een hulpmiddel voor het gemak. De structuur is het overdraagbare onderdeel, en met een teksteditor bouwt u deze voor elk referentiemateriaal waarover u beschikt.

1. Schrijf één invoerbestand en bewaar dit in de buurt van de 4,000 tokens waarop de converter zich richt. Plaats de benoemde concepten hierin met hun exacte formuleringen, plus een index met een lijst van elk detailbestand en de onderwerpen die dat bestand bevat.
2. Splits het materiaal in bestanden van ongeveer 1,000 tokens, één onderwerp per bestand, zodanig benoemd dat de bestandsnaam alleen al aangeeft wat de inhoud is.
3. Beschrijf elk van die bestanden vanuit het invoerbestand, in de zin die aangeeft wanneer u het moet lezen.

Stap 3 is de stap die mensen overslaan, en het is de stap die het patroon laat werken. De agent kiest wat hij opent door de index te lezen, dus een bestand dat de index niet beschrijft, is een bestand dat de agent nooit opent. De index is het product en de hoofdstukbestanden zijn de opslag.

Houd het invoerbestand binnen het compressiebudget en de gehele structuur overleeft een lange sessie. Die regel geldt ongeacht of een converter de bestanden heeft geschreven of u zelf.

FAQ

Mag ik een skill publiceren die gebaseerd is op een boek dat ik heb gekocht?

Nee, tenzij de licentie van dat boek herdistributie toestaat. De MIT-licentie van de converter heeft betrekking op de code van de converter, niet op het materiaal dat u erin voert, en de gegenereerde skill is een afgeleid werk van het boek. Houd deze in ~/.claude/skills/ op uw eigen machine. Publiceren is toegestaan voor documentatie die u zelf heeft geschreven of voor bronnen met een open licentie. De tool vraagt als aparte vraag naar de zichtbaarheid van de repository en accepteert alleen een kale public of private, zodat de beslissing bewust blijft.

Heb ik docling nodig, of is pdftotext voldoende?

pdftotext uit poppler-utils is voldoende voor platte tekst en werkt vrijwel direct. Installeer docling wanneer de waarde van het boek in de tabellen en codefragmenten zit, omdat een eenvoudige tekst-extractor juist die onderdelen negeert. De afweging is snelheid: het project meet docling op ongeveer 1,5 seconde per pagina, dus een handleiding van 300 pagina's kost enkele minuten CPU-tijd op een VPS.

Waarom faalt pip met externally-managed-environment op mijn VPS?

Ubuntu 24.04 en huidige Debian-versies markeren de systeem-Python als beheerd door apt, waardoor pip weigert hierin te installeren en de melding error: externally-managed-environment geeft. Maak een virtuele omgeving aan met python3 -m venv ~/.venvs/book-to-skill, activeer deze, installeer de extractors daarin en start uw agent vervolgens vanuit diezelfde shell. De skill roept python3 aan, waardoor de interpreter wordt gebruikt die in uw PATH staat; dit is nu de interpreter in de virtuele omgeving.

Waarom verschijnt mijn gegenereerde skill niet als slash-commando?

Er zijn twee oorzaken. De naam van het commando is afgeleid van de mapnaam, dus de skill moet zich bevinden in ~/.claude/skills/<name>/SKILL.md of .claude/skills/<name>/SKILL.md, waarbij SKILL.md exact zo gespeld moet zijn. Als het pad correct is, herstart dan de agent. Claude Code detecteert wijzigingen in skill-mappen die al worden gemonitord, maar een skills-map die is aangemaakt nadat de sessie is gestart, wordt in het geheel niet gemonitord.