Pular para o conteúdo
UseIA
0
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
Salvar

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`)