claude-plugins/dev-tools/skills/xlsx/SKILL.md

name, description, layer

name	description	layer
xlsx	Criacao, edicao e analise de ficheiros Excel (.xlsx, .xlsm, .csv, .tsv) — formulas, formatacao, modelos financeiros e integracao com facturacao Moloni.	wiki

Excel / XLSX Specialist

Skill para manipulacao completa de folhas de calculo seguindo padroes Descomplicar®.

Quando Usar

• Abrir, ler, editar ou corrigir ficheiros .xlsx, .xlsm, .csv ou .tsv
• Criar nova folha de calculo a partir de dados ou de raiz
• Converter entre formatos tabulares
• Limpar ou reestruturar dados tabulares (linhas malformadas, cabecalhos deslocados, dados residuais)
• Exportar dados do Desk CRM ou Moloni para Excel
• O entregavel final deve ser um ficheiro de folha de calculo

Quando NAO Usar

• Quando o entregavel e um documento Word, relatorio HTML, script Python isolado ou pipeline de base de dados
• Para integracoes Google Sheets API
• Quando outra skill mais especifica esta disponivel

---

Requisitos para Outputs

Todos os ficheiros Excel

Fonte profissional

• Usar fonte consistente e profissional (ex.: Arial, Times New Roman) salvo indicacao contraria

Zero erros de formula

• Todo ficheiro Excel DEVE ser entregue com ZERO erros de formula (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

Preservar templates existentes (ao actualizar)

• Estudar e reproduzir EXACTAMENTE o formato, estilo e convencoes do ficheiro existente
• Nunca impor formatacao padronizada sobre ficheiros com padroes estabelecidos
• Convencoes do template existente SEMPRE prevalecem sobre estas directrizes

Modelos financeiros

Convencoes financeiras Portugal

Formato monetario

• Moeda: EUR (nunca USD por defeito)
• Formato numerico: #.##0,00 EUR (separador milhares: ponto, separador decimal: virgula)
• Exemplo: 1.234,56 EUR (nao $1,234.56)
• Negativos: Parenteses (1.234,56) e nao -1.234,56
• Formato Excel: #.##0,00 €;(#.##0,00 €);"-"

Formato data

• Padrao: DD-MM-YYYY (ex.: 06-03-2026)
• Excel format code: DD-MM-YYYY
• Nunca: MM/DD/YYYY

Formato percentagem

• Por defeito 0,0% (uma casa decimal)

Codigo de cores padrao

Excepto se indicado pelo utilizador ou template existente

Convencoes standard da industria

• Texto azul (RGB: 0,0,255): Inputs hardcoded, numeros que o utilizador pode alterar para cenarios
• Texto preto (RGB: 0,0,0): TODAS as formulas e calculos
• Texto verde (RGB: 0,128,0): Links a outras folhas dentro do mesmo workbook
• Texto vermelho (RGB: 255,0,0): Links externos a outros ficheiros
• Fundo amarelo (RGB: 255,255,0): Pressupostos-chave ou celulas que precisam de actualizacao

Formato numerico

Regras obrigatorias

• Anos: Formatar como texto (ex.: "2024" e nao "2.024")
• Moeda: Usar #.##0,00 €; SEMPRE especificar unidades nos cabecalhos ("Receita (EUR)")
• Zeros: Usar formatacao para apresentar zeros como "-", incluindo percentagens
• Multiplos: Formato 0,0x para multiplos de avaliacao (EV/EBITDA, P/E)

Regras de construcao de formulas

Colocacao de pressupostos

• Colocar TODOS os pressupostos (taxas de crescimento, margens, multiplos, etc.) em celulas separadas
• Usar referencias a celulas em vez de valores hardcoded nas formulas
• Exemplo: Usar =B5*(1+$B$6) em vez de =B5*1,05

Prevencao de erros de formula

• Verificar que todas as referencias estao correctas
• Verificar erros off-by-one em intervalos
• Garantir formulas consistentes em todos os periodos de projecao
• Testar com edge cases (valores zero, numeros negativos)
• Verificar que nao existem referencias circulares involuntarias

Documentacao de hardcodes

• Comentar ou colocar em celulas adjacentes. Formato: "Fonte: [Sistema/Documento], [Data], [Referencia], [URL se aplicavel]"
• Exemplos:
  • "Fonte: Relatorio Anual, FY2024, Pagina 45, Nota Receitas"
  • "Fonte: Moloni, 06-03-2026, Extracto Vendas"
  • "Fonte: Desk CRM, 06-03-2026, Relatorio Clientes"

---

Criacao, edicao e analise de XLSX

Overview

O utilizador pode pedir para criar, editar ou analisar o conteudo de um ficheiro .xlsx. Existem ferramentas e workflows diferentes para tarefas diferentes.

Requisitos importantes

LibreOffice obrigatorio para recalculo de formulas: O LibreOffice deve estar instalado para recalcular valores de formula usando o script scripts/recalc.py. O script configura o LibreOffice automaticamente na primeira execucao, incluindo ambientes sandboxed onde Unix sockets sao restritos (tratado por scripts/office/soffice.py).

Leitura e analise de dados

Analise com pandas

Para analise de dados, visualizacao e operacoes basicas, usar pandas:

import pandas as pd

# Ler Excel
df = pd.read_excel('ficheiro.xlsx')  # Default: primeira folha
all_sheets = pd.read_excel('ficheiro.xlsx', sheet_name=None)  # Todas as folhas como dict

# Analisar
df.head()      # Preview dados
df.info()      # Info colunas
df.describe()  # Estatisticas

# Escrever Excel
df.to_excel('output.xlsx', index=False)