Convertir un libro técnico en una skill de agente
Convierte un PDF, EPUB o carpeta de documentos en una skill que el agente carga bajo demanda. Incluye instalación, tokens, ejecuciones headless y licencias.
Convertir un libro técnico en una skill de agente: qué se obtiene
Para convertir un libro técnico en una skill de agente, se indica a un conversor un PDF, un EPUB, una exportación DOCX o una carpeta de documentos internos que ya posee. El conversor escribe un directorio de skill: un archivo de entrada que contiene los frameworks con nombre y un índice de los capítulos, además de un archivo por capítulo que el agente sólo lee cuando la pregunta lo requiere. El libro nunca entra en la ventana de contexto. El índice sí.
Este trabajo es lo contrario de escribir una skill de agente desde cero, donde se codifica un procedimiento que ya se conoce. Aquí el conocimiento existe, pero nadie puede acceder a él: un PDF de 800 páginas de un proveedor o un manual que no se ha abierto desde que se marchó la persona que lo escribió. El trabajo consiste en comprimir e indexar. Si el término skill es nuevo para usted, lea primero qué es realmente una skill de agente.
El conversor utilizado aquí es book-to-skill, una skill con licencia MIT que se ejecuta en su propia máquina. La etiqueta actual en octubre de 2026 es v1.4.0. La estructura que produce es más importante que la herramienta, y la última sección antes de FAQ muestra cómo crear la misma estructura manualmente.
Por qué el presupuesto de tokens define todo el diseño
Un libro pegado en una ventana de contexto consume todo su tamaño en cada conversación que lo necesita. Una skill consume su archivo de entrada una vez, además de los capítulos que la pregunta realmente requiere. El proyecto define un presupuesto para cada archivo que genera.
Los datos de este gráfico
[
{
"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"
}
]El archivo de entrada, SKILL.md, se limita a 4,000 tokens e incluye los marcos de trabajo identificados y el índice de capítulos. Cada archivo de capítulo tiene aproximadamente 1,000 tokens y permanece en el disco hasta que algo lo solicita. Los archivos de apoyo siguen un criterio similar: 1,500 tokens para glossary.md, 2,000 para patterns.md y 1,000 para cheatsheet.md.
Estos presupuestos coinciden con la forma en que Claude Code consume el contexto. El description de una skill aparece en el listado de skills para que el modelo sepa que existe. El contenido se carga cuando se invoca la skill y, una vez cargado, permanece en el contexto durante el resto de la sesión. Por eso cada línea del archivo de entrada genera un coste recurrente. Los archivos de apoyo sólo se cargan cuando el agente los lee, lo que hace que los archivos independientes por capítulo sean económicos.
Existe un límite más estricto relacionado con ese valor del archivo de entrada. Cuando la compactación automática resume una conversación larga, Claude Code vuelve a adjuntar la invocación más reciente de cada skill después del resumen y conserva los primeros 5,000 tokens de cada una, dentro de un presupuesto combinado de 25,000 tokens para todas las skills adjuntadas de nuevo. Un archivo de entrada que cabe en 5,000 tokens sobrevive completo a la compactación. Un archivo de entrada de 20,000 tokens reaparece con su primer cuarto, y nada indica qué tres cuartos se han perdido.
Eso es la divulgación progresiva: un índice pequeño cuyo coste siempre está justificado y la mayor parte del material detrás de una puerta que el agente abre de forma explícita. Cómo gestiona Claude Code su ventana de contexto explica el resto de ese cálculo.
Instale el convertidor en su VPS y fije una versión
La skill es un repositorio de git. Clónela en el directorio de skills del agente que utilice. El nombre del directorio se convierte en el comando slash, por lo que la ruta de clonación no es una elección arbitraria.
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch acepta un tag, por lo que este comando extrae v1.4.0 y ninguna versión posterior. Fije la versión porque una skill es un conjunto de instrucciones que sigue su agente, y un cambio no revisado en esas instrucciones modifica lo que se ejecuta en su servidor. GitHub Copilot CLI lee ~/.copilot/skills/, mientras que Amp lee ~/.agents/skills/.
También existe una instalación de una sola línea, npx skills add virgiliojr94/book-to-skill, que obtiene la versión actual. Úsela para probar la herramienta. Use el clon con la versión fijada para cualquier ejecución posterior.
Ahora confirme qué extractores están disponibles en el servidor:
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check informa de qué extractores están instalados y muestra qué debe instalar para los que faltan: un comando pip combinado para los paquetes de Python ausentes y una indicación para cada herramienta del sistema que falte. El paquete necesita Python 3.9 o una versión posterior.
Si /book-to-skill no aparece en el autocompletado después de clonar el repositorio, ejecute /reload-skills o reinicie el agente. Claude Code supervisa los directorios de skills que existían cuando se inició la sesión, por lo que todavía no supervisa una ~/.claude/skills/ que haya creado hace dos minutos.
¿Qué extractores necesita realmente?
No se necesita nada aparte de Python, porque todos los formatos tienen una alternativa basada en la biblioteca estándar. Estas alternativas ofrecen peores resultados. En un servidor pequeño, el tiempo se desperdicia al instalar extractores que no va a utilizar.
pdftotext, del paquetepoppler-utils, procesa PDFs con mucho texto y termina casi al instante. Instálelo consudo apt install poppler-utils.pypdfypdfminer.sixson las alternativas de Python para PDF.doclingestá pensado para PDFs técnicos cuyo valor está en las tablas y los listados de código. El proyecto estima un tiempo de aproximadamente 1.5 segundos por página.ebooklibjunto conbeautifulsoup4lee EPUB correctamente. Sin ellos, la herramienta recurre al lectorzipfilede la biblioteca estándar.python-docxlee DOCX ystriprtflee RTF.ebook-convertde Calibre es necesario para archivos MOBI y AZW.ocrmypdfejecuta OCR (reconocimiento óptico de caracteres) sobre un libro escaneado que no contiene ninguna capa de texto.
En Ubuntu 24.04, un pip3 install pypdf sin más se detiene con este mensaje:
error: externally-managed-environmentNo se trata de un fallo de pip. Ubuntu y Debian marcan el Python del sistema como gestionado por apt, por lo que pip no puede escribir en él. Hay dos opciones válidas. sudo apt install poppler-utils instala un binario y no necesita pip, y pdftotext procesa por sí solo la mayoría de los PDFs con prosa. Para los extractores de Python, cree un entorno virtual e inicie el agente desde dentro de él. Así, el python3 que utiliza la skill es el intérprete que tiene instalados los paquetes.
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]"
claudeEl checkout fijado de v1.4.0 declara los extras pdf, epub, docx, rtf, technical y all, donde technical es docling. La página de instalación del proyecto también documenta una instalación independiente desde la línea de comandos directamente desde GitHub, pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", seguida de book-to-skill --check para mostrar los extractores instalados. Esta opción no necesita una release de PyPI, pero instala la rama predeterminada del proyecto en lugar de v1.4.0 y sólo proporciona el comando del extractor, no la skill /book-to-skill. Para una instalación fijada, instale desde su propio checkout como se indicó antes. Un pip install book-to-skill sin más no funciona, porque ese nombre no está publicado en PyPI a fecha de octubre de 2026.
Deje docling fuera hasta que un libro lo necesite. Instala una pila de machine learning, así que compruebe el espacio libre en disco antes de instalarlo en un plan pequeño.
Ejecutarlo sobre una carpeta de documentos, también sin interacción
El comando acepta un archivo, una carpeta, un patrón glob entre comillas o varias rutas a la vez, seguidos de un nombre de skill opcional. Puede indicar cualquier contenido que pueda colocar en un directorio, incluido un conjunto de RFC (request for comments, los documentos que definen los protocolos de 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-researchPonga el patrón glob entre comillas para que el shell no lo expanda antes de que la skill lo reciba. Si indica una carpeta de skill existente, las nuevas fuentes se incorporan a esa skill en lugar de crear otra.
Una ejecución interactiva le hace preguntas. Debe indicar si el material es técnico o contiene mucho texto; esto determina el extractor. También debe indicar qué quiere hacer con la skill; esto define la profundidad de referencia o estudio y, con ella, el presupuesto por capítulo. Después debe indicar el nombre de la skill y, si todavía no existe una raíz de skills o hay más de una, la raíz en la que debe ubicarse. El comando también muestra una estimación de tokens y tiempo antes de generar el resultado y espera su confirmación.
En una ejecución sin interacción no hay nadie que responda esas preguntas. Las skills invocables por el usuario funcionan en claude -p: incluya el comando slash en la cadena del prompt y Claude Code lo expande antes de iniciar la ejecución. Por tanto, responda las preguntas en el mismo 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 aprueba previamente las herramientas que necesita la ejecución, porque un aviso de permisos sin un terminal conectado produce una ejecución que nunca termina. Si añade --output-format json, el resultado incluye total_cost_usd, que es una estimación del cliente y no de su facturación.
La extracción consolida todas las fuentes en un directorio de trabajo temporal bajo /tmp antes de que cualquier modelo las lea, y el último paso de la ejecución elimina ese directorio. Si una fuente no se puede extraer, se omite para que el lote continúe; por tanto, una ejecución puede informar de que ha terminado correctamente aunque haya leído menos archivos de los que proporcionó. Compare el inventario de archivos del informe final con el contenido de la carpeta. Si falta un capítulo, normalmente falta una fuente.
Proporcione a la ejecución un servidor que esté dispuesto a entregar a un agente. Ejecutar Claude Code de forma segura en un VPS explica los aspectos relacionados con los permisos.
Dónde se guarda la salida para que el agente de programación la encuentre
La skill generada se guarda en una raíz de skills. Hay dos ubicaciones importantes.
~/.claude/skills/<skill-name>/es personal y está disponible en todos los proyectos de esa máquina..claude/skills/<skill-name>/se encuentra dentro de un repositorio y se mueve junto con él.
Dentro de cualquiera de las dos encontrarás SKILL.md, un directorio chapters/ con un archivo por capítulo y los archivos auxiliares. El nombre del directorio es el comando, por lo que ~/.claude/skills/platform-handbook/ te proporciona /platform-handbook, y puedes añadirle un tema o una pregunta directa.
Elige la raíz según la licencia y no según la comodidad. Una skill creada a partir de un libro que compraste pertenece a tu directorio personal. Una skill creada a partir de documentación escrita por tu propio equipo pertenece al repositorio. Esto convierte compartir una skill entre varios repositorios en el siguiente problema que debes resolver.
Hay un coste que aumenta con cada skill que añades. La descripción de cada skill permanece en el listado de skills para que el modelo pueda decidir si la usa. El texto combinado de la descripción se trunca a 1,536 caracteres por entrada, y el listado completo tiene un presupuesto. Diez skills de libros implican diez descripciones que compiten por ese presupuesto. Para las skills que siempre llamas por nombre, añade una línea al frontmatter generado:
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---Con disable-model-invocation: true la descripción queda completamente fuera del contexto, y la skill se sigue cargando por completo cuando escribes /platform-handbook. Pierdes la detección automática, pero obtienes una ventana de contexto menos saturada.
Licencia: MIT cubre el conversor, no el libro
Sea exacto con esto, porque el problema no es técnico.
- La licencia MIT cubre el código del conversor y su definición de habilidades. No dice nada sobre el documento que se le proporciona.
- Ejecutar el conversor sobre un libro que ha comprado, en hardware que controla, equivale a tomar notas de su propia copia.
- Publicar el resultado es distribuirlo, y la licencia MIT de la herramienta no le concede ningún derecho para distribuir material derivado del libro de otra persona.
- El resultado es una obra derivada. Los marcos y las conclusiones de cada capítulo siguen estando determinados por la fuente, y una obra derivada sigue estando sujeta a los derechos de autor de la fuente.
- Una habilidad creada a partir de material que no puede redistribuir debe permanecer en la máquina donde se creó. No debe estar en un repositorio público ni en un marketplace compartido por el equipo.
- Publique cuando la fuente sea suya o tenga una licencia abierta: documentación escrita por su equipo o un estándar cuyos términos permitan la redistribución.
La herramienta está diseñada teniendo esto en cuenta. No incluye contenido de libros y la extracción se ejecuta localmente. El valor fijado de v1.4.0 sólo imprime una línea opcional de gh skill publish y nunca pregunta por la visibilidad, por lo que esa decisión depende por completo de usted. Desde entonces, la rama predeterminada del proyecto ha añadido un paso de publicación que pregunta por la visibilidad del repositorio mediante una pregunta independiente de una sola palabra y crea un repositorio público sólo cuando la respuesta es la palabra exacta public; cualquier otra respuesta termina en un repositorio privado. Considere ese paso como la decisión sobre la licencia, porque eso es lo que representa.
Los manuales internos plantean un segundo problema. Contienen credenciales con más frecuencia de lo que se reconoce, y un conversor transforma un PDF que nadie abre en un archivo que su agente lee cuando lo necesita. Lea una vez los archivos generados antes de confirmarlos y consulte cómo mantener los secretos fuera de sus agentes de IA.
¿Cuánto cuesta una conversión?
Las cifras siguientes son mediciones publicadas por el propio proyecto, no mediciones nuestras.
Los datos de este gráfico
[
{
"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
}
]En los 4 libros que midió el proyecto, una conversión costó entre 0.88 y 1.42 dólares estadounidenses, y Pro Git costó 1.23. Las cifras se midieron con Claude Sonnet 4.5, con recuentos de tokens obtenidos de tiktoken mediante cl100k_base, y están publicadas en docs/performance.md del proyecto con fecha de octubre de 2026. Tu propia cifra variará según el modelo y los precios que uses.
El proyecto también documenta que se necesitan entre 24 y 51 veces menos tokens para responder una pregunta individual a partir de la skill que a partir del libro completo pegado en el contexto. Interpreta esto como la magnitud del ahorro, no como una garantía, porque depende del libro y de la pregunta. El principio estructural se mantiene: la conversión se paga una sola vez, mientras que volcar el contexto se paga de nuevo en cada conversación que necesite el libro.
¿Por qué no pegar el PDF o crear un índice RAG?
Pegar el contenido funciona y es la opción adecuada para una pregunta sobre un documento. Deja de ser la opción adecuada cuando necesita el mismo libro el martes y de nuevo el viernes, porque paga todo su tamaño cada vez.
La recuperación, o RAG (generación aumentada mediante recuperación), busca en el momento de la consulta y devuelve los pasajes que coinciden con sus palabras. Es útil cuando necesita la frase exacta. Es menos útil cuando lo importante es un marco conceptual distribuido por un capítulo, porque ningún pasaje aislado lo contiene. Una skill realiza esa extracción una sola vez, durante la conversión, y almacena la estructura en lugar de los pasajes.
El límite real es el siguiente: una skill generada es un resumen con pérdida de información, redactado por un modelo. Sirve como ayuda de estudio, pero la fuente original sigue siendo la referencia. Cuando la redacción exacta tiene importancia jurídica o protocolaria, conserve el PDF y cite su contenido. Comparación entre skills, servidores MCP y archivos de reglas explica dónde encaja cada enfoque.
Modos de fallo y cadenas que verá
Un PDF escaneado no produce ningún resultado. El extractor comprueba si las páginas iniciales tienen una capa de texto y se detiene con una explicación en lugar de procesar 400 páginas de imágenes. Ejecute ocrmypdf input.pdf output.pdf primero y, después, proporciónele el archivo de salida.
pip se niega a instalar. error: externally-managed-environment en Ubuntu 24.04 indica que apt está protegiendo el Python del sistema. Use el entorno virtual anterior o instale poppler-utils y omita pip por completo.
Los capítulos aparecen mal. La detección de capítulos busca encabezados explícitos como Chapter 7 y sus variantes lingüísticas. También reconoce números romanos como Chapter IV o IV. Title. Un libro que usa títulos de sección sin numerar produce una división incorrecta. Para corregirlo, indique al proceso dónde empiezan los capítulos en lugar de confiar en que los detecte por sí solo.
El comando no existe. Si /book-to-skill no aparece en el autocompletado, significa que el directorio de skills se creó después de iniciar la sesión. Ejecute /reload-skills o reinicie el agente.
Docling tarda demasiado. A aproximadamente 1.5 segundos por página, un libro largo requiere varios minutos de CPU. En un servidor compartido, ese proceso compite con el resto de los servicios alojados. Responda "text-heavy" cuando el proceso pregunte por el tipo de contenido o pase --mode text si ejecuta scripts/extract.py directamente. --mode technical es la respuesta que selecciona docling.
Una fuente desaparece sin aviso. Los archivos que no se pueden leer se omiten para que el lote pueda terminar. El proceso informa de éxito con menos fuentes de las que se proporcionaron. El único lugar donde esto se muestra es el inventario de archivos del informe final. Comprobar un proceso terminado con respecto a los archivos que realmente se le proporcionaron es una práctica útil más allá de esta herramienta. El método Depth Tree de la skill unlazy es una forma de hacer que un agente aplique el mismo criterio en lugar de declarar prematuramente que el trabajo ha terminado.
Aplicar el mismo patrón manualmente
La herramienta es una comodidad. La estructura es la parte transferible, y un editor de texto puede crearla para cualquier material de referencia que sea suyo.
- Escriba un archivo de entrada y manténgalo cerca de los 4,000 tokens a los que apunta el convertidor. Incluya en él los conceptos con sus formulaciones exactas, además de un índice que enumere cada archivo de detalle y los temas que contiene.
- Divida el material en archivos de aproximadamente 1,000 tokens, con un tema por archivo. Asigne nombres que permitan saber el contenido sólo por el nombre del archivo.
- Describa cada uno de esos archivos en el archivo de entrada, dentro de la frase que indica cuándo debe leerse.
El paso 3 es el que más se omite, y es el que hace funcionar el patrón. El agente decide qué abrir leyendo el índice, por lo que nunca abre un archivo que el índice no describa. El índice es el producto, y los archivos de capítulos son el almacenamiento.
Mantenga el archivo de entrada dentro del presupuesto de compactación y toda la estructura se conservará durante una sesión larga. Esta regla se aplica tanto si un convertidor escribió los archivos como si los creó usted.
FAQ
¿Puedo publicar una skill creada a partir de un libro que compré?
No, salvo que la licencia del libro permita su redistribución. La licencia MIT del conversor cubre el código del conversor, no el material que le proporcione, y la skill generada es una obra derivada del libro. Guárdela en ~/.claude/skills/ en su propia máquina. Puede publicar documentación escrita por usted o basada en fuentes con licencias abiertas. El v1.4.0 fijado nunca pregunta por la visibilidad, mientras que la rama predeterminada del proyecto ahora lo pregunta como una cuestión independiente y sólo se hace pública con un public vacío; en ambos casos, la decisión debe tomarla deliberadamente.
¿Necesito docling o basta con pdftotext?
pdftotext de poppler-utils basta para la prosa y es casi instantáneo. Instale docling cuando el valor del libro esté en sus tablas y listados de código, porque un extractor de texto plano omite precisamente esos elementos. La contrapartida es la velocidad: el proyecto mide docling en aproximadamente 1.5 segundos por página, por lo que un manual de 300 páginas requiere varios minutos de CPU en un VPS.
¿Por qué pip falla con externally-managed-environment en mi VPS?
Ubuntu 24.04 y las versiones actuales de Debian marcan el Python del sistema como gestionado por apt, por lo que pip se niega a instalar paquetes en él y muestra error: externally-managed-environment. Cree un entorno virtual con python3 -m venv ~/.venvs/book-to-skill, actívelo, instale allí los extractores y después inicie el agente desde esa misma shell. La skill llama a python3, por lo que usa el intérprete que figure en su PATH, que ahora es el del entorno virtual.
¿Por qué mi skill generada no aparece como comando de barra?
Hay dos causas. El nombre del comando procede del nombre del directorio, por lo que la skill debe estar en ~/.claude/skills/<name>/SKILL.md o .claude/skills/<name>/SKILL.md, con SKILL.md escrito exactamente así. Si la ruta es correcta, ejecute /reload-skills o reinicie el agente. Claude Code detecta los cambios dentro de los directorios de skills que ya supervisa, pero no supervisa un directorio de skills creado después de iniciar la sesión hasta que se realiza una de esas acciones.