xlsx: tratar a planilha como entregável principal

Para quem

Quando uma planilha é a entrada ou saída principal, use este guia xlsx. Cobre abrir, ler, editar ou reparar arquivos .xlsx, .xlsm, .xltx, .csv ou .tsv existentes. O entregável deve ser um arquivo de planilha.

Não dispare isto quando o entregável principal for um documento Word, um relatório HTML, um script Python independente, um pipeline de banco de dados ou uma integração Google Sheets API, mesmo que no meio haja dados tabulares. O material não lista produtos de agente; não trate isso como exclusivo de um software. A página oficial do guia é

https://raw.githubusercontent.com/anthropics/skills/main/skills/xlsx/SKILL.md

Primeira tentativa em 3 minutos

Caminho recomendado: openpyxl, pandas e markitdown já vêm pré-instalados. Não faça pip install primeiro; escreva um script e importe-os diretamente.

Pré-requisito: o ambiente atual consegue importar essas três bibliotecas diretamente. A primeira tentativa de baixo risco é uma olhada somente leitura; ainda não grave em disco. Para um arquivo local que já existe, importe markitdown para uma visão rápida. Se o arquivo não existir, pare na falha de abertura; não crie uma planilha de exemplo sem nome.

Sinal de sucesso: a importação funciona e você vê um resumo em texto desse arquivo. Isto não é reparo nem sobrescrita. Se ainda não houver arquivo e o usuário pedir explicitamente uma planilha, passe a criar com openpyxl, mas confirme o nome e o risco de sobrescrita antes de gravar.

Ao criar, lembre: use fórmulas; não grave resultados fixos que o Python já calculou. O exemplo do material escreve uma célula como =SUM(B2:B9) para a planilha poder recalcular quando as entradas mudarem.

Casos de uso

Caso 1: criar ou alterar uma planilha que recalcula. Escreva um script com o openpyxl pré-instalado. Após importar, escreva totais como fórmulas — por exemplo B10 usa =SUM(B2:B9) — em vez de somar no Python e gravar um número. O critério de conclusão: o arquivo contém fórmulas e a planilha pode recalcular após mudanças de entrada. O resumo deixa pandas para leitura/gravação em lote e markitdown para a visão rápida; este caso cobre só a escrita de fórmulas. O trecho não dá uma API de estilo completa; não invente funções de formatação que não aparecem.

Caso 2: um arquivo com fórmulas deve ser recalculado antes de ler valores. O material afirma: sempre que o arquivo contém fórmulas, o recálculo é obrigatório. openpyxl escreve fórmulas como strings e não tem valores em cache; até você recalcular, cada célula de fórmula volta como None. Isto é uma checagem reversível: abra o arquivo que acabou de gravar e leia uma célula de fórmula; se obtiver None, o recálculo ainda não aconteceu — pare aí, termine o recálculo e só então trate o valor lido como resultado. Não interprete None como um total zero.

Limites de uso

Use só quando a planilha em si for o entregável principal. Word, HTML, scripts independentes, pipelines de banco de dados e Google Sheets API não tomam este caminho mesmo que contenham tabelas. As três bibliotecas estão pré-instaladas; por padrão não faça pip install primeiro. As fórmulas devem poder recalcular quando as entradas mudam; depois de gravar é obrigatório recalcular, senão a leitura volta None.

Não escreva um caminho de repositório que não aparece como comando de instalação. Não faça números fixos passarem por totais. Antes de gravar em disco ou sobrescrever a planilha original, confirme o caminho de destino e os efeitos colaterais e só então execute. Além destes tipos de arquivo, desta forma de importar e destes requisitos de recálculo já escritos, este guia não cobre o resto.