virgiliojr94/book-to-skill

Convertidor de Libro a Habilidad

Transforma 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 tomaron años en desarrollarse. Esta habilidad extrae ese conocimiento en un formato que GitHub Copilot CLI, Amp, Claude Code, Hermes Agent u otro agente compatible pueda aprovechar repetidamente.

Extrae estructura, no resúmenes. Una habilidad 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 suelen tener 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.

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

---

Modos de Operación

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

1. Conversión Completa (Predeterminada)

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

2. Solo Análisis

Activación: El usuario dice "analiza", "solo extrae" o "quiero revisar antes de generar" Acción: Ejecuta los Pasos 0–3, luego produce un informe de extracción estructurado (marcos de trabajo, principios, técnicas encontradas). Detente — NO generes archivos de habilidad. Salida: Informe de análisis para revisión del usuario

3. Generar a partir de Análisis Previo

Activación: El usuario tiene notas de análisis existentes o ejecutó previamente solo análisis Acción: Omite los Pasos 0–3, usa el análisis proporcionado como entrada, ejecuta los Pasos 4–9 Salida: Archivos de habilidad a partir del análisis proporcionado

4. Actualizar / Fusionar (Habilidad Existente)

Activación: El usuario proporciona una o más rutas de fuente nuevas e indica que quiere actualizar una habilidad existente (ya sea señalando la carpeta de la habilidad existente, proporcionando un slug de habilidad que ya existe en SKILLS_HOME, o solicitando explícitamente una actualización). Acción: Ejecuta el Paso 0 (verificación fuera de alcance), Paso 1 (validar entradas), Paso 1.5 (identificar tipo de libro) y Paso 2 (extraer nuevos archivos). Luego salta al Paso 5 (identificar/detectar ruta de habilidad existente) y ejecuta el Flujo de Trabajo de Actualización/Fusión para fusionar el nuevo contenido en los archivos de habilidad existentes. Salida: Habilidad existente actualizada con resúmenes de capítulos nuevos/revisados e índices/glosarios fusionados.

---

Ubicaciones de Habilidades

Este convertidor puede ejecutarse desde múltiples sistemas de habilidades. Al buscar el script auxiliar de este convertidor o escribir la habilidad de libro generada, prefiere estas ubicaciones en orden:

1. Habilidades personales de GitHub Copilot CLI: ~/.copilot/skills/
2. Habilidades personales entre agentes (Copilot, Amp, Codex): ~/.agents/skills/
3. Habilidades personales de Claude Code: ~/.claude/skills/
4. Habilidades de Copilot locales al proyecto: .github/skills/
5. Habilidades de Claude locales al proyecto: .claude/skills/
6. Habilidades de Amp / Copilot locales al proyecto: .agents/skills/
7. Habilidades globales de Amp: ~/.config/agents/skills/
8. Habilidades globales heredadas de Amp: ~/.config/amp/skills/
9. Habilidades personales de Hermes Agent: $HERMES_HOME/skills/ (por defecto ~/.hermes/skills/)
10. Habilidades de proyecto de Hermes Agent: .hermes/skills/ o .agents/skills/

Para habilidades de libro generadas, prefiere la raíz entre agentes a nivel de usuario ~/.agents/skills/ — una copia física sirve para cada anfitrión compatible. Copilot CLI y Amp la detectan de forma nativa; Claude Code necesita un enlace simbólico desde ~/.claude/skills/<nombre_habilidad> (creado en el Paso 10, ver Paso 5 para las reglas). Elige una raíz privada al anfitrión o local al proyecto solo cuando el usuario lo solicite.

---

Paso 0 — Verificación fuera de alcance

Si no se proporcionan argumentos, detente y responde:

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

A lo largo del flujo de trabajo:

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

---

Paso 1 — Validar entrada

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

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

---

Paso 1.5 — Identificar tipo de contenido

Antes de extraer, pregunta al usuario:

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

1. Técnico — tiene bloques de código, tablas, fórmulas, diagramas (por ejemplo, libros de programación, artículos académicos, guías de arquitectura)
2. Con mucho texto — mayormente prosa, pocas o ninguna tabla/código (por ejemplo, gestión, productividad, no ficción narrativa)
3. No estoy seguro — usaré el método rápido y te advertiré si la calidad parece limitada"

Almacena 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, informa 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 conservados 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, informa:

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

---

Paso 2 — Extraer texto de los documentos fuente

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

SCRIPT_PATH=""
HERMES_HOME_RESOLVED="${HERMES_HOME:-$HOME/.hermes}"
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
HERMES_PROJECT_TRUSTED=false
if [ -n "$PROJECT_ROOT" ] && [ "${HERMES_AGENT:-}" = true ] && \
  command -v hermes >/dev/null 2>&1 && \
  command -v python3 >/dev/null 2>&1 && \
  hermes config get skills.trusted_project_dirs --json 2>/dev/null | PROJECT_ROOT="$PROJECT_ROOT" python3 -c 'import json, os, pathlib, sys; root=pathlib.Path(os.environ["PROJECT_ROOT"]).resolve(); sys.exit(not any(pathlib.Path(p).expanduser().resolve() == root for p in json.load(sys.stdin)))' 2>/dev/null
then
  HERMES_PROJECT_TRUSTED=true
fi

CANDIDATES=(
  "$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"
  "$HERMES_HOME_RESOLVED/skills/book-to-skill/scripts/extract.py"
  "$HERMES_HOME_RESOLVED"/skills/*/book-to-skill/scripts/extract.py
)
if [ "${HERMES_AGENT:-}" != true ]; then
  CANDIDATES+=(
    ".github/skills/book-to-skill/scripts/extract.py"
    ".claude/skills/book-to-skill/scripts/extract.py"
    ".agents/skills/book-to-skill/scripts/extract.py"
  )
fi
CANDIDATES+=(
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py"
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
)
if [ "$HERMES_PROJECT_TRUSTED" = true ]; then
  CANDIDATES=(
    "$PROJECT_ROOT/.hermes/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.hermes/skills"/*/book-to-skill/scripts/extract.py
    "$PROJECT_ROOT/.agents/skills/book-to-skill/scripts/extract.py"
    "$PROJECT_ROOT/.agents/skills"/*/book-to-skill/scripts/extract.py
    "${CANDIDATES[@]}"
  )
fi
for candidate in "${CANDIDATES[@]}"
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, le pide al usuario 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 — verifica el entorno previamente: 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 un directorio de trabajo por ejecución — <tempdir>/book_skill_work-<pid>/ por defecto, o exactamente la ruta que establezcas en BOOK_SKILL_WORKDIR — que contiene:

• full_text.txt — texto extraído combinado de todas las fuentes con límites visualmente demarcados claramente.
• metadata.json — tamaño total combinado, palabras, páginas, conteos de tokens, conteos de imágenes de EPUB descartadas, el workdir resuelto, y una lista detallada de sources individuales procesadas.

La ejecución imprime las tres rutas al completarse (Workdir ->, Text ->, Meta ->). Toma las rutas de esa salida (o del campo workdir de metadata.json) en lugar de asumir una ubicación fija — el nombre del directorio difiere por ejecución para que extracciones concurrentes en una misma máquina no puedan sobrescribir los resultados de la otra.

Lee el metadata.json de esa ejecución para inspeccionar los resultados.

Siempre confirma que la extracción es el documento que solicitaste antes de generar cualquier cosa: verifica filename / source_file en metadata.json, o el encabezado SOURCE: en la primera línea de full_text.txt. Si estás esperando una ejecución en segundo plano, espera en su workdir específico — sondear una ruta compartida podría mostrar la salida de una ejecución diferente.

---

Paso 2.5 — Estimación de costo previa

Lee el metadata.json de esta ejecución (la ruta Meta -> de la salida de extracción) y presenta al usuario una estimación antes de hacer cualquier generación:

📖 Fuentes detectadas: <total_sources> fuente(s)
<lista cada nombre de archivo fuente y formato de la lista de metadatos de fuentes>
<si images_dropped > 5: advierte que N imágenes fuente no fueron leídas>
📄 Páginas/Secciones combinadas: ~<N> | Palabras: ~<N> | Tokens totales: ~<N>K

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

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

   ⏱  Tiempo estimado: ~<N> minutos

📁 Archivos a generar/actualizar:
   SKILL.md + archivos de capítulo + 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 metadata × 1.3 (sobrecarga de indicaciones por pase de capítulo)
• Tokens de salida ≈ capítulos × presupuesto por capítulo + 4,000 (SKILL.md) + 4,500 (glosario + patrones + chuleta)
  • Punto medio del presupuesto por capítulo según BOOK_TYPE (PROFUNDIDAD 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, usa la fila correspondiente de la matriz del Paso 7.
• Costo: reporta los conteos de tokens y multiplícalos por las tarifas por cada 1M de tokens de entrada/salida actuales del usuario. NO codifiques cantidades en dólares de forma fija — los nombres de modelos y precios cambian; si muestras uno, etiquétalo como estimación y fechalo.

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

---

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

Inspirado en el paradigma del Modelo de Lenguaje Recursivo (RLM): trata 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, prefiere 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"

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

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

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

# Lectura dirigida con desplazamiento/límite evita volcar todo el archivo
# Read(file_path=full_text.txt, offset=<línea>, limit=<líneas>)

Usa 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 de menos de 50k tokens, un solo Read está bien.

Por qué importa: un libro de 200 páginas tiene ~75k tokens. Releerlo una vez por capítulo (28 pases) consume mucho contexto. Con acceso estilo REPL, solo cargas lo que necesitas y mantienes el presupuesto para la generación real de la habilidad.