Convertir un libro técnico en una skill de agente

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 posea. El conversor escribe un directorio de la 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 lee sólo cuando la pregunta lo requiere. El libro nunca entra en la ventana de contexto. El índice sí.

Esta tarea es la opuesta 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 un proveedor de 800 páginas 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 agosto de 2026 es v1.4.0. La estructura que produce es más importante que la propia 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.

[
  {
    "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, fijado a 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 de barra diagonal, por lo que la ruta de clonación no es una cuestión de preferencias.

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

--branch acepta una etiqueta, por lo que esto extrae v1.4.0 y ninguna versión posterior. Fíjela porque una skill es un conjunto de instrucciones que sigue el agente, y un cambio no revisado en esas instrucciones cambia 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 fijado para cualquier ejecución posterior.

Ahora confirme qué extractores tiene el equipo:

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

--check informa de qué extractores están instalados e imprime el comando de instalación de cada extractor que falta. El paquete necesita Python 3.9 o posterior.

Si /book-to-skill no aparece en el autocompletado después de clonar, 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 un ~/.claude/skills/ que creó 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 son peores. En un servidor pequeño, el tiempo se desperdicia instalando extractores que no se van a utilizar.

• pdftotext, del paquete poppler-utils, procesa PDF con mucho texto y es casi instantáneo. Instálelo con sudo apt install poppler-utils.
• pypdf y pdfminer.six son las alternativas de Python para PDF.
• docling está pensado para PDF técnicos cuyo contenido principal son tablas y listados de código. El proyecto calcula un tiempo aproximado de 1.5 segundos por página.
• ebooklib con beautifulsoup4 procesa EPUB correctamente. Sin ellos, la herramienta usa el lector zipfile de la biblioteca estándar.
• python-docx procesa DOCX y striprtf procesa RTF.
• ebook-convert de Calibre es necesario para archivos MOBI y AZW.
• ocrmypdf ejecuta OCR (reconocimiento óptico de caracteres) sobre un libro escaneado que no tiene ninguna capa de texto.

En Ubuntu 24.04, un pip3 install pypdf sin opciones termina con este error:

error: externally-managed-environment

No 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 soluciones. sudo apt install poppler-utils instala un binario y no necesita pip, y pdftotext procesa por sí solo la mayoría de los PDF con texto. Para los extractores de Python, cree un entorno virtual y ejecute el agente desde dentro de él. Así, el python3 que utiliza la habilidad 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]"
claude

El repositorio declara los extras pdf, epub, docx, rtf, technical y all, donde technical es docling. La página de instalación del proyecto también muestra pip install "book-to-skill[pdf,epub,docx]", pero ese nombre no está publicado en PyPI a fecha de agosto de 2026. Por tanto, instálelo desde su propia copia de trabajo como se indicó anteriormente.

No instale docling hasta que un libro lo necesite. Añade una pila de aprendizaje automático, 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, seguido de un nombre de skill opcional. Puede incluir cualquier contenido disponible 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-research

Escriba el patrón glob entre comillas para que el shell no lo expanda antes de que la skill lo reciba. Si apunta el comando a un directorio de skill existente, las nuevas fuentes se incorporan a esa skill en lugar de crear otra.

Una ejecución interactiva le hace preguntas. Pregunta si el material es técnico o contiene mucho texto, lo que determina el extractor. También pregunta si necesita profundidad de referencia o de estudio, lo que determina el presupuesto por capítulo. Después pregunta cómo debe llamarse la skill y en qué directorio raíz de skills debe instalarse. Además, 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 con barra 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 preautoriza las herramientas que necesita la ejecución, porque un aviso de permisos sin un terminal conectado impide que la ejecución termine. 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. 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 tuvo éxito 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.

Asigne la ejecución a un servidor que esté dispuesto a entregar a un agente. Ejecutar Claude Code de forma segura en un VPS cubre el aspecto de 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 convertidor, no el libro

Sea exacto en este punto, porque el fallo no es técnico.

• La licencia MIT cubre el código del convertidor y su definición de skill. No dice nada sobre el documento que se le proporciona.
• Ejecutar el convertidor 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.
• La salida es una obra derivada. Los marcos y las conclusiones de los capítulos siguen estando condicionados por la fuente, y una obra derivada continúa sujeta a los derechos de autor de la fuente.
• Una skill creada a partir de material que no puede redistribuir debe permanecer en la máquina que la creó. No debe publicarse en un repositorio público ni en un marketplace compartido por el equipo.
• Publique el resultado cuando la fuente sea suya o tenga una licencia abierta: por ejemplo, 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, la extracción se ejecuta localmente y el paso de publicación solicita la visibilidad del repositorio como una pregunta independiente. Sólo acepta la palabra exacta public o private, sin inferir una opción. Trate esa pregunta 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 la que se admite, y un convertidor transforma un PDF que nadie abre en un archivo que su agente lee bajo demanda. 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.

[
  {
    "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 tuvo un coste de 1.23. Las cifras se midieron con Claude Sonnet 4.5, usando recuentos de tokens de tiktoken mediante cl100k_base, y están publicadas en el docs/performance.md del proyecto con fecha de agosto de 2026. Su propia cifra varía según el modelo y los precios que utilice.

El proyecto también documenta entre 24 y 51 veces menos tokens para responder una sola pregunta a partir de la skill que a partir del libro completo pegado en el contexto. Interprete esto como una indicación de 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 necesita 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 mensajes 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 cientos de páginas de imágenes. Ejecute primero ocrmypdf input.pdf output.pdf 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.

Los capítulos aparecen mal. La detección de capítulos busca encabezados explícitos, como Chapter 7, y sus variantes lingüísticas. Un libro que usa títulos de sección independientes o números romanos produce una división incorrecta. La solución es indicar al proceso dónde comienzan los capítulos, en lugar de confiar en una detección automática.

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. 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 servicios alojados. Responda "text-heavy" cuando el proceso pregunte por el tipo de contenido o pase --mode text cuando ejecute scripts/extract.py manualmente. --mode technical es la respuesta que selecciona docling.

Una fuente desaparece sin avisar. Los archivos que no se pueden leer se omiten para que el lote pueda finalizar. El proceso informa de éxito sobre un número de fuentes inferior al que se le proporcionó. El inventario de archivos del informe final es el único lugar donde se muestra esta diferencia.

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.

1. 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.
2. 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.
3. 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 se le proporciona, 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 fuentes con una licencia abierta. La herramienta solicita la visibilidad del repositorio como una decisión independiente y acepta únicamente public o private sin texto adicional, para que la decisión sea deliberada.

¿Necesito docling o basta con pdftotext?

pdftotext de poppler-utils basta para la prosa y es prácticamente instantáneo. Instale docling cuando el valor del libro esté en sus tablas y listados de código, porque un extractor de texto plano elimina 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 ese mismo shell. La skill ejecuta python3, por lo que utiliza el intérprete que esté en su PATH. En este caso, es el intérprete 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, y SKILL.md debe escribirse exactamente así. Si la ruta es correcta, reinicie el agente. Claude Code detecta los cambios realizados dentro de los directorios de skills que ya está supervisando, pero no supervisa un directorio de skills creado después de iniciar la sesión.