SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Come trasformare un libro tecnico in una skill per agenti

Converti PDF, EPUB, DOCX o documenti interni in una skill caricata su richiesta: installazione, budget di token, esecuzioni headless e licenza MIT.

Trasformare un libro tecnico in una skill per agenti: cosa si ottiene

Per trasformare un libro tecnico in una skill per agenti, si passa a un convertitore un PDF, un EPUB, un'esportazione DOCX oppure una directory di documenti interni già disponibili. Il convertitore crea una directory della skill: un file di ingresso contenente i framework denominati e un indice dei capitoli, oltre a un file per ogni capitolo, che l'agente legge soltanto quando la domanda lo richiede. Il libro non entra nella finestra di contesto. L'indice sì.

È un'attività opposta a scrivere una skill per agenti da zero, in cui si codifica una procedura già conosciuta. In questo caso, la conoscenza esiste, ma nessuno riesce ad accedervi: può trovarsi in un PDF del fornitore di 800 pagine oppure in un manuale che non viene aperto da quando la persona che lo ha scritto ha lasciato l'organizzazione. Il lavoro consiste nel comprimere e indicizzare i contenuti. Se il termine skill è nuovo, leggere prima che cos'è realmente una skill per agenti.

Il convertitore utilizzato in questa guida è book-to-skill, una skill con licenza MIT che viene eseguita sulla propria macchina. Il tag corrente a ottobre 2026 è v1.4.0. La struttura che produce è più importante dello strumento stesso e l'ultima sezione prima delle FAQ mostra come creare manualmente la stessa struttura.

Perché il budget di token determina l'intera progettazione

Un libro inserito in una finestra di contesto comporta il costo dell'intera dimensione a ogni conversazione che lo richiede. Una skill comporta il costo del relativo file di ingresso una sola volta, oltre a quello dei capitoli effettivamente interessati dalla domanda. Il progetto assegna un budget a ogni file che genera.

GraficoDocumented token budget per generated file, book-to-skill v1.4.0
I dati alla base di questo grafico
[
  {
    "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"
  }
]

Il file di ingresso, SKILL.md, è limitato a 4,000 token e contiene i framework indicati e l'indice dei capitoli. Ogni file di capitolo contiene circa 1,000 token e resta sul disco finché non viene richiesto. I file di supporto seguono lo stesso criterio: 1,500 token per glossary.md, 2,000 per patterns.md e 1,000 per cheatsheet.md.

Questi budget corrispondono al modo in cui Claude Code utilizza effettivamente il contesto. Il description di una skill compare nell'elenco delle skill, così il modello sa che la skill esiste. Il corpo viene caricato quando la skill viene invocata e, una volta caricato, resta nel contesto per il resto della sessione. Di conseguenza, ogni riga del file di ingresso rappresenta un costo ricorrente. I file di supporto vengono caricati solo quando l'agente li legge, ed è questo che rende convenienti i file separati per capitolo.

Esiste un limite più rigido alla base del valore del file di ingresso. Quando l'auto-compaction riepiloga una conversazione lunga, Claude Code ricollega al riepilogo l'invocazione più recente di ogni skill e conserva i primi 5.000 token di ciascuna, entro un budget combinato di 25.000 token per tutte le skill ricollegate. Un file di ingresso che rientra nei 5.000 token supera la compattazione senza essere troncato. Un file di ingresso da 20.000 token viene ripristinato per il primo quarto e nulla indica quali tre quarti siano andati persi.

Questa è la divulgazione progressiva: un indice piccolo, il cui costo è sempre giustificato, mentre la maggior parte del materiale resta dietro una porta che l'agente apre intenzionalmente. Come Claude Code gestisce la propria finestra di contesto illustra il resto di questo calcolo.

Installare il converter sul VPS, fissando una release

Il skill è un repository Git. Clonarlo nella directory skills dell'agente utilizzato. Il nome della directory diventa il comando slash, quindi il percorso di clonazione non è una scelta arbitraria.

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

--branch accetta un tag, quindi questo comando estrae v1.4.0 e nessuna versione successiva. Fissare la versione è importante perché uno skill è un insieme di istruzioni eseguite dall'agente, e una modifica non verificata a tali istruzioni cambia ciò che viene eseguito sul server. GitHub Copilot CLI legge invece ~/.copilot/skills/, mentre Amp legge ~/.agents/skills/.

È disponibile anche un'installazione su una sola riga, npx skills add virgiliojr94/book-to-skill, che scarica la versione corrente. Usarla per provare lo strumento. Per qualsiasi esecuzione successiva, usare il clone con versione fissata.

Ora verificare quali estrattori sono disponibili sul server:

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

--check indica quali estrattori sono installati e specifica cosa installare per quelli mancanti: un unico comando pip per i pacchetti Python mancanti e un'indicazione per ogni strumento di sistema mancante. Il pacchetto richiede Python 3.9 o versioni successive.

Se /book-to-skill non compare nel completamento automatico dopo la clonazione, eseguire /reload-skills oppure riavviare l'agente. Claude Code controlla le directory degli skill esistenti all'avvio della sessione; pertanto una directory ~/.claude/skills/ creata due minuti fa non è ancora monitorata.

Quali estrattori servono davvero?

Non serve altro oltre a Python, perché ogni formato dispone di un fallback nella libreria standard. I fallback sono peggiori; su un server di piccole dimensioni il tempo sprecato deriva dall'installazione di estrattori che non ti servono.

  • pdftotext, dal pacchetto poppler-utils, gestisce i PDF ricchi di testo ed è quasi istantaneo. Installalo con sudo apt install poppler-utils.
  • pypdf e pdfminer.six sono i fallback Python per i PDF.
  • docling serve per i PDF tecnici il cui valore è contenuto nelle tabelle e negli elenchi di codice. Il progetto indica un tempo di circa 1.5 secondi per pagina.
  • ebooklib con beautifulsoup4 legge correttamente gli EPUB. Senza questi pacchetti, lo strumento usa il lettore zipfile della libreria standard.
  • python-docx legge i file DOCX e striprtf legge i file RTF.
  • ebook-convert di Calibre è necessario per i file MOBI e AZW.
  • ocrmypdf esegue il riconoscimento ottico dei caratteri (OCR) su un libro acquisito tramite scansione, che non contiene alcun livello di testo.

Su Ubuntu 24.04, un semplice pip3 install pypdf si interrompe con questo messaggio:

error: externally-managed-environment

Non si tratta di un problema di pip. Ubuntu e Debian contrassegnano il Python di sistema come gestito da apt, quindi pip rifiuta di scriverci. Sono disponibili due soluzioni. sudo apt install poppler-utils installa un file binario e non richiede pip, mentre pdftotext gestisce autonomamente la maggior parte dei PDF in prosa. Per gli estrattori Python, crea un ambiente virtuale e avvia l'agente al suo interno, in modo che python3, richiamato dalla skill, sia l'interprete che contiene i pacchetti.

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

Il checkout v1.4.0 bloccato dichiara gli extra pdf, epub, docx, rtf, technical e all, dove technical è docling. La pagina di installazione del progetto documenta anche un'installazione autonoma da riga di comando direttamente da GitHub, pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", seguita da book-to-skill --check per elencare gli estrattori installati. Questa procedura non richiede una release PyPI, ma installa il branch predefinito del progetto invece di v1.4.0 e fornisce soltanto il comando dell'estrattore, non la skill /book-to-skill. Per un'installazione con versione bloccata, installa il progetto dal tuo checkout come indicato sopra. Un semplice pip install book-to-skill non funziona, perché a ottobre 2026 quel nome non è pubblicato su PyPI.

Lascia docling non installato finché un libro non ne richiede l'uso. Introduce uno stack di machine learning, quindi su un piano di piccole dimensioni controlla lo spazio libero su disco prima di installarlo.

Eseguilo su una cartella di documenti, anche senza interazione

Il comando accetta un file, una cartella, un glob tra virgolette oppure più percorsi contemporaneamente, seguito facoltativamente dal nome di una skill. È possibile usare qualsiasi contenuto inserito in una directory, compreso un insieme di RFC (request for comments, i documenti che definiscono i protocolli Internet).

/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

Racchiudi il glob tra virgolette per impedire alla shell di espanderlo prima che la skill lo elabori. Se specifichi una directory di skill esistente, le nuove fonti vengono aggiunte a quella skill invece di crearne una seconda.

Un'esecuzione interattiva pone alcune domande. Chiede se il materiale è tecnico o prevalentemente testuale, perché questa scelta determina l'estrattore. Chiede che cosa deve aiutarti a fare la skill, impostando il livello di riferimento o di studio e quindi il budget per capitolo. Chiede inoltre come deve chiamarsi la skill e, se non esiste ancora una skills root o se ce n'è più di una, in quale root deve essere inserita. Prima della generazione mostra anche una stima di token e tempo e attende la conferma.

Un'esecuzione headless non ha nessuno che possa rispondere a queste domande. Le skill invocabili dall'utente funzionano anche in claude -p: inserisci il comando slash nella stringa del prompt e Claude Code lo espande prima dell'avvio dell'esecuzione. Rispondi quindi alle domande nello stesso 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 approva preventivamente gli strumenti richiesti dall'esecuzione, perché una richiesta di autorizzazione senza un terminale collegato impedisce all'esecuzione di terminare. Aggiungendo --output-format json inserisci total_cost_usd nel risultato: si tratta di una stima lato client, non di un addebito.

Prima che il modello legga qualsiasi fonte, l'estrazione consolida tutte le fonti in una directory di lavoro temporanea sotto /tmp. L'ultimo passaggio dell'esecuzione elimina quella directory. Una fonte la cui estrazione non riesce viene ignorata, così l'elaborazione batch può continuare. Di conseguenza, un'esecuzione può segnalare il successo anche dopo aver letto meno file di quelli forniti. Confronta l'inventario dei file nel rapporto finale con il contenuto della cartella. Un capitolo mancante è solitamente una fonte mancante.

Esegui il comando su un server che sei disposto ad affidare a un agent. Eseguire Claude Code in sicurezza su un VPS illustra gli aspetti relativi alle autorizzazioni.

Dove viene salvato l'output, così il coding agent lo trova

Lo skill generato viene salvato in una directory radice degli skill. Due directory sono importanti.

  • ~/.claude/skills/<skill-name>/ è personale ed è disponibile in ogni progetto della macchina.
  • .claude/skills/<skill-name>/ si trova all'interno di un repository e viaggia insieme a esso.

In entrambe trovi SKILL.md, una directory chapters/ con un file per ogni capitolo e i file di supporto. Il nome della directory è il comando: quindi ~/.claude/skills/platform-handbook/ restituisce /platform-handbook, che puoi seguire con un argomento oppure con una domanda in linguaggio naturale.

Scegli la directory radice in base alla licenza, non alla praticità. Uno skill creato a partire da un libro che hai acquistato appartiene alla directory personale. Uno skill creato dalla documentazione scritta dal tuo team appartiene al repository. In questo caso, condividere uno skill tra più repository diventa il problema successivo da risolvere.

Un costo aumenta a ogni skill aggiunto. La descrizione di ogni skill resta nell'elenco degli skill, così il modello può decidere se usarlo. Il testo combinato delle descrizioni viene troncato a 1,536 caratteri per voce e l'elenco complessivo ha un limite di dimensione. Dieci skill basati su libri significano dieci descrizioni che competono per questo spazio. Per gli skill che richiami sempre per nome, aggiungi una riga al frontmatter generato:

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

Con disable-model-invocation: true la descrizione resta completamente fuori dal contesto e lo skill viene comunque caricato per intero quando digiti /platform-handbook. Rinunci al rilevamento automatico e ottieni una finestra di contesto meno rumorosa.

Licenza: MIT copre il convertitore, non il libro

Su questo punto è necessario essere precisi, perché il problema non è tecnico.

  • La licenza MIT copre il codice del convertitore e la relativa definizione della skill. Non dice nulla sul documento che gli fornisci.
  • Eseguire il convertitore su un libro che hai acquistato, usando hardware sotto il tuo controllo, equivale a prendere appunti dalla tua copia.
  • Pubblicare il risultato costituisce distribuzione, e la licenza MIT dello strumento non ti concede alcun diritto di distribuire materiale derivato dal libro di un'altra persona.
  • L'output è un'opera derivata. Anche la struttura e i riepiloghi dei capitoli restano modellati sulla fonte, e un'opera derivata continua a essere soggetta al copyright della fonte.
  • Una skill creata a partire da materiale che non puoi ridistribuire deve restare sulla macchina che l'ha generata. Non in un repository pubblico. Non in un marketplace condiviso dal team.
  • Pubblica il risultato quando la fonte è tua o distribuita con una licenza aperta: ad esempio, documentazione scritta dal tuo team oppure uno standard i cui termini consentono la ridistribuzione.

Lo strumento è progettato tenendo conto di questo principio. Non include contenuti di libri e l'estrazione viene eseguita localmente. Il valore predefinito v1.4.0 stampa soltanto una riga gh skill publish facoltativa e non chiede se il contenuto debba essere pubblico; quindi, in quel caso, la decisione spetta interamente a te. Da allora, il branch predefinito del progetto ha aggiunto un passaggio di pubblicazione che chiede la visibilità del repository con una domanda separata, a una sola parola, e crea un repository pubblico soltanto quando la risposta è la parola esatta public; qualsiasi altra risposta produce un repository privato. Considera quel passaggio come la decisione relativa alla licenza, perché è esattamente questo.

I manuali interni presentano un secondo problema. Contengono credenziali più spesso di quanto si ammetta, e un convertitore trasforma un PDF che nessuno apre in un file che il tuo agente legge quando necessario. Leggi una volta i file generati prima di eseguire il commit e consulta come impedire che i secret finiscano nei tuoi agenti AI.

Quanto costa una conversione?

I numeri riportati di seguito provengono dalle misurazioni pubblicate dal progetto, non da nostre misurazioni.

GraficoCost to convert one full-length book, as published by the project
I dati alla base di questo grafico
[
  {
    "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
  }
]

Nei 4 libri misurati dal progetto, una conversione è costata tra 0.88 e 1.42 dollari statunitensi, con Pro Git a 1.23. Le misurazioni sono state eseguite con Claude Sonnet 4.5, usando i conteggi dei token ottenuti da tiktoken tramite cl100k_base, e sono pubblicate nel docs/performance.md del progetto alla data di ottobre 2026. Il costo effettivo varia in base al modello e ai relativi prezzi.

Il progetto documenta inoltre un numero di token da 24 a 51 volte inferiore per rispondere a una singola domanda usando lo skill, rispetto all'inserimento dell'intero libro nel contesto. Questo dato indica l'ordine di grandezza del risparmio, non costituisce una garanzia, perché dipende dal libro e dalla domanda. Il principio strutturale resta valido: la conversione viene pagata una volta, mentre il contenuto completo inserito nel contesto viene pagato di nuovo per ogni conversazione che richiede il libro.

Perché non incollare il PDF o creare un indice RAG?

Incollare il contenuto funziona ed è la scelta corretta per una domanda su un singolo documento. Non è più la scelta corretta quando lo stesso libro serve martedì e di nuovo venerdì, perché ogni volta devi pagare il costo della sua dimensione completa.

Il retrieval, o RAG (retrieval augmented generation), esegue la ricerca al momento della query e restituisce i passaggi che corrispondono alle tue parole. È efficace quando ti serve la frase esatta. È meno efficace quando l'elemento utile è un framework distribuito lungo un capitolo, perché nessun singolo passaggio lo contiene. Una skill esegue questa estrazione una sola volta, durante la conversione, e memorizza la struttura anziché i passaggi.

Il limite va dichiarato chiaramente: una skill generata è un riepilogo con perdita di informazioni, scritto da un modello. È uno strumento di studio, mentre la fonte resta la fonte. Quando la formulazione esatta ha valore legale o è determinante per un protocollo, conserva il PDF e cita il testo da lì. Confronto tra skill, server MCP e file di regole spiega quale approccio usare in ciascun caso.

Modalità di errore e messaggi visualizzati

Un PDF acquisito tramite scansione non produce alcun risultato. L'estrattore verifica la presenza di un livello di testo nelle pagine iniziali e si interrompe mostrando una spiegazione, invece di elaborare 400 pagine di immagini. Eseguire prima ocrmypdf input.pdf output.pdf, quindi passare il file di output.

pip rifiuta l'installazione. Su Ubuntu 24.04, error: externally-managed-environment protegge il Python di sistema tramite apt. Usare l'ambiente virtuale creato in precedenza oppure installare poppler-utils e non usare pip.

I capitoli vengono rilevati in modo errato. Il rilevamento cerca titoli espliciti come Chapter 7 e le relative varianti linguistiche. Riconosce anche numeri romani come Chapter IV o IV. Title. Un libro che usa titoli di sezione privi di numerazione produce una suddivisione errata. Per correggere il problema, indicare al comando da dove iniziano i capitoli invece di affidarsi a una stima automatica.

Il comando non esiste. Se /book-to-skill non compare nell'autocompletamento, la directory delle skill è stata creata dopo l'avvio della sessione. Eseguire /reload-skills oppure riavviare l'agent.

Docling impiega troppo tempo. Con un tempo di circa 1.5 secondi per pagina, un libro lungo richiede diversi minuti di CPU. Su un server condiviso, l'elaborazione compete con tutti gli altri servizi ospitati. Quando l'esecuzione chiede il tipo di contenuto, rispondere "text-heavy". In alternativa, passare --mode text quando si esegue direttamente scripts/extract.py. --mode technical è la risposta che seleziona docling.

Una fonte scompare senza messaggi. Un file illeggibile viene ignorato per consentire il completamento dell'elaborazione batch. L'esecuzione segnala quindi il successo per un numero di fonti inferiore a quello fornito. L'unico punto in cui questa differenza è visibile è l'inventario dei file nel report finale. Verificare sempre il risultato di un'esecuzione confrontandolo con gli input effettivamente forniti è una pratica utile anche al di fuori di questo strumento. Il metodo Depth Tree della skill unlazy aiuta l'agent ad applicare lo stesso controllo, invece di dichiarare il lavoro completato in anticipo.

Applicare manualmente lo stesso schema

Lo strumento è solo una comodità. La struttura è la parte riutilizzabile e un editor di testo può crearla per qualsiasi materiale di riferimento in tuo possesso.

  1. Scrivi un file di ingresso e mantienilo vicino ai 4,000 token a cui mira il convertitore. Inserisci i concetti denominati usando la loro formulazione esatta, insieme a un indice che elenchi ogni file di dettaglio e gli argomenti contenuti.
  2. Suddividi il materiale in file di circa 1,000 token, con un argomento per file. Assegna nomi che permettano di capire il contenuto dal solo nome del file.
  3. Descrivi ciascuno di questi file nel file di ingresso, nella frase che indica quando leggerlo.

Il passaggio 3 è quello che molti saltano ed è proprio quello che fa funzionare lo schema. L’agente sceglie cosa aprire leggendo l’indice. Di conseguenza, un file che l’indice non descrive non viene mai aperto dall’agente. L’indice è il prodotto; i file dei capitoli sono l’archivio.

Mantieni il file di ingresso entro il budget di compattazione e l’intera struttura resterà utilizzabile durante una sessione lunga. Questa regola vale sia quando i file sono stati creati da un convertitore, sia quando li hai creati tu.

FAQ

Posso pubblicare una skill creata a partire da un libro che ho acquistato?

No, a meno che la licenza del libro ne consenta la ridistribuzione. La licenza MIT del convertitore copre il codice del convertitore, non il materiale che gli fornisci, e la skill generata è un'opera derivata del libro. Conservala in ~/.claude/skills/ sul tuo computer. La pubblicazione è consentita per la documentazione scritta da te o per le fonti distribuite con una licenza aperta. Il v1.4.0 fissato non chiede mai informazioni sulla visibilità, mentre il branch predefinito del progetto ora la richiede come domanda separata e rende il contenuto pubblico solo con un public vuoto; in ogni caso, la decisione deve essere presa consapevolmente.

Mi serve docling oppure è sufficiente pdftotext?

pdftotext di poppler-utils è sufficiente per la prosa ed è quasi istantaneo. Installa docling quando il valore del libro risiede nelle tabelle e negli elenchi di codice, perché un estrattore di testo semplice elimina proprio questi elementi. Il compromesso riguarda la velocità: il progetto misura docling a circa 1.5 secondi per pagina, quindi un manuale di 300 pagine richiede diversi minuti di tempo CPU su un VPS.

Perché pip restituisce l'errore externally-managed-environment sul mio VPS?

Ubuntu 24.04 e le versioni attuali di Debian indicano che Python di sistema è gestito da apt, quindi pip rifiuta di installarvi i pacchetti e stampa error: externally-managed-environment. Crea un ambiente virtuale con python3 -m venv ~/.venvs/book-to-skill, attivalo, installa gli estrattori al suo interno, quindi avvia il tuo agent dalla stessa shell. La skill richiama python3, quindi usa l'interprete presente nel tuo PATH, che ora è quello dell'ambiente virtuale.

Perché la skill generata non viene visualizzata come comando slash?

Le cause sono due. Il nome del comando deriva dal nome della directory, quindi la skill deve trovarsi in ~/.claude/skills/<name>/SKILL.md o .claude/skills/<name>/SKILL.md, con SKILL.md scritto esattamente in questo modo. Se il percorso è corretto, esegui /reload-skills oppure riavvia l'agent. Claude Code rileva le modifiche nelle directory delle skill che sta già monitorando, ma una directory delle skill creata dopo l'avvio della sessione non viene monitorata finché non esegui una di queste operazioni.

Questo articolo ti è stato utile?