Come trasformare un libro tecnico in una skill per agenti

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 nominati e un indice dei capitoli, oltre a un file per ogni capitolo, che l'agente legge solo quando la domanda lo richiede. Il libro non entra mai nella finestra di contesto. L'indice sì.

È un'operazione 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 a raggiungerla: 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 usato in questo caso è book-to-skill, una skill distribuita con licenza MIT che viene eseguita sul proprio computer. Il tag corrente ad agosto 2026 è v1.4.0. La struttura prodotta è più importante dello strumento in sé 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.

[
  {
    "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 convertitore sul VPS a una release specifica

Lo skill è un repository Git. Clonalo nella directory skills dell'agent che utilizzi. 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 estrae v1.4.0 e nessuna versione successiva. Fissa la release, perché uno skill è un insieme di istruzioni che l'agent segue 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 recupera la versione corrente. Usala per provare lo strumento. Per qualsiasi esecuzione successiva, usa il clone con release fissata.

Ora verifica quali estrattori sono presenti sul server:

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

--check indica quali estrattori sono installati e stampa il comando di installazione per ciascun estrattore mancante. Il pacchetto richiede Python 3.9 o versioni successive.

Se /book-to-skill non compare nell'autocompletamento dopo la clonazione, riavvia l'agent. Claude Code monitora le directory degli skill presenti all'avvio della sessione, quindi una ~/.claude/skills/ creata due minuti fa non è ancora monitorata.

Quali estrattori servono realmente?

Non serve installare altro oltre a Python, perché ogni formato dispone di un fallback della libreria standard. I fallback sono meno efficienti e, su un server di dimensioni ridotte, il tempo sprecato deriva dall'installazione di estrattori che non servono.

• pdftotext, del pacchetto poppler-utils, gestisce i PDF con molto testo ed è quasi istantaneo. Installalo con sudo apt install poppler-utils.
• pypdf e pdfminer.six sono i fallback Python per i PDF.
• docling è destinato ai PDF tecnici il cui contenuto utile si trova nelle tabelle e negli elenchi di codice. Il progetto indica una velocità di circa 1.5 secondi per pagina.
• ebooklib con beautifulsoup4 legge correttamente gli EPUB. In loro assenza, lo strumento usa il lettore zipfile della libreria standard.
• python-docx legge i DOCX e striprtf legge gli RTF.
• Il comando ebook-convert di Calibre è necessario per i file MOBI e AZW.
• ocrmypdf esegue l'OCR (riconoscimento ottico dei caratteri) 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

Il problema non dipende da pip. Ubuntu e Debian contrassegnano Python di sistema come gestito da apt, quindi pip rifiuta di scrivervi. Sono disponibili due soluzioni. sudo apt install poppler-utils installa un binario e non richiede pip, mentre pdftotext gestisce autonomamente la maggior parte dei PDF con testo. Per gli estrattori Python, crea un ambiente virtuale e avvia l'agent al suo interno. In questo modo, python3 richiamato dallo skill è 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 repository dichiara gli extra pdf, epub, docx, rtf, technical e all, dove technical è docling. La pagina di installazione del progetto mostra anche pip install "book-to-skill[pdf,epub,docx]", ma ad agosto 2026 questo nome non è pubblicato su PyPI. Installa quindi il progetto dal tuo checkout, come indicato sopra.

Non installare docling finché non serve per un libro. 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 in modalità headless

Il comando accetta un file, una cartella, un glob tra virgolette o più percorsi contemporaneamente, seguito dal nome facoltativo di una skill. Puoi inserire in una directory qualsiasi contenuto, incluso 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 riceva. Se indichi una directory di skill già 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 composto soprattutto da testo: questa scelta determina l'estrattore. Chiede se vuoi una profondità di riferimento o di studio: questa scelta determina il budget per capitolo. Chiede inoltre quale nome assegnare alla skill e in quale skills root inserirla. Prima della generazione stampa anche una stima di token e tempo, quindi attende la conferma.

Un'esecuzione headless non ha nessuno che possa rispondere a queste domande. Le skill invocabili dall'utente funzionano in claude -p: inserisci il comando slash nella stringa del prompt e Claude Code lo espande prima dell'avvio. Devi quindi fornire le risposte 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 in anticipo gli strumenti necessari all'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 dell'importo addebitato.

L'estrazione consolida ogni fonte in una directory di lavoro temporanea sotto /tmp prima che qualsiasi modello la legga. L'ultimo passaggio dell'esecuzione elimina questa directory. Se una fonte non viene estratta, viene saltata per consentire la prosecuzione dell'elaborazione in batch. Di conseguenza, un'esecuzione può segnalare un esito positivo anche se ha letto meno file di quelli forniti. Confronta l'inventario dei file nel rapporto finale con il contenuto della cartella. Se manca un capitolo, di solito manca la relativa fonte.

Assegna all'esecuzione un server che sei disposto a mettere a disposizione di un agente. 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

Siate precisi su questo punto, perché qui 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 fornite.
• Eseguire il convertitore su un libro acquistato, usando hardware sotto il vostro controllo, equivale a prendere appunti dalla vostra copia.
• Pubblicare il risultato significa distribuirlo, e la licenza MIT dello strumento non vi concede alcun diritto di distribuire materiale derivato dal libro di terzi.
• L'output è un'opera derivata. Anche la struttura e le sintesi dei capitoli restano influenzate dalla fonte, e un'opera derivata continua a essere soggetta al copyright della fonte.
• Una skill creata a partire da materiale che non potete ridistribuire deve restare sul computer che l'ha creata. Non in un repository pubblico. Non in un marketplace condiviso dal team.
• Pubblicate solo quando la fonte è vostra o distribuita con una licenza aperta: documentazione scritta dal vostro team oppure uno standard i cui termini consentono la ridistribuzione.

Lo strumento è progettato tenendo conto di questo principio. Non include contenuti di libri, l'estrazione viene eseguita localmente e la procedura di pubblicazione chiede separatamente la visibilità del repository. Per questa scelta accetta soltanto la parola esatta public o private, senza dedurla automaticamente. Considerate quella richiesta come la decisione sulla 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 vostro agente legge quando necessario. Leggete una volta i file generati prima di eseguire il commit e consultate evitare di inserire secret nei vostri agenti AI.

Quanto costa una conversione?

I numeri riportati di seguito sono le misurazioni pubblicate dal progetto, non nostre.

[
  {
    "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 USA, con Pro Git a 1.23. Le misurazioni sono state effettuate con Claude Sonnet 4.5, usando i conteggi dei token di tiktoken tramite cl100k_base, e sono pubblicate nel docs/performance.md del progetto alla data di agosto 2026. Il costo effettivo varia in base al modello e ai prezzi applicati.

Il progetto documenta inoltre un numero di token da 24 a 51 volte inferiore per rispondere a una singola domanda usando la skill, rispetto all'inserimento dell'intero libro nel contesto. Considerate questo dato come l'ordine di grandezza del risparmio, non come una garanzia, perché dipende dal libro e dalla domanda. Il principio strutturale resta valido: la conversione viene pagata una sola volta, mentre il contenuto completo inserito nel contesto viene pagato di nuovo per ogni conversazione che richiede quel 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, se non lo trova, si interrompe mostrando una spiegazione invece di elaborare 400 pagine di immagini. Esegui prima ocrmypdf input.pdf output.pdf, quindi passa il file di output.

pip rifiuta l'installazione. Su Ubuntu 24.04, error: externally-managed-environment indica che apt sta proteggendo Python di sistema. Usa l'ambiente virtuale precedente oppure installa poppler-utils e non usare pip.

I capitoli vengono rilevati in modo errato. Il rilevamento cerca intestazioni esplicite come Chapter 7 e le relative varianti linguistiche. Un libro che usa semplici titoli di sezione o numeri romani viene suddiviso in modo errato. Per correggere il problema, indica al comando il punto di inizio dei capitoli invece di affidarti al rilevamento automatico.

Il comando non esiste. Se /book-to-skill non compare nel completamento automatico, la directory delle competenze è stata creata dopo l'avvio della sessione. Riavvia l'agent.

Docling impiega troppo tempo. Con circa 1.5 secondi per pagina, l'elaborazione di un libro lungo richiede diversi minuti di CPU. Su un server condiviso, inoltre, il processo compete con gli altri servizi ospitati. Quando il comando chiede il tipo di contenuto, rispondi "text-heavy", oppure passa --mode text se esegui 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. Il comando segnala quindi un completamento riuscito per un numero di fonti inferiore a quello fornito. L'unico punto in cui questa differenza è visibile è l'inventario dei file nel report finale.

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 dal libro. Conservala in ~/.claude/skills/ sul tuo computer. La pubblicazione è consentita per la documentazione scritta da te o per fonti distribuite con licenze aperte; inoltre, lo strumento chiede separatamente la visibilità del repository e accetta solo un public o private non racchiuso da altri valori, quindi la decisione resta consapevole.

Ho bisogno di docling oppure è sufficiente pdftotext?

pdftotext di poppler-utils è sufficiente per il testo in prosa ed è quasi immediato. Installa docling quando il valore del libro è 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 in circa 1.5 secondi per pagina, quindi un manuale di 300 pagine richiede diversi minuti di CPU su un VPS.

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

Ubuntu 24.04 e le versioni correnti di Debian contrassegnano Python di sistema come gestito da apt. Per questo pip rifiuta di installarvi pacchetti e stampa error: externally-managed-environment. Crea un ambiente virtuale con python3 -m venv ~/.venvs/book-to-skill, attivalo, installa lì gli estrattori, quindi avvia l'agente dalla stessa shell. La skill richiama python3, quindi usa l'interprete disponibile nel tuo PATH, che a questo punto è quello dell'ambiente virtuale.

Perché la skill generata non compare 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 quel modo. Se il percorso è corretto, riavvia l'agente. 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 affatto.