xls-skill

Converte pastas de trabalho do Excel (.xlsx/.xlsm/.xls) em Markdown legível por IA, mantendo cada imagem em sua célula original — incluindo imagens incorporadas DENTRO de células (WPS Office =DISPIMG e Microsoft 365 "Place in Cell"), que os leitores normais de Excel silenciosamente ignoram — além de imagens flutuantes, caixas de texto, fórmulas, estrutura mesclada/oculta e OCR. Use ao ler, converter, auditar ou responder perguntas sobre planilhas que contêm fotos, etiquetas, logotipos, capturas de tela, desenhos ou assinaturas em células ou sobre a grade.

O que é xls-skill?

Esta skill resolve um problema comum, mas negligenciado: ao extrair dados de planilhas do Excel, a maioria das ferramentas (openpyxl, pandas, exportação CSV) captura apenas os valores das células, perdendo completamente as imagens que estão dentro das células ou flutuando sobre a grade. xls-skill lida especificamente com dois tipos de perda de imagem: (1) imagens incorporadas em células do WPS Office (que mostram `=DISPIMG(...)`) e Microsoft 365 (que mostram `#VALUE!`), e (2) imagens flutuantes e caixas de texto. Ele extrai todas essas imagens, salva cada uma como um arquivo e as insere de volta na tabela Markdown gerada, exatamente na célula onde pertencem. Isso permite que um agente de IA ou usuário humano veja a tabela e suas imagens juntas, facilitando a compreensão visual dos dados. A skill é útil para desenvolvedores, analistas de dados e profissionais de IA que precisam converter planilhas complexas do Excel para um formato que preserva a integridade visual, como fotos de produtos, assinaturas, logotipos e diagramas. Ela suporta os formatos .xlsx, .xlsm e .xls, gera diversos arquivos de saída (Markdown com imagens inline, manifestos de imagens, fórmulas e formas, relatório de conversão em JSON) e oferece OCR opcional para extrair texto de dentro das imagens. A documentação (SKILL.md) também define um fluxo de trabalho para o agente, instruindo a verificar o relatório de conversão primeiro, inspecionar as imagens e relatar lacunas honestamente, seguindo regras sobre dados ocultos, cores, intervalos mesclados e formatos de imagem não suportados.

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

Installed? Explore more Produtividade e Colaboração skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

Peças!B2

Documentação

xls-skill: Excel -> Markdown, imagens mantidas em suas células

Por que esta skill existe

A maioria dos leitores de Excel (openpyxl, pandas, exportação CSV) vê apenas os valores das células. Dois tipos de imagens são perdidos:

  1. Imagens em célula. A imagem é o conteúdo de uma célula.
    • WPS Office "incorporar na célula": a célula mostra apenas =DISPIMG("ID_...",1); a imagem está em xl/cellimages.xml.
    • Microsoft 365 "Place in Cell" / IMAGE: a célula mostra #VALUE!; a imagem é alcançada por meio de xl/metadata.xml e xl/richData/.
  2. Imagens flutuantes e caixas de texto desenhadas sobre a grade (processar fotos, etiquetas, números de formulários).

Esta skill extrai todas elas, salva cada imagem como um arquivo e as insere de volta na tabela Markdown na célula onde vive, para que um leitor veja a tabela e suas imagens juntas:

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | Suporte | ![Peças!B2](images/01_Peças_B2_cel1.png) | Suporte \| imagem em célula | 4 |

Como executar

python <skill-dir>/scripts/xlsx_to_md.py <arquivo-ou-pasta> [...] -o <dir-saida> [--ocr auto|off] [--ocr-lang eng+chi_sim]
  • Aceita .xlsx, .xlsm, .xls ou pastas (recursivo). Imprime uma linha por pasta de trabalho com contagens de imagens.
  • Requer Python 3.9+ e openpyxl. Opcional: Pillow (tamanhos de imagem), Tesseract OCR (texto dentro de imagens), Microsoft Excel ou LibreOffice (para abrir .xls).
  • Autoteste: python <skill-dir>/tests/run_tests.py constrói pastas de trabalho sintéticas do WPS e Microsoft 365 e verifica se cada imagem está em sua célula.

O que você obtém por pasta de trabalho (<dir-saida>/<nome>/)

ArquivoConteúdo
<nome>.mdÍndice da pasta de trabalho, depois cada planilha como uma tabela Markdown completa (sem truncamento) com imagens inline em suas células; fatos da planilha (estado oculto, intervalos mesclados, linhas/colunas ocultas, comentários, caixas de texto, contagem de gráficos) acima de cada tabela
<nome>.images.mdUma entrada por imagem: a imagem, planilha!célula, tipo, tamanho, texto de célula vizinha, texto OCR e um espaço para descrição
images/Cada imagem como um arquivo, nomeado `<plan#><célula>_<célula
sheets_csv/Valores da planilha; células de imagem contêm [image: images/...]
image_manifest.csvplanilha, célula, tipo (in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / flutuante), arquivo, parte do pacote, texto alternativo, tamanho, OCR, texto vizinho
formula_manifest.csvTexto da fórmula e valor em cache por célula
shapes_manifest.csvTexto de caixas de texto/formas flutuantes, com célula de âncora
conversion_report.jsonContagens, avisos, review_required

Fluxo de trabalho para o agente

  1. Converter. Execute o script na(s) pasta(s) de trabalho.
  2. Leia o relatório primeiro. Abra conversion_report.json. Aja sobre cada aviso:
    • image not found in package -> a célula está marcada como [image missing: ID]; informe isso, não adivinhe a imagem.
    • .emf/.wmf saved as-is -> converta para PNG (ex.: Pillow no Windows, LibreOffice em outros lugares) antes de examiná-la.
    • charts > 0 -> gráficos são contados, não renderizados; abra ou exporte a planilha se o gráfico for importante.
    • OCR ignorado ou idioma ausente -> confie em examinar as imagens você mesmo.
  3. Observe as imagens. Abra cada arquivo listado em <nome>.images.md e substitua cada espaço reservado description pelo que a imagem mostra: objeto, texto legível (etiquetas, números de modelo, marcas), símbolos e como se relaciona com as células vizinhas. OCR é uma dica, não a resposta; texto de etiqueta pequena geralmente precisa de um recorte ou zoom.
  4. Responda a partir da tabela e das imagens juntas. Use a tabela Markdown para valores exatos de células, fórmulas e estrutura; use as imagens para "como é / o que está escrito na peça". Cite planilha!célula para ambos.
  5. Relate lacunas honestamente. Se algo na etapa 2 permaneceu não resolvido, marque a pasta de trabalho como necessitando de revisão manual.

Regras

  • Uma tabela CSV ou apenas de valores não é evidência completa quando a pasta de trabalho tem imagens, caixas de texto, cores ou conteúdo oculto. Verifique os fatos da planilha e manifestos.
  • Emparelhe cada imagem com sua célula e vizinhas; nunca confie apenas na ordem das imagens.
  • Texto importante pode viver fora das células: caixas de texto (números de formulário, marcas de revisão), comentários, cabeçalhos/rodapés. Caixas de texto e comentários são extraídos; cabeçalhos/rodapés não - verifique-os no Excel se um número de documento estiver faltando.
  • Cor pode ser dado (aprovado/reprovado, nível de risco, status). Este script não decodifica preenchimentos ou formatação condicional; se as cores carregam significado, inspecione-as com openpyxl ou uma exportação de página e declare o mapeamento.
  • Intervalos mesclados mantêm seu valor apenas na célula superior esquerda; leia a linha merged: antes de interpretar células em branco.
  • Planilhas, linhas e colunas ocultas são convertidas e listadas, não descartadas. Diga quando uma resposta vem de conteúdo oculto.
  • Não confie em caminhos mojibake em um terminal; verifique se o caminho real existe antes de relatar um arquivo como ausente.

Limitações

  • Imagens flutuantes são vinculadas em sua célula âncora superior esquerda; uma imagem abrangendo muitas células é listada com seu to_cell no manifesto.
  • Formas agrupadas são lidas, mas setas e balões desenhados como formas separadas mantêm sua relação com uma foto apenas em uma renderização de página. Quando o layout importa ("qual seta aponta para onde"), exporte a planilha para PDF/PNG com Excel ou LibreOffice e observe-a junto com o Markdown.
  • Imagens em cabeçalhos/rodapés (VML) e em comentários não são extraídas.
  • .xls precisa do Microsoft Excel (Windows, pywin32) ou LibreOffice para converter primeiro; sem eles, apenas os valores das células são lidos e o relatório informa isso.

Habilidades Relacionadas