xls-skill

Convierte libros de Excel (.xlsx/.xlsm/.xls) a Markdown legible por IA, manteniendo cada imagen en su celda original, incluyendo imágenes incrustadas DENTRO de celdas (WPS Office =DISPIMG y Microsoft 365 'Place in Cell') que los lectores normales de Excel pasan por alto, además de imágenes flotantes, cuadros de texto, fórmulas, estructura oculta y OCR.

¿Qué es xls-skill?

Esta habilidad resuelve un problema común en el procesamiento de archivos Excel: la pérdida de contenido visual. Mientras que librerías como openpyxl o pandas solo extraen valores de celda, xls-skill captura imágenes incrustadas en celdas (tanto de WPS Office como de Microsoft 365), imágenes flotantes y cuadros de texto, y las coloca de nuevo en la tabla Markdown en la celda exacta donde aparecen. Es útil para desarrolladores, auditores y asistentes de IA que necesitan analizar hojas de cálculo con fotos, logotipos, firmas, diagramas o cualquier elemento visual. Soporta archivos .xlsx, .xlsm y .xls (este último requiere Excel o LibreOffice), extrae fórmulas, estructura oculta y realiza OCR opcional con Tesseract. El resultado es un conjunto completo de archivos: tabla Markdown con imágenes incrustadas, manifiestos de imágenes, fórmulas y formas, más un informe de conversión detallado con advertencias para que el agente pueda actuar sobre cualquier problema (imágenes faltantes, formato EMF/WMF, gráficos no renderizados).

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hougw/xls-skill/tree/HEAD

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Vista previa

Del README del skill

Piezas!B2

Documentación

xls-skill: Excel -> Markdown, imágenes conservadas en sus celdas

Por qué existe esta habilidad

La mayoría de los lectores de Excel (openpyxl, pandas, exportación CSV) solo ven valores de celda. Dos tipos de imágenes se pierden:

  1. Imágenes dentro de celda. La imagen es el contenido de la celda.
    • WPS Office "incrustar en celda": la celda solo muestra =DISPIMG("ID_...",1); la imagen está en xl/cellimages.xml.
    • Microsoft 365 "Colocar en celda" / IMAGE: la celda muestra #¡VALOR!; la imagen se encuentra a través de xl/metadata.xml y xl/richData/.
  2. Imágenes flotantes y cuadros de texto dibujados sobre la cuadrícula (fotos de proceso, etiquetas, números de formulario).

Esta habilidad extrae todas ellas, guarda cada imagen como un archivo y la reescribe en la tabla Markdown en la celda donde vive, para que un lector vea la tabla y sus imágenes juntas:

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | Soporte | ![Piezas!B2](images/01_Piezas_B2_celda1.png) | Soporte \| imagen en celda | 4 |

Cómo ejecutar

python <directorio-skill>/scripts/xlsx_to_md.py <archivo-o-carpeta> [...] -o <directorio-salida> [--ocr auto|off] [--ocr-lang eng+chi_sim]
  • Acepta archivos .xlsx, .xlsm, .xls o carpetas (de forma recursiva). Imprime una línea por libro con recuentos de imágenes.
  • Necesita Python 3.9+ y openpyxl. Opcional: Pillow (tamaños de imagen), Tesseract OCR (texto dentro de imágenes), Microsoft Excel o LibreOffice (para abrir .xls).
  • Autocomprobación: python <directorio-skill>/tests/run_tests.py crea libros sintéticos de WPS y Microsoft 365 y verifica que cada imagen esté en su celda.

Qué obtienes por libro (<directorio-salida>/<nombre>/)

ArchivoContenido
<nombre>.mdÍndice del libro, luego cada hoja como una tabla Markdown completa (sin truncamiento) con imágenes en línea en sus celdas; hechos de la hoja (estado oculto, rangos combinados, filas/columnas ocultas, comentarios, cuadros de texto, número de gráficos) encima de cada tabla
<nombre>.images.mdUna entrada por imagen: la imagen, ¡hoja!celda, tipo, tamaño, texto de celdas cercanas, texto OCR y un espacio para descripción
images/Cada imagen como un archivo, nombrado `<hoja#>_<celda
sheets_csv/Valores de las hojas; las celdas con imagen contienen [imagen: images/...]
image_manifest.csvhoja, celda, tipo (en-celda (WPS DISPIMG) / en-celda (Microsoft 365) / flotante), archivo, parte del paquete, texto alternativo, tamaño, OCR, texto cercano
formula_manifest.csvTexto de fórmula y valor almacenado en caché por celda
shapes_manifest.csvTexto de cuadros de texto flotantes / formas, con celda de anclaje
conversion_report.jsonRecuentos, advertencias, revisión_requerida

Flujo de trabajo para el agente

  1. Convertir. Ejecuta el script sobre el/los libro(s).
  2. Leer primero el informe. Abre conversion_report.json. Actúa sobre cada advertencia:
    • imagen no encontrada en el paquete -> la celda está marcada como [imagen faltante: ID]; díselo, no adivines la imagen.
    • .emf/.wmf guardado tal cual -> conviértelo a PNG (por ejemplo, Pillow en Windows, LibreOffice en otros lugares) antes de examinarlo.
    • gráficos > 0 -> los gráficos se cuentan, no se renderizan; abre o exporta la hoja si el gráfico es relevante.
    • OCR omitido o falta un idioma -> confía en mirar las imágenes tú mismo.
  3. Mirar las imágenes. Abre cada archivo listado en <nombre>.images.md y reemplaza cada marcador de posición descripción con lo que muestra la imagen: objeto, texto legible (etiquetas, números de modelo, marcas), símbolos y cómo se relaciona con las celdas cercanas. El OCR es una pista, no la respuesta; el texto de etiquetas pequeñas a menudo necesita un recorte o ampliación.
  4. Responder usando la tabla y las imágenes juntas. Utiliza la tabla Markdown para valores exactos de celda, fórmulas y estructura; utiliza las imágenes para "¿cómo se ve / qué está escrito en la pieza?". Cita ¡hoja!celda para ambos.
  5. Informar las carencias honestamente. Si algo del paso 2 quedó sin resolver, marca el libro como pendiente de revisión manual.

Reglas

  • Una tabla CSV o solo de valores no es evidencia completa cuando el libro tiene imágenes, cuadros de texto, colores o contenido oculto. Revisa los hechos de la hoja y los manifiestos.
  • Empareja cada imagen con su celda y vecinos; nunca te fíes solo del orden de las imágenes.
  • El texto importante puede estar fuera de las celdas: cuadros de texto (números de formulario, marcas de revisión), comentarios, encabezados/pies de página. Los cuadros de texto y comentarios se extraen; los encabezados/pies de página no: revísalos en Excel si falta un número de documento.
  • El color puede ser datos (aprobado/fallido, nivel de riesgo, estado). Este script no decodifica rellenos ni formato condicional; si los colores tienen significado, inspecciónalos con openpyxl o una exportación de página y describe la correspondencia.
  • Los rangos combinados mantienen su valor solo en la celda superior izquierda; lee la línea combinado: antes de interpretar celdas en blanco.
  • Las hojas, filas y columnas ocultas se convierten y listan, no se eliminan. Indica si una respuesta proviene de contenido oculto.
  • No confíes en rutas con caracteres corruptos en una terminal; verifica que la ruta real exista antes de informar un archivo como faltante.

Limitaciones

  • Las imágenes flotantes se vinculan en su celda de anclaje superior izquierda; una imagen que abarca muchas celdas se lista con su celda_a en el manifiesto.
  • Las formas agrupadas se leen, pero las flechas y llamadas dibujadas como formas separadas mantienen su relación con una foto solo en una representación de página. Cuando el diseño importa ("qué flecha apunta hacia dónde"), exporta la hoja a PDF/PNG con Excel o LibreOffice y examínala junto con el Markdown.
  • Las imágenes en encabezados/pies de página (VML) y en comentarios no se extraen.
  • .xls necesita Microsoft Excel (Windows, pywin32) o LibreOffice para convertirse primero; sin ellos solo se leen valores de celda y el informe lo indica.

Skills relacionados