Convertidor de Libro a Skill

Transforma el conocimiento escrito en habilidades accionables para agentes extrayendo estructura — no produciendo resúmenes.

Filosofía

Los libros contienen experiencia cristalizada: marcos de trabajo, principios y técnicas que tomó años desarrollar. Este skill extrae ese conocimiento en un formato que GitHub Copilot CLI, Amp, Claude Code u otro agente compatible pueda aprovechar repetidamente.

Extrae estructura, no resúmenes. Un skill no es un informe de lectura. Es un conjunto de herramientas de:

Marcos de trabajo nombrados (modelos mentales con aplicación clara)
Principios accionables (reglas que guían decisiones)
Técnicas (métodos paso a paso)
Anti-patrones (qué evitar y por qué)
Calibración de voz (cómo piensa y se comunica el autor)

Preserva la precisión del autor. Los marcos de trabajo a menudo tienen nombres específicos por una razón. "Los 5 Porqués" no es intercambiable con "preguntar por qué varias veces". Captura la formulación exacta.

Aplica profundidad adecuadamente. Libros simples → skills simples. Libros complejos con 10+ marcos de trabajo → skills con archivos de referencia y capítulos bajo demanda.

Modos de Operación

Cuatro caminos disponibles. Elige según lo que el usuario pida:

1. Conversión Completa (Predeterminado)

Disparador: El usuario proporciona una o más rutas de documento/directorio/glob sin instrucciones especiales Acción: Ejecutar todos los pasos siguientes (Pasos 0–9) Salida: Skill completo con SKILL.md, chapters/, glosario, patrones, chuleta

2. Solo Análisis

Disparador: El usuario dice "analiza", "solo extrae" o "quiero revisar antes de generar" Acción: Ejecutar Pasos 0–3, luego producir un informe de extracción estructurado (marcos de trabajo, principios, técnicas encontrados). Detenerse — NO generar archivos de skill. Salida: Informe de análisis para revisión del usuario

3. Generar desde Análisis Previo

Disparador: El usuario tiene notas de análisis existentes o ejecutó previamente solo análisis Acción: Saltar Pasos 0–3, usar el análisis proporcionado como entrada, ejecutar Pasos 4–9 Salida: Archivos de skill a partir del análisis proporcionado

4. Actualizar / Fusionar (Skill Existente)

Disparador: El usuario proporciona una o más rutas de origen nuevas e indica que desea actualizar un skill existente (ya sea señalando la carpeta del skill existente, proporcionando un slug de skill que ya existe en SKILLS_HOME, o solicitando explícitamente una actualización). Acción: Ejecutar Paso 0 (verificación fuera de alcance), Paso 1 (validar entradas), Paso 1.5 (identificar tipo de libro) y Paso 2 (extraer archivos nuevos). Luego saltar al Paso 5 (identificar/detectar ruta del skill existente) y ejecutar el Flujo de Actualización / Fusión para integrar el contenido nuevo en los archivos del skill existente. Salida: Skill existente actualizado con resúmenes de capítulos nuevos/mejorados e índices/glosarios fusionados.

Ubicaciones de Skills

Este convertidor puede ejecutarse desde múltiples sistemas de skills. Al buscar el script auxiliar de este convertidor o escribir el skill de libro generado, preferir estos lugares en orden:

Skills personales de GitHub Copilot CLI: ~/.copilot/skills/
Skills personales entre agentes (Copilot + Amp): ~/.agents/skills/
Skills personales de Claude Code: ~/.claude/skills/
Skills de Copilot locales al proyecto: .github/skills/
Skills de Claude locales al proyecto: .claude/skills/
Skills de Amp / Copilot locales al proyecto: .agents/skills/
Skills globales de Amp: ~/.config/agents/skills/
Skills globales heredadas de Amp: ~/.config/amp/skills/

Para los skills de libro generados, elige un destino que el agente anfitrión del usuario pueda descubrir realmente (ver Paso 5). Cuando exista más de una raíz válida, pregúntale al usuario una vez y recuerda la respuesta para la sesión — no uses un valor predeterminado en silencio.

Paso 0 — Verificación fuera de alcance

Si no se proporcionan argumentos, detenerse y responder:

"book-to-skill requiere una ruta de documento, carpeta o patrón glob compatible. Uso: book-to-skill <ruta-a-carpeta-de-documentos-o-glob>... [nombre-slug-skill]"

A lo largo del flujo:

Identificar las rutas de entrada y el slug opcional del skill.
Si el último argumento no es un archivo, carpeta o glob que exista o coincida con algún archivo, y parece un slug de skill (ej. guiones en minúsculas, alfanumérico), tratarlo como SKILL_NAME.
Tratar todos los demás argumentos como la lista de INPUT_PATHS.
Si alguna ruta de entrada es un directorio de skill existente (contiene SKILL.md y una subcarpeta chapters/), o si SKILL_NAME coincide con un slug de skill existente en SKILLS_HOME, marcar esta ejecución como una operación de Actualización/Fusión (Modo 4).

Paso 1 — Validar entrada

Verificar que haya al menos un archivo, directorio o patrón glob compatible entre los INPUT_PATHS. Para directorios y globs, expandirlos para encontrar archivos compatibles (.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3).

Si no se encuentran archivos compatibles, detenerse con un mensaje de error claro.

Paso 1.5 — Identificar tipo de contenido

Antes de extraer, preguntar al usuario:

"¿Qué tipo de contenido tienen estas fuentes? Esto me ayuda a elegir el mejor método de extracción.

Técnico — tiene bloques de código, tablas, fórmulas, diagramas (ej. libros de programación, artículos académicos, guías de arquitectura)

Con mucho texto — mayormente prosa, pocas o ninguna tabla/código (ej. gestión, productividad, no ficción narrativa)

No estoy seguro — Usaré el método rápido y te advertiré si la calidad parece limitada"

Almacenar la respuesta como BOOK_TYPE:

Opción 1 → BOOK_TYPE=technical
Opción 2 → BOOK_TYPE=text
Opción 3 → BOOK_TYPE=text

Si BOOK_TYPE=technical, informar al usuario antes de continuar:

"📐 Modo técnico seleccionado — usando Docling para extracción con conciencia de estructura (tablas, bloques de código, fórmulas preservados como markdown). Esto toma ~1.5s por página, así que espera unos minutos para fuentes más largas. Comenzando ahora..."

Si BOOK_TYPE=text, informar:

"📄 Modo de texto seleccionado — usando el extractor más rápido adecuado para cada tipo de archivo. Texto plano/Markdown/HTML generalmente están listos en segundos; los PDFs usan pdftotext cuando está disponible."

Paso 2 — Extraer texto de los documentos fuente

Ejecutar el script de extracción, pasando las rutas de entrada:

SCRIPT_PATH=""
for candidate in \
  "$HOME/.copilot/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.claude/skills/book-to-skill/scripts/extract.py" \
  ".github/skills/book-to-skill/scripts/extract.py" \
  ".claude/skills/book-to-skill/scripts/extract.py" \
  ".agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "No se pudo encontrar scripts/extract.py para book-to-skill" >&2
  exit 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask

Antes de la extracción, el script verifica los paquetes opcionales de Python necesarios para el formato detectado. Si falta un extractor mejor, solicita al usuario con la alternativa disponible. Las sesiones no interactivas usan la alternativa por defecto a menos que el modo de instalación sea explícitamente yes.

Consejo — preparar el entorno: ejecuta "$PYTHON_BIN" "$SCRIPT_PATH" --check para imprimir un informe por formato de qué extractores están instalados y el comando exacto para instalar lo que falta, sin procesar ningún archivo. Útil cuando un usuario reporta un problema de configuración o calidad.

Esto crea:

<tempdir>/book_skill_work/full_text.txt — texto extraído combinado de todas las fuentes con límites visualmente demarcados claros.
<tempdir>/book_skill_work/metadata.json — tamaño total combinado, palabras, páginas, recuentos de tokens y una lista detallada de sources procesadas individualmente.

Leer <tempdir>/book_skill_work/metadata.json para inspeccionar los resultados.

Paso 2.5 — Estimación de costo preliminar

Leer <tempdir>/book_skill_work/metadata.json y presentar al usuario una estimación antes de hacer cualquier generación:

📖 Fuentes detectadas: <total_sources> fuente(s)
<listar cada nombre de archivo fuente y formato de la lista de metadatos de fuentes>
📄 Páginas/Secciones combinadas: ~<N> | Palabras: ~<N> | Tokens totales: ~<N>K

💰 Costo estimado en tokens (Conversión Completa / Actualización):
   Entrada (lectura + prompts): ~<N>K tokens
   Salida (archivos de skill generados/actualizados):  ~<N>K tokens
   Total:                           ~<N>K tokens

   Costo: multiplica los recuentos de tokens anteriores por las tasas actuales
   de tu modelo por 1M tokens de entrada/salida (los precios y nombres de modelo
   cambian a menudo — no los codifiques; cita la tasa de hoy y etiquétala como estimación).

   ⏱  Tiempo estimado: ~<N> minutos

📁 Archivos a generar/actualizar:
   SKILL.md + archivos de capítulos + glosario + patrones + chuleta

➡  ¿Proceder con Conversión Completa / Actualización? (o escribe "solo analizar" para previsualizar primero)

Cómo estimar:

Tokens de entrada ≈ estimated_tokens de metadatos × 1.3 (sobrecarga de prompts por paso de capítulo)
Tokens de salida ≈ capítulos × presupuesto por capítulo + 4,000 (SKILL.md) + 4,500 (glosario + patrones + chuleta)
- Presupuesto por capítulo punto medio según BOOK_TYPE (DEPTH se decide más tarde en el Paso 4 y puede aumentarlo): text ≈ 1,000, technical ≈ 1,800. Si el usuario ya ha indicado solo referencia vs estudio profundo, usar la fila correspondiente de la matriz del Paso 7.
Costo: reportar los recuentos de tokens y multiplicar por las tasas actuales de entrada/salida por 1M tokens del usuario. NO codificar cifras en dólares — los nombres de modelo y precios cambian; si muestras uno, etiquétalo como estimación y fechalo.

Esperar la confirmación del usuario antes de continuar. Si dice "solo analizar", cambiar al Modo 2.

Paso 2.6 — Acceso tipo REPL para libros grandes (> 50k tokens)

Inspirado en el paradigma del Modelo de Lenguaje Recursivo (RLM): tratar full_text.txt como un corpus consultable, no como una lectura única. Cargar todo el archivo en contexto quema presupuesto que necesitarás más tarde para la generación.

Para libros de más de ~50k tokens, preferir sondeos programáticos sobre Read(full_text.txt) sin límites:

# Verificación de tamaño antes de cualquier Read
wc -w "$FULL_TEXT_PATH"

# Encontrar offsets de capítulos sin cargar todo el archivo
grep -n -E "^\s*(Capítulo|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# Extraer solo el capítulo que necesitas (líneas start..end inclusive)
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# Verificar que un marco de trabajo se menciona antes de reclamarlo en SKILL.md
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# Read dirigido con offset/limit evita volcar todo el archivo
# Read(file_path=full_text.txt, offset=<linea>, limit=<lineas>)

Usar este enfoque para el Paso 3 (análisis de estructura), Paso 7 (resúmenes por capítulo) y Paso 8 (extracción de glosario/patrones). En libros por debajo de 50k tokens, un solo Read está bien.

Por qué esto importa: un libro de 200 páginas tiene ~75k tokens. Releerlo una vez por capítulo (28 pasadas) cuesta ~2M tokens de entrada; usar grep + sed para extraer solo las porciones relevantes mantiene el costo de generación proporcional a la salida, no a la fuente.

Paso 3 — Analizar estructura del libro

Leer los primeros 8,000 caracteres del full_text.txt extraído para identificar:

Título del libro y autor(es)
Estructura de capítulos (buscar "Capítulo N", "PARTE I", encabezados numerados, tabla de contenidos)
Temas centrales y dominio de la materia
Número aproximado de capítulos

Luego leer la sección de la Tabla de Contenidos si está presente para mapear todos los capítulos.

Si el modo es "Solo Análisis": producir el informe de extracción ahora y detenerse. Estructura:

## Informe de Extracción — <Título>

### Marcos de Trabajo Centrales del Autor
- **<Nombre del Marco>**: <qué es y cuándo aplicarlo>

### Principios Clave
- <Principio>: <regla accionable>

### Técnicas y Métodos
- <Técnica>: <paso a paso o cómo hacerlo>

### Anti-patrones
- <Qué evitar>: <por qué>

### Nombre Sugerido del Skill
`{apellido-autor}-{concepto-central}` — ej. `cialdini-influence`

### Capítulos Detectados
| # | Título | Marcos Principales |

Paso 4 — Preguntar propósito (solo Conversión Completa)

Antes de generar, preguntar al usuario:

"¿Para qué debería ayudarte este skill? (Elige uno o más)

Aplicar los marcos de trabajo del autor mientras trabajas

Pensar con los modelos mentales del autor

Consultar capítulos y conceptos específicos

Todo lo anterior"

Usar la respuesta para ponderar lo que se destaca en la sección Core del SKILL.md.

Derivar DEPTH de la respuesta (sin prompt adicional):

La respuesta es solo la opción 3 (referencia) → DEPTH=reference — capítulos ligeros y de consulta rápida.
La respuesta incluye la opción 1, 2 o 4 → DEPTH=study — capítulos más profundos con más detalle trabajado, ejemplos y razonamiento.

DEPTH y BOOK_TYPE juntos establecen el presupuesto de tokens por capítulo en el Paso 7. No preguntes una pregunta separada de "estudio vs referencia" — se infiere aquí. (En los Modos 2/3, donde se salta el Paso 4, el valor predeterminado es DEPTH=study.)

Paso 5 — Determinar nombre del skill

Si se proporcionó SKILL_NAME, usarlo como slug del skill. De lo contrario, proponer dos opciones y dejar que el usuario elija:

Por autor-concepto: {apellido-autor}-{concepto-central} (ej. cialdini-influence, meadows-systems)
Por título: minúsculas con guiones a partir del título del libro (ej. designing-data-intensive-apps)

Por defecto, usar el formato autor-concepto si el libro tiene una identidad metodológica fuerte.

Elegir la raíz de skill de destino (SKILLS_HOME). Sondear el sistema de archivos del usuario en busca de directorios de skills existentes y elegir según el anfitrión en el que el usuario está ejecutando:

| Agente anfitrión | Personal

...

[truncated for translation]

Leutenegger/book-to-skill

¿Qué es book-to-skill?

Preguntar en tu IA favorita

Documentación