Skill
Skill XLSX (Excel)
Crédito: anthropics no GitHub (anthropics/skills) · 0 cópias
Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026
179,8 mil estrelas no GitHubVer no GitHub
Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).
--- name: xlsx description: "Use esta skill sempre que um arquivo de planilha for a principal entrada ou saída. Isso significa qualquer tarefa em que o usuário queira: abrir, ler, editar ou corrigir um arquivo .xlsx, .xlsm, .xltx, .csv ou .tsv existente (por exemplo, adicionar colunas, calcular fórmulas, formatar, criar gráficos, limpar dados bagunçados); criar uma planilha nova do zero ou a partir de outras fontes de dados; ou converter entre formatos de arquivos tabulares. Acione especialmente quando o usuário citar um arquivo de planilha por nome ou caminho — mesmo de modo informal (como \"o xlsx na minha pasta de downloads\") — e quiser que algo seja feito com ele ou produzido a partir dele. Acione também para limpar ou reestruturar arquivos de dados tabulares bagunçados (linhas malformadas, cabeçalhos fora do lugar, dados inúteis) transformando-os em planilhas adequadas. O entregável deve ser um arquivo de planilha. NÃO acione quando o principal entregável for um documento do Word, um relatório em HTML, um script Python independente, um pipeline de banco de dados ou uma integração com a API do Google Sheets, mesmo que haja dados tabulares envolvidos." license: Proprietary. LICENSE.txt has complete terms --- # Criação, edição e análise de XLSX | Tarefa | Abordagem | |---|---| | **Criar** ou **editar** com fórmulas/formatação | `openpyxl` — veja as pegadinhas abaixo | | **Dados em massa** entrando ou saindo | `pandas` (`read_excel`, `to_excel`) | | **Dar uma olhada rápida** em uma planilha | `markitdown file.xlsx` — `## SheetName` por planilha; lê `.xlsm` também. Sem coordenadas de célula, então não planeje edições a partir dele | | **Ler** um modelo (fórmulas *e* valores) | duas passadas de `load_workbook` — veja as pegadinhas | > `openpyxl`, `pandas` e `markitdown` já vêm pré-instalados — não rode `pip install` antes; escreva o script e importe diretamente. Somente se uma importação falhar (ou o comando `markitdown` não existir): faça `pip install` do pacote que faltar. > Os caminhos de scripts abaixo são relativos ao diretório desta skill. ## Requisitos para toda saída - **Fonte profissional** (Arial, Times New Roman) em todo o arquivo, a menos que o usuário diga o contrário. - **Zero erros de fórmula.** Nunca entregue enquanto o `recalc.py` relatar `errors_found`. Se você acha que um erro é anterior ao seu trabalho, prove: carregue o *original* com `data_only=True` e olhe aquela célula. Um erro que você introduziu parece exatamente com um que você herdou. - **Use fórmulas, nunca resultados fixos no código.** Escreva `sheet['B10'] = '=SUM(B2:B9)'`, e não o total calculado em Python. A planilha deve recalcular quando as entradas mudarem. - **Siga a especificação do usuário ao pé da letra.** Nomes exatos de abas, cabeçalhos de coluna exatos e a fórmula que ele descreveu. Um redesenho que calcule outra coisa fracassa, por mais elegante que seja. - **Documente toda suposição e todo número fixo no código** onde o leitor vá ver — um comentário de célula ou uma célula adjacente ao fim de uma tabela. Cite uma fonte real quando existir uma (`Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]`); quando o número veio do usuário, diga isso com clareza. - **Uma pasta de trabalho que *você cria* para alguém preencher** precisa de uma legenda curta dizendo quais células editar e de uma linha de exemplo com valores realistas que mostre o formato esperado. Nunca adicione uma linha dessas a um arquivo que lhe pediram para editar. - **Ao editar um arquivo existente: siga exatamente as convenções dele.** Elas prevalecem sobre toda diretriz aqui. Encontre primeiro as células de entrada designadas — uma cor de fonte, preenchimento ou sombreamento distintos as marcam — escreva apenas nelas e deixe intocada toda fórmula existente. ## Recalcular (obrigatório sempre que o arquivo contiver fórmulas) O openpyxl grava as fórmulas como strings **sem valores em cache**. Até você recalcular, toda célula de fórmula é lida como `None` por qualquer coisa que leia valores em cache — `pandas`, `load_workbook(data_only=True)` e a maioria dos visualizadores. ```bash python scripts/recalc.py output.xlsx [timeout_seconds] # default 30 ``` O LibreOffice calcula todas as fórmulas, o arquivo é **reescrito no lugar** e você recebe um JSON: `status` (`success` | `errors_found`), `total_formulas`, `total_errors` e um `error_summary` que nomeia até 100 células por tipo de erro (`locations_truncated` informa quantas foram omitidas — confie no `total_errors`, não no tamanho da lista). Corrija o que ele indicar e rode de novo. **Um JSON com uma chave `error` em vez de `status` significa que nada foi recalculado**, e só esse caso sai com código diferente de zero — `errors_found` sai com 0, então nunca trate uma saída limpa como uma pasta de trabalho limpa. **Um recalc verde prova que suas fórmulas *são avaliadas*, não que estão *certas*.** Um intervalo errado por um ou uma referência à linha errada geram um arquivo limpo, sem erros, com números errados. Escreva 2 ou 3 fórmulas primeiro e confira se elas trazem os valores esperados, antes de montar uma grade inteira. **Uma pasta de trabalho que tem vínculos com outro arquivo perde esses vínculos** se você salvá-la de novo com o openpyxl e depois recalcular. Uma fórmula assim se parece com `='[1]Returns Analysis'!$B$2` — o `[1]` é um índice na lista de referências externas da pasta de trabalho, que nomeia um *arquivo separado em disco*, não uma planilha. Esse arquivo raramente está presente aqui, então o valor em cache da célula é a única coisa que guarda os dados dela. O openpyxl remove esse valor ao salvar; o LibreOffice então precisa resolver a referência de verdade, falha, grava `#NAME?` e exclui todos os vínculos. O `recalc.py` se recusa a rodar nesse estado — copie os valores dessas células do original antes de salvar por cima (`--force` ignora a recusa e aceita a perda). ## Escolhendo fórmulas que sobrevivem à verificação O LibreOffice implementa menos funções do que o Excel, e uma que ele não consiga avaliar vira um `#NAME?` literal gravado no arquivo que você entrega. - **Prefira funções da era do Excel 2007** — `SUMIFS`, `INDEX`, `MATCH`, `IFERROR`, `SUMPRODUCT` — que não precisam de prefixo. - **Seis funções posteriores a 2007 funcionam, mas só com o prefixo `_xlfn.`**, porque o openpyxl grava sua fórmula no XML literalmente e o Excel armazena nomes posteriores a 2007 com prefixo (a interface dele esconde o prefixo): `_xlfn.TEXTJOIN`, `_xlfn.CONCAT`, `_xlfn.IFS`, `_xlfn.SWITCH`, `_xlfn.MAXIFS`, `_xlfn.MINIFS`. Escritas sem o prefixo, cada uma gera `#NAME?`. - **Nunca use `XLOOKUP`, `XMATCH`, `SORT`, `FILTER`, `UNIQUE` nem `SEQUENCE`.** O LibreOffice do ambiente de execução não consegue avaliá-las com *nenhum* prefixo. Versões mais novas as avaliam, mas são funções de matriz com derramamento e um arquivo gravado pelo openpyxl não tem metadados de derramamento, então só a célula do canto superior esquerdo do intervalo recebe valor — e o `recalc.py` informa `total_errors: 0` sobre o resultado truncado. Use `INDEX`/`MATCH` para buscas e ordene, filtre e remova duplicatas em Python antes de gravar as células. - Uma fórmula que o LibreOffice não conseguiu interpretar é gravada de volta **em minúsculas** — um sinal rápido ao lado de um `#NAME?`. ## Pegadinhas do openpyxl - **Ler um modelo exige dois carregamentos.** O `data_only=True` entrega os valores em cache sem as fórmulas; o padrão entrega as strings das fórmulas sem os valores. Uma só passada não dá os dois. - **O `data_only=True` é destrutivo se você salvar.** Essa pasta de trabalho não tem mais fórmulas, então salvar substitui todas por literais — de forma permanente. - **O `data_only=True` em um arquivo que o openpyxl acabou de gravar retorna `None` em tudo** — rode o `recalc.py` primeiro. (Uma fórmula cujo resultado é `""` também é lida como `None`.) - **Células mescladas: escreva apenas na âncora do canto superior esquerdo.** Todas as outras células do intervalo são uma `MergedCell` cujo `.value` é somente leitura. - **O `.xlsm` perde as macros, a menos que você passe `keep_vba=True`** ao `load_workbook`. - **O nome de uma planilha com espaço deve ficar entre aspas** em uma referência entre planilhas: `='Assumptions Inputs'!$B$5`. Sem aspas, resulta em `#VALUE!`. ## Modelos financeiros A menos que o usuário diga o contrário, ou o arquivo existente já faça de outro jeito. **Cor:** texto azul (`0,0,255`) para entradas fixas e alavancas de cenário · preto para fórmulas · verde (`0,128,0`) para vínculos com outra planilha · vermelho (`255,0,0`) para vínculos com outro arquivo · preenchimento amarelo (`255,255,0`) para suposições-chave e células que o usuário deve preencher. **Números:** moeda `$#,##0`, com a unidade nomeada no cabeçalho (`Revenue ($mm)`) · zeros exibidos como `-`, inclusive em percentuais (`$#,##0;($#,##0);-`) · negativos entre parênteses · percentuais `0.0%`, **armazenados como frações** (`0.15` exibe `15.0%`; armazenar `15` exibe `1500.0%`) · múltiplos de avaliação `0.0x` · anos como texto (`"2024"`, nunca `2,024`). **Estrutura:** toda suposição em sua própria célula rotulada, referenciada pelas fórmulas que a usam (`=B5*(1+$B$6)`, nunca `=B5*1.05`) · fórmulas consistentes em todos os períodos de projeção, pois uma célula editada isoladamente no meio de uma linha é o erro silencioso mais comum · proteja os denominadores que podem ser zero. ## Dependências `openpyxl`, `pandas`, `markitdown` (pip, pré-instalados — instale apenas se uma importação falhar ou o comando não existir) · LibreOffice (`soffice`, configurado automaticamente para ambientes em sandbox por meio de `scripts/office/soffice.py`)
Funciona com:Claude

