Trasformare un documento in una skill per Claude Code, invece di incollarlo nel contesto
Una skill per Claude Code è un pacchetto di istruzioni e conoscenza che l'agente carica soltanto quando gli serve, invece di tenerlo fisso nel contesto a ogni richiesta. book-to-skill è un progetto open source, comparso a inizio agosto 2026 e arrivato in pochi giorni oltre le 24.800 stelle su GitHub, che prende un libro o un manuale in PDF e lo trasforma proprio in una di queste skill. Il punto interessante non è il tool in sé, è la domanda a cui risponde: come si dà a un assistente AI la conoscenza di un documento lungo senza incollarlo ogni volta, e pagarlo ogni volta.
Cos'è book-to-skill e cosa produce
book-to-skill è un convertitore da riga di comando che trasforma un documento in una skill strutturata, non in un riassunto. Accetta PDF, EPUB, DOCX, HTML, RTF, i formati Kindle MOBI e AZW, oltre a testo semplice, Markdown, reStructuredText e AsciiDoc. Da un singolo libro non produce un file solo, ma una piccola cartella pensata per essere letta a pezzi.
| File | Contenuto | Peso |
|---|---|---|
SKILL.md | modelli mentali e indice dei capitoli | ~4.000 token |
| un file per capitolo | il capitolo, caricato solo su richiesta | ~1.000 token |
glossary.md | termini chiave in ordine alfabetico | ~1.500 token |
patterns.md | tecniche e pattern ricorrenti | ~2.000 token |
cheatsheet.md | tabelle decisionali e regole rapide | ~1.000 token |
La differenza con il riassunto classico è che book-to-skill estrae framework, regole decisionali e anti-pattern invece di comprimere il testo, e tiene ogni capitolo in un file separato che l'agente apre solo quando la conversazione lo richiede. È compatibile con Claude Code, con la CLI di GitHub Copilot e con Amp, ed è distribuito con licenza MIT.
Perché una skill costa meno di un PDF nel contesto
Una skill costa meno di un PDF nel contesto perché l'agente non rilegge tutto il documento a ogni richiesta: apre l'indice, decide quale capitolo gli serve e carica solo quello. book-to-skill dichiara di usare da 24 a 51 volte meno token rispetto a mettere l'intero libro nel contesto, misurando su libri reali. È lo stesso ordine di grandezza che avevo trovato scrivendo di come ridurre i token di un agente di coding, e vale la stessa cautela: il termine di paragone è il caso peggiore, cioè incollare il libro intero, che quasi nessuno fa davvero.
Il guadagno vero non è solo in fattura. Un modello con davanti quattrocento token pertinenti ragiona meglio di uno con quarantamila token di contesto in gran parte inutile: la finestra piena non è un vantaggio, è rumore che peggiora la risposta. Dare la conoscenza a pezzi, con un indice che dice dove guardare, è la stessa idea del context engineering applicata ai documenti invece che al codice.
Come si trasforma un documento in una skill per Claude Code
Trasformare un documento in una skill per Claude Code, ridotto all'osso, vuol dire creare una cartella con un file indice e un file per ogni pezzo di conoscenza, e dire all'agente di aprire i pezzi solo quando servono. book-to-skill lo fa in automatico partendo dal file del libro, ma la struttura che genera si può ricostruire a mano per un manuale interno, ed è questa:
La regola che conta sta nel SKILL.md: lì non ci va la conoscenza, ci va la mappa di dove sta la conoscenza e quando andarla a prendere. Questo è anche il motivo per cui una skill non sostituisce un sistema RAG sugli archivi enormi, ma lo batte quando i documenti sono pochi, stabili e vanno letti per intero, come una procedura o un manuale operativo. Se invece il documento cambia ogni giorno, conviene ragionare su come dare i file all'API di Claude, che ha regole e scadenze diverse.
L'angolo: la conoscenza si compila, non si incolla
La direzione giusta, per chi costruisce con l'AI, è smettere di trattare i documenti come qualcosa da incollare e iniziare a trattarli come qualcosa da compilare una volta e consultare molte. Questo blog è l'esempio che ho sottomano. Le regole con cui vengono scritti gli articoli non stanno in un unico prompt gigante: stanno in .claude/skills/articolo/, divise fra un SKILL.md che fa da indice e i file linee-guida.md e seo-geo.md che l'agente apre soltanto quando deve scrivere davvero. È la stessa struttura che book-to-skill genera partendo da un libro.
La differenza pratica la vedo sul costo e sulla qualità insieme. Un prompt unico da ventimila token viaggia intero a ogni richiesta anche quando serve una riga sola, mentre una skill indicizzata porta con sé quasi niente finché non serve il pezzo giusto. È lo stesso principio con cui gestisco più sessioni di Claude Code che si parlano fra loro: meno contesto sempre acceso, più contesto giusto al momento giusto. Per un'azienda che ha manuali, procedure e normative da dare a un assistente AI, compilarli in skill è la versione ordinata di quello che spesso si fa buttando tutto in una chat, e sta al centro di come imposto l'AI sui dati aziendali.
La cautela: è un progetto giovane
book-to-skill non è l'unica strada per farlo, ed è giovane: è comparso da poche settimane e va guardato con la prudenza che merita ogni progetto con così poca storia alle spalle. Ma la domanda che porta è quella giusta, e non scade con il tool. La conoscenza che dai a un agente non deve essere grande, deve essere trovabile.
Fonte primaria: il repository virgiliojr94/book-to-skill su GitHub.
Domande frequenti
Cos'è una skill di Claude Code?
Una skill di Claude Code è una cartella con un file indice e uno o più file di conoscenza che l'agente carica solo quando la conversazione lo richiede. Non è un prompt sempre attivo, ma un pacchetto che sta fermo finché non serve. Lo standard Agent Skills è aperto, quindi la stessa cartella funziona anche con altri host, come la CLI di GitHub Copilot e Amp.
Serve saper programmare per creare una skill da un documento?
No. Una skill nel formato Agent Skills è fatta di file di testo in Markdown, e si può scrivere a mano senza scrivere codice. book-to-skill automatizza il passaggio partendo da un PDF o un EPUB, ma la struttura che genera, un indice più un file per capitolo, è ricostruibile da chiunque sappia scrivere un file di testo ordinato.
Come dare a un'intelligenza artificiale la conoscenza di un manuale aziendale senza incollarlo ogni volta?
Si compila il manuale una volta sola in una skill: un file indice che dice dove sta cosa, e i capitoli in file separati che l'assistente AI apre solo quando servono. Così la conoscenza non viaggia intera a ogni richiesta, ma viene letta a pezzi. È l'alternativa ordinata a incollare il documento in chat ogni volta, che costa token a ogni messaggio e riempie il contesto di materiale inutile.
Skill o RAG: che differenza c'è per dare conoscenza a un agente?
Una skill tiene la conoscenza in pochi file di testo che l'agente apre per intero quando servono, ed è adatta a documenti pochi e stabili come una procedura o un manuale. Un sistema RAG spezza gli archivi in frammenti e ne recupera solo pezzi via ricerca, ed è adatto a basi documentali enormi o che cambiano spesso. Sono due strumenti diversi, non uno migliore dell'altro.