Convierte cualquier libro en una skill (book-to-skill)

Tienes libros técnicos que no has terminado.

No lo digo como reproche, lo digo porque yo también. El PDF de 400 páginas que compraste en una oferta de Black Friday, el EPUB que te recomendó aquel compañero, los tres papers que guardaste en una carpeta llamada “leer” y que ya llevan dos años ahí. Conocimiento comprado, pagado y guardado. Sin usar.

Y cuando por fin necesitas algo de ese libro, ¿qué haces? Abres el PDF, buscas por palabra clave y el visor te devuelve la página 213. No la respuesta: la página. Toca leer tres párrafos de contexto para entender de qué habla el autor y otros cinco para encontrar la regla que buscabas.

La alternativa moderna es peor de lo que parece: le pasas el libro entero a tu agente de IA. Funciona. Y te cuesta 200.000 tokens en cada turno de la conversación.

book-to-skill propone una tercera vía: compilar el libro una sola vez y convertirlo en una Agent Skill que tu agente carga por trozos, cuando le hace falta. Según los benchmarks del propio proyecto, la diferencia es de 24 a 51 veces menos tokens para responder a la misma pregunta.

Esto es lo que vas a encontrar aquí:

• Qué problema resuelve book-to-skill y por qué no es un RAG con otro nombre
• Cómo se instala y cómo compilar tu primer libro en una sesión
• Qué ficheros genera y cómo están pensados por dentro
• Los números reales de ahorro de tokens y cuánto cuesta compilar un libro
• Las limitaciones que nadie te cuenta (incluido el tema espinoso del copyright)

Vamos al lío.

¿Qué problema resuelve book-to-skill exactamente? ¶

book-to-skill es una Agent Skill (más un motor de extracción en Python) que convierte libros y documentos en otra Agent Skill estructurada, lista para que la consuman Claude Code, GitHub Copilot CLI, Amp y cualquier agente compatible con el estándar de Agent Skills. Está publicado bajo licencia MIT por Virgilio Jr en GitHub, y ronda las 11.000 estrellas tras pasar por Trendshift en mayo de 2026 como el décimo repositorio Python del día.

El problema que ataca tiene nombre propio en la documentación del proyecto: el impuesto del bucle de descubrimiento.

Piénsalo así. Tu agente necesita responder una pregunta concreta sobre un libro. Sin skill, tiene tres caminos y los tres son malos:

1. Volcar el libro entero al contexto: 119.000 tokens del Think Python 2, 256.000 de AI Engineering. Y no es un pago único, es un peaje que abonas en cada turno de la conversación.
2. Buscar a ciegas: grep, leer un trozo, no era, leer otro trozo, tampoco. El bucle de descubrimiento consume entre 12.000 y 78.000 tokens según los benchmarks del repositorio, y termina cuando termina.
3. No usar el libro: que es lo que hacemos casi siempre, seamos honestos.

book-to-skill mueve todo ese trabajo al momento de la compilación. Analiza la estructura del libro una vez, extrae los frameworks con el nombre exacto que les dio el autor, y escribe una skill donde el índice ya está resuelto. Cuando preguntas, el agente carga unos 4.000 tokens de núcleo más el capítulo que toque. Y ya.

🔑 La idea de fondo: paga el coste de navegación en tiempo de compilación, no en tiempo de consulta. Es exactamente el mismo principio por el que compilas un binario en vez de interpretar el código fuente en cada ejecución.

Si esto te suena a la conversación sobre eficiencia de contexto, es porque lo es. Ya hablamos de por qué más contexto no significa mejores resultados en el post sobre context rot: un agente con la ventana llena de ruido rinde peor que uno con menos información pero bien ordenada. book-to-skill es una herramienta de higiene de contexto disfrazada de conversor de libros.

Guía interactiva gratis

La ventana de contexto es donde se marca la diferencia

Si esto de gestionar el contexto te suena a chino, hay una parada entera del curso dedicada a la ventana de contexto y otra a las skills. 17 paradas interactivas y sales con una checklist a tu medida.

Entra en el curso gratis →

¿Qué ficheros genera y cómo están organizados? ¶

Aquí es donde se ve que el diseño está pensado y no improvisado. La skill resultante no es un tocho: es una estructura en capas donde cada fichero tiene un presupuesto de tokens asignado.

Lo residente en contexto es solo el SKILL.md. El resto entra cuando el agente lo pide. Es progressive disclosure de manual, el mecanismo que hace que las skills escalen donde un prompt gigante se ahoga.

Fíjate en un detalle de la especificación que me parece de cirujano: el SKILL.md tiene que quedar por debajo de 4.000 tokens y con lo más importante al principio, porque la compactación de contexto trunca por el final. Si el agente se queda sin ventana, lo que se pierde es la cola del documento. Así que los frameworks nucleares van arriba y los índices abajo. Eso no lo escribe quien ha leído sobre skills: lo escribe quien las ha visto romperse.

Cada capítulo sigue una plantilla fija con secciones como Idea central, Frameworks introducidos, Conceptos clave, Modelos mentales, Anti-patrones, Puntos clave y “Conecta con” (enlaces a otros capítulos). Si el libro es técnico, se añaden dos secciones más: ejemplos de código y tablas de referencia.

👉 ¿Y cómo se pone esto en marcha sin morir en el intento?

¿Cómo se instala y se compila el primer libro? ¶

Hay dos piezas y puedes usar solo una si quieres. La skill (para que tu agente ejecute el flujo completo) y el motor de extracción en Python (para usarlo suelto desde la terminal).

Para la skill, es un git clone en el directorio de skills de tu agente:

# Claude Code
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

# GitHub Copilot CLI
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill

# Ubicación cross-agent (Amp y compatibles)
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

Para el motor de extracción por separado, hay paquete en PyPI con extras por formato:

pip install "book-to-skill[pdf,epub,docx]"
book-to-skill --check   # te dice qué extractores tienes y cuáles te faltan

Ese --check es de las cosas que más agradeces. En vez de fallar a mitad de un PDF de 300 páginas, te lista de entrada qué parsers están disponibles en tu máquina y el comando exacto para instalar los que faltan. Detalle pequeño, ahorro de tiempo grande.

Con la skill instalada, la conversión es una línea:

# Un libro suelto
/book-to-skill ~/books/thinking.pdf

# Una carpeta entera de documentación interna, con nombre de skill
/book-to-skill ~/workspace/docs/ project-knowledge

# Un glob de papers fusionados en una única skill
/book-to-skill "~/papers/*.pdf" research-unified

# Incorporar un artículo nuevo a una skill que ya existe
/book-to-skill ~/new-article.pdf ~/.claude/skills/existing-skill

Y después consultas la skill como cualquier otra:

/thinking-fast-slow                      # carga los frameworks nucleares
/thinking-fast-slow "sesgo de disponibilidad"   # busca un concepto concreto
/thinking-fast-slow ch05                 # abre el capítulo 5

Durante el proceso, la skill te para en dos sitios a preguntarte cosas. La primera: ¿el libro es técnico o de prosa? Esa respuesta decide qué extractor se usa y qué presupuesto de tokens se asigna. La segunda: ¿para qué quieres la skill? Si es para consultar, se genera con profundidad reference (capítulos secos y rápidos); si es para aplicar y estudiar, con DEPTH=study, que añade ejemplos trabajados y engorda cada capítulo.

Entre medias hay un paso que agradecerás: una estimación de coste previa. Antes de lanzarse a generar, te enseña la proyección de tokens de entrada y salida. Sabes lo que va a costar antes de que empiece a costar.

¿Qué formatos traga y qué dependencias necesitas? ¶

La lista de formatos es amplia y el diseño es de “mejor herramienta primero, fallback de la librería estándar después”. Si no tienes instalado el parser bueno, no explota: usa uno peor y sigue adelante.

La diferencia entre los dos modos de PDF merece un párrafo, porque es donde más gente se equivoca. Sobre un PDF técnico de 103 páginas, el benchmark del proyecto mide que pdftotext termina en 0,1 segundos y captura cero tablas y cero bloques de código. Docling en modo técnico tarda 164 segundos y preserva 48 tablas y 36 bloques de código convertidos a markdown.

Si el libro es Moby Dick, usa pdftotext y a otra cosa. Si es Designing Data-Intensive Applications, esos tres minutos de Docling son la diferencia entre una skill útil y una skill que se ha comido justo la parte que te importaba.

⚠️ El modo de extracción es la decisión que más condiciona la calidad final. Un libro técnico procesado como prosa genera una skill que suena bien y no sirve para nada: las tablas de decisión y los ejemplos de código se han evaporado por el camino.

¿Cómo funciona por dentro? ¶

La arquitectura separa con nitidez dos mundos que suelen ir mezclados: lo determinista y lo agéntico.

Etapa 1, el extractor. Python puro, sin IA. scripts/extract.py es un wrapper fino que delega en un paquete modular (extractor/) con parsers por formato, detección de dependencias y manejo de errores por fuente. Procesa lo que le eches, fusiona todas las fuentes marcando los límites de cada una y escribe dos ficheros: full_text.txt con el texto combinado y metadata.json con páginas, palabras, estimación de tokens, capítulos detectados e índice.

Que un fichero falle no aborta el trabajo: se salta esa fuente y continúa con las demás. Cuando estás procesando una carpeta con 40 documentos internos de tu empresa, esa decisión de diseño vale su peso en oro.

Etapa 2, el generador. Aquí entra el agente, siguiendo los diez pasos numerados de la especificación: clasificar el tipo de contenido, estimar coste, analizar la estructura, preguntar el propósito, elegir nombre y ubicación, crear directorios, generar capítulos, generar ficheros de apoyo, escribir el SKILL.md maestro y limpiar.

Hay un paso 2.6 que me parece la joya escondida de todo el proyecto. Cuando el texto extraído supera los 50.000 tokens, el agente no lo carga entero: usa grep y sed para sondear secciones concretas del full_text.txt, como quien trabaja en un REPL. Preserva presupuesto de contexto para la fase que de verdad lo necesita, que es escribir los capítulos.

Es la misma filosofía de la herramienta aplicada a sí misma. Nada de volcar; sondear.

Y hay un paso 9.5 que dice mucho de la madurez del repositorio: un escaneo de seguridad sobre la skill recién generada antes de publicarla. Tiene todo el sentido, porque una skill generada a partir de un documento que no controlas es una superficie de ataque perfecta para una inyección de prompt. Si quieres profundizar en esa capa, SkillSpector hace justo ese trabajo de auditoría sobre cualquier skill antes de que la instales.

El repositorio también trae tools/validate_skill.py, que comprueba que el SKILL.md generado cumple las restricciones de cada host (tiene una opción --lens específica para Claude), y tools/discovery_tax.py, que es el que produce los números de los que hablamos ahora.

¿Cuánto ahorras de verdad en tokens? ¶

Vamos con los datos, que es donde este proyecto se juega la credibilidad. La metodología de discovery_tax.py mide los tokens necesarios para responder una sola pregunta dirigida, comparando tres estrategias sobre libros reales.

Los ~5.000 tokens salen de sumar los 4.000 residentes del SKILL.md más el capítulo que se cargue.

Mira la tercera fila con atención, porque cuenta la historia completa: cuanto más gordo y más técnico es el libro, mayor es la ventaja. Con un libro de 119.000 tokens el bucle de descubrimiento aguanta el tipo. Con uno de 256.000, la diferencia se dispara a 15 veces. La ventaja escala con el tamaño del capítulo, que es justo lo contrario de lo que hacen la mayoría de optimizaciones.

Un matiz honesto que conviene dejar claro: la comparación es “una pregunta, una vez”. Si vas a consultar el libro una sola vez en tu vida, compilar no compensa. El retorno aparece cuando esa consulta se repite, que es exactamente el perfil de la documentación interna, de los estándares de tu equipo o del libro de referencia que abres cada dos semanas.

¿Cuánto cuesta compilar un libro? ¶

Poco, y esto es lo que hace que la propuesta se sostenga. Con precios de Claude Sonnet 4.5 (3 y 15 dólares por millón de tokens de entrada y salida), los benchmarks del repositorio dan estas cifras:

La frase que resume el proyecto está en su documentación de rendimiento: “aproximadamente un dólar por libro, pagado una vez”.

Un euro escaso por convertir Pro Git en algo que tu agente consulta durante meses sin que se te vaya la ventana de contexto al garete. Comparado con lo que cuesta volcar 229.000 tokens en cada conversación en la que necesites algo de ese libro, no hay debate.

¿Por qué esto no es un RAG con otro nombre? ¶

Es la primera objeción que salta y el proyecto la contesta de frente. La diferencia no es de implementación, es de momento.

Un RAG trocea el documento, genera embeddings y, cuando preguntas, busca los fragmentos más parecidos a tu consulta. La inteligencia ocurre en tiempo de consulta y lo que te devuelve son trozos de texto original con buena puntuación de similitud.

book-to-skill hace el trabajo conceptual antes. Un modelo lee el libro, identifica los frameworks que el autor ha nombrado, los extrae con su nombre exacto y escribe reglas de decisión. Lo que te devuelve al consultar no son fragmentos: son principios con nombre propio y tablas de cuándo aplicar cada cosa.

Las reglas de calidad de la especificación insisten en ese punto hasta ser pesadas: “extrae estructura, no resúmenes”, “preserva la precisión del autor” (con un ejemplo perfecto: “Los 5 porqués” no es lo mismo que “iteración genérica”), “densidad sobre exhaustividad”, “voz de practicante” (escribe “usa X cuando Y”, no explicaciones pasivas) y, la más tajante, “nunca copies texto en bruto”.

Si te interesa esta frontera conceptual, en el post sobre las diferencias entre skills, prompts, MCP y subagentes desmenuzamos por qué cada una de estas herramientas resuelve un problema distinto aunque de lejos parezcan lo mismo.

Lleva tus skills al siguiente nivel

Una skill generada hay que saber leerla (y corregirla)

Estas reglas de calidad no son exclusivas de los libros: son las que separan una skill que tu agente usa de una que ignora. Te llevas el método para escribir tus propios SKILL.md, con progressive disclosure y compatibilidad con 25+ agentes.

Abrir la guía →

Acceso con suscripción Web Reactiva Premium · 15€/mes · Plantillas SKILL.md descargables incluidas

¿Qué presupuesto de tokens usa cada capítulo? ¶

La matriz de presupuestos es una de esas tablas que resumen una filosofía entera. Cruza el tipo de libro con la profundidad elegida:

Un capítulo de un libro técnico en modo estudio ocupa hasta tres veces más que uno de prosa en modo consulta. Y eso es correcto: si el capítulo trae código, tablas y un ejemplo trabajado, necesita sitio.

La consecuencia práctica: elige reference para lo que consultas al vuelo (documentación de APIs, estándares, manuales) y study para lo que quieres interiorizar (un libro de arquitectura, uno de diseño de sistemas). Si te equivocas, no pasa nada grave, pero acabarás con una skill demasiado gorda o demasiado seca.

¿Se puede ampliar una skill que ya existe? ¶

Sí, y es el modo que menos protagonismo tiene en el README pero más te va a servir a medio plazo. Se llama fold-in y es el cuarto modo de operación (los otros tres son conversión completa, solo análisis, y generar a partir de un análisis previo).

El flujo es cuidadoso:

1. Lee el SKILL.md existente y parsea el índice de capítulos, el de temas y los metadatos.
2. Distingue qué del material nuevo es revisión de algo que ya estaba y qué es capítulo nuevo.
3. Crea o actualiza los ficheros de capítulo, continuando la numeración desde el más alto existente.
4. Fusiona glossary.md, patterns.md y cheatsheet.md manteniendo el orden alfabético.
5. Regenera el SKILL.md con los índices actualizados y ejecuta el escaneo de seguridad.

Piensa en lo que eso habilita. Compilas la documentación de tu equipo hoy, y cada vez que alguien publica un ADR o una guía nueva, la incorporas a la misma skill. No es un snapshot muerto: es una base de conocimiento viva que crece por acumulación ordenada.

¿Qué no hace bien book-to-skill? ¶

Ninguna herramienta es solo virtudes, y aquí no vendemos humo. Estas son las arrugas que le veo.

La calidad depende del libro, no de la herramienta. Un libro bien estructurado, con capítulos claros y frameworks nombrados, produce una skill excelente. Un libro que es un flujo de conciencia de 300 páginas sin arquitectura interna produce una skill mediocre, por mucho Docling que le eches. El conversor extrae señal; si no hay señal que extraer, no la inventa.

El paso técnico es lento de verdad. Esos 164 segundos por 103 páginas de Docling no son un detalle: un libro técnico de 400 páginas se te va a más de diez minutos solo en la fase de extracción, antes de que el modelo escriba una línea. No es un problema, es una expectativa que conviene tener ajustada.

Necesitas revisar lo que sale. El generador es un modelo interpretando un libro. Puede confundir el nombre de un framework, mezclar dos conceptos parecidos o dejarse fuera una parte importante. Antes de convertir una skill en tu fuente de verdad, lee el SKILL.md completo y hojea un par de capítulos contra el original.

Y el elefante en la habitación: el copyright. El proyecto es transparente en este punto y hay que repetirlo. La extracción sucede en local (tus ficheros no salen de tu máquina, salvo que el backend de tu agente sea cloud, que suele serlo). La skill generada contiene frameworks sintetizados y definiciones, no pasajes literales. Y la licencia MIT cubre el conversor, no los documentos que procesas.

Traducido: compilar un libro que has comprado para uso personal es una cosa. Publicar esa skill en un marketplace para que se la descargue el mundo es otra muy distinta, y bastante fea con el autor que se pasó dos años escribiéndolo. Para documentación interna, material con licencia abierta o tus propios contenidos, no hay debate posible.

🛡️ Regla sencilla que no falla: si el libro lo compraste, la skill es tuya y se queda en tu máquina. Si la vas a compartir, que sea de documentación propia o de material con licencia que lo permita.

¿Para qué lo usarías tú de verdad? ¶

Salgamos de los libros un momento, porque creo que el nombre del proyecto le hace un flaco favor. Acepta carpetas y globs de documentos, no solo libros. Y ahí es donde le veo el verdadero recorrido para un equipo:

• Documentación interna dispersa: esos 40 markdown, ADRs y Confluence exportados que nadie lee. Compilados en una skill, tu agente los consulta sin que tú tengas que recordar dónde estaba cada cosa.
• Colecciones de papers: un glob de PDFs de investigación fusionados en una skill unificada, con glosario común y referencias cruzadas entre ellos.
• Estándares y especificaciones: RFCs, guías de estilo del equipo, normativa de accesibilidad. Material que se consulta en fragmentos, mil veces, y nunca de un tirón.
• El libro de referencia de tu stack: si trabajas a diario con una tecnología cuyo libro canónico te sabes a medias, esta es la mejor inversión de un euro que vas a hacer este mes.

Si andas buscando qué compilar primero, en la guía de los 40 mejores libros para developers hay unas cuantas fichas que encajan como un guante con este flujo.

Mi veredicto ¶

Lo que más me gusta de book-to-skill no es el ahorro de tokens, aunque los números sean contundentes. Es la idea de fondo: el conocimiento se compila.

Llevamos dos años metiendo cosas en la ventana de contexto como quien mete ropa en una maleta a presión, confiando en que el modelo encuentre lo que necesita. Este proyecto propone lo contrario: dedica un euro y diez minutos a estructurar el conocimiento una vez, y consúltalo barato durante meses. Es la diferencia entre buscar en una caja de zapatos y buscar en un archivador con pestañas.

No es magia, no arregla libros malos y hay que revisar lo que sale. Pero si tienes una estantería digital que no usas y un agente al que le cuesta encontrar las cosas, esto conecta ambos problemas de una manera que no había visto antes.

¿Cuál sería el primero que compilarías tú?

TL;DR ¶

• 📚 book-to-skill convierte libros, PDFs, EPUBs y carpetas de documentación en Agent Skills estructuradas para Claude Code, Copilot CLI y Amp
• ⚡ Usa entre 24 y 51 veces menos tokens que volcar el libro al contexto, y de 2,4 a 15,6 veces menos que un bucle de búsqueda, según los benchmarks del repositorio
• 💰 Compilar un libro cuesta alrededor de 1 dólar, pagado una sola vez
• 🧩 Genera un SKILL.md de ~4.000 tokens con los frameworks nucleares, más capítulos, glosario, patrones y cheatsheet que se cargan bajo demanda
• ⚠️ Elige bien el modo de extracción: en un PDF técnico, pdftotext tarda 0,1 s y pierde todas las tablas; Docling tarda 164 s y conserva 48 tablas y 36 bloques de código

Preguntas frecuentes sobre book-to-skill ¶

¿Qué es book-to-skill? ¶

Es una herramienta open source con licencia MIT que convierte libros y documentos (PDF, EPUB, DOCX, HTML, Markdown y más) en Agent Skills estructuradas. Genera un SKILL.md con los frameworks nucleares del libro más ficheros de capítulo, glosario, patrones y cheatsheet que el agente carga solo cuando los necesita.

¿Cómo se instala book-to-skill? ¶

Para usarlo como skill, se clona el repositorio en el directorio de skills de tu agente: git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill. Para usar solo el motor de extracción desde la terminal, se instala con pip install "book-to-skill[pdf,epub,docx]".

¿Cuántos tokens ahorra book-to-skill? ¶

Entre 24 y 51 veces menos tokens que volcar el documento completo en el contexto, y entre 2,4 y 15,6 veces menos que un bucle de búsqueda iterativa, medido sobre libros reales de 244 a 501 páginas. La ventaja crece con el tamaño y la densidad técnica del libro.

¿Cuánto cuesta convertir un libro en una skill? ¶

Alrededor de un dólar por libro con precios de Claude Sonnet 4.5, según la documentación de rendimiento del proyecto. Los libros medidos van de 0,88 dólares (Think Python 2) a 1,42 dólares (Moby-Dick), y es un coste único: la skill generada no vuelve a consumir nada de generación.

¿book-to-skill es lo mismo que un RAG? ¶

No. Un RAG trocea el documento y busca fragmentos parecidos en tiempo de consulta. book-to-skill analiza el libro una sola vez al compilar y extrae los frameworks del autor con su nombre exacto, más reglas de decisión. El resultado son ficheros markdown navegables, sin base vectorial ni embeddings.

¿Qué formatos de documento soporta? ¶

PDF, EPUB, DOCX, HTML, RTF, Markdown, reStructuredText, AsciiDoc y texto plano. Los formatos de e-reader (MOBI, AZW, AZW3) funcionan mediante Calibre. Texto plano, Markdown y reStructuredText no necesitan instalar ninguna dependencia extra.

¿Puedo procesar varios documentos a la vez? ¶

Sí. Acepta carpetas y patrones glob, y fusiona todas las fuentes en una única skill con glosario común e índice compartido. Es el caso de uso ideal para documentación interna dispersa o colecciones de papers relacionados.

¿Se puede añadir material nuevo a una skill ya creada? ¶

Sí, mediante el modo fold-in. Parsea el SKILL.md existente, distingue entre revisiones y capítulos nuevos, continúa la numeración desde el capítulo más alto y fusiona el glosario, los patrones y el cheatsheet manteniendo el orden alfabético.

¿Es legal convertir un libro con copyright en una skill? ¶

Para uso personal de un libro que has adquirido, el proyecto lo plantea dentro del uso legítimo: la extracción ocurre en local y la skill contiene frameworks sintetizados, no pasajes literales. Redistribuir skills generadas a partir de obras con copyright es otra cosa y el propio repositorio recomienda cautela. Documentación interna y material con licencia abierta no plantean ese problema.

¿Con qué agentes de IA funciona? ¶

Con Claude Code, GitHub Copilot CLI y Amp de forma oficial, y con cualquier agente compatible con el estándar abierto de Agent Skills. El propio conversor sondea siete u ocho ubicaciones habituales de skills en tu sistema y te pregunta cuál usar si encuentra varias.

Fuentes ¶

• Repositorio oficial de book-to-skill en GitHub
• Especificación completa del conversor (SKILL.md)
• Benchmarks de rendimiento y costes (docs/PERFORMANCE.md)
• Arquitectura del extractor y el generador (docs/ARCHITECTURE.md)

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter