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

name, description

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

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)

Workflows Excel

CRITICO: Usar formulas, NAO valores hardcoded

Usar SEMPRE formulas Excel em vez de calcular valores em Python e hardcoda-los. Isto garante que a folha permanece dinamica e actualizavel.

ERRADO - Hardcoding de valores calculados

# Mau: calcular em Python e hardcodar resultado
total = df['Vendas'].sum()
sheet['B10'] = total  # Hardcoda 5000

# Mau: calcular taxa de crescimento em Python
growth = (df.iloc[-1]['Receita'] - df.iloc[0]['Receita']) / df.iloc[0]['Receita']
sheet['C5'] = growth  # Hardcoda 0.15

# Mau: calculo Python para media
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcoda 42.5

CORRECTO - Usar formulas Excel

# Bom: deixar Excel calcular a soma
sheet['B10'] = '=SUM(B2:B9)'

# Bom: taxa de crescimento como formula Excel
sheet['C5'] = '=(C4-C2)/C2'

# Bom: media usando funcao Excel
sheet['D20'] = '=AVERAGE(D2:D19)'

Isto aplica-se a TODOS os calculos - totais, percentagens, racios, diferencas, etc. A folha deve poder recalcular quando os dados de origem mudam.

Workflow comum

1. Escolher ferramenta: pandas para dados, openpyxl para formulas/formatacao
2. Criar/Carregar: Criar novo workbook ou carregar ficheiro existente
3. Modificar: Adicionar/editar dados, formulas e formatacao
4. Guardar: Escrever para ficheiro
5. Recalcular formulas (OBRIGATORIO SE USAR FORMULAS): Usar o script scripts/recalc.py

   python scripts/recalc.py output.xlsx
   

6. Verificar e corrigir erros:
   • O script retorna JSON com detalhes de erros
   • Se status for errors_found, verificar error_summary para tipos e localizacoes
   • Corrigir os erros identificados e recalcular novamente
   • Erros comuns a corrigir:
     • #REF!: Referencias de celula invalidas
     • #DIV/0!: Divisao por zero
     • #VALUE!: Tipo de dados errado na formula
     • #NAME?: Nome de formula nao reconhecido

Criar novos ficheiros Excel

# Usando openpyxl para formulas e formatacao
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Adicionar dados
sheet['A1'] = 'Descricao'
sheet['B1'] = 'Valor'
sheet.append(['Linha', 'de', 'dados'])

# Adicionar formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatacao
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Largura da coluna
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

Editar ficheiros Excel existentes

# Usando openpyxl para preservar formulas e formatacao
from openpyxl import load_workbook

# Carregar ficheiro existente
wb = load_workbook('existente.xlsx')
sheet = wb.active  # ou wb['NomeFolha'] para folha especifica

# Trabalhar com multiplas folhas
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Folha: {sheet_name}")

# Modificar celulas
sheet['A1'] = 'Novo Valor'
sheet.insert_rows(2)  # Inserir linha na posicao 2
sheet.delete_cols(3)  # Eliminar coluna 3

# Adicionar nova folha
new_sheet = wb.create_sheet('NovaFolha')
new_sheet['A1'] = 'Dados'

wb.save('modificado.xlsx')

Recalcular formulas

Ficheiros Excel criados ou modificados com openpyxl contem formulas como strings mas nao valores calculados. Usar o script scripts/recalc.py para recalcular formulas:

python scripts/recalc.py <ficheiro_excel> [timeout_segundos]

Exemplo:

python scripts/recalc.py output.xlsx 30

O script:

• Configura automaticamente a macro LibreOffice na primeira execucao
• Recalcula todas as formulas em todas as folhas
• Analisa TODAS as celulas a procura de erros Excel (#REF!, #DIV/0!, etc.)
• Retorna JSON com localizacoes e contagens detalhadas de erros
• Funciona em Linux e macOS

Checklist de verificacao de formulas

Verificacoes rapidas para garantir que as formulas funcionam correctamente:

Verificacao essencial

• Testar 2-3 referencias exemplo: Verificar que obtem valores correctos antes de construir modelo completo
• Mapeamento de colunas: Confirmar que colunas Excel correspondem (ex.: coluna 64 = BL, nao BK)
• Offset de linhas: Lembrar que linhas Excel sao 1-indexed (DataFrame linha 5 = Excel linha 6)

Armadilhas comuns

• Tratamento de NaN: Verificar valores nulos com pd.notna()
• Colunas distantes: Dados FY frequentemente em colunas 50+
• Multiplas correspondencias: Pesquisar todas as ocorrencias, nao apenas a primeira
• Divisao por zero: Verificar denominadores antes de usar / em formulas (#DIV/0!)
• Referencias erradas: Verificar que todas as referencias apontam para celulas pretendidas (#REF!)
• Referencias entre folhas: Usar formato correcto (Folha1!A1) para ligar folhas

Estrategia de teste de formulas

• Comecar pequeno: Testar formulas em 2-3 celulas antes de aplicar amplamente
• Verificar dependencias: Confirmar que todas as celulas referenciadas existem
• Testar edge cases: Incluir zero, negativos e valores muito grandes

Interpretar output do scripts/recalc.py

O script retorna JSON com detalhes de erros:

{
  "status": "success",
  "total_errors": 0,
  "total_formulas": 42,
  "error_summary": {
    "#REF!": {
      "count": 2,
      "locations": ["Folha1!B5", "Folha1!C10"]
    }
  }
}

Boas praticas

Seleccao de biblioteca

• pandas: Melhor para analise de dados, operacoes em massa e exportacao simples
• openpyxl: Melhor para formatacao complexa, formulas e funcionalidades especificas do Excel

Trabalhar com openpyxl

• Indices de celula sao 1-based (row=1, column=1 refere-se a celula A1)
• Usar data_only=True para ler valores calculados: load_workbook('ficheiro.xlsx', data_only=True)
• Atencao: Se aberto com data_only=True e guardado, as formulas sao substituidas por valores e perdidas permanentemente
• Para ficheiros grandes: Usar read_only=True para leitura ou write_only=True para escrita
• Formulas sao preservadas mas nao avaliadas — usar scripts/recalc.py para actualizar valores

Trabalhar com pandas

• Especificar tipos de dados para evitar problemas de inferencia: pd.read_excel('ficheiro.xlsx', dtype={'id': str})
• Para ficheiros grandes, ler colunas especificas: pd.read_excel('ficheiro.xlsx', usecols=['A', 'C', 'E'])
• Tratar datas correctamente: pd.read_excel('ficheiro.xlsx', parse_dates=['coluna_data'])

Estilo de codigo

IMPORTANTE: Ao gerar codigo Python para operacoes Excel:

• Escrever codigo Python minimo e conciso sem comentarios desnecessarios
• Evitar nomes de variaveis verbosos e operacoes redundantes
• Evitar print statements desnecessarios

Para os ficheiros Excel em si:

• Adicionar comentarios em celulas com formulas complexas ou pressupostos importantes
• Documentar fontes de dados para valores hardcoded
• Incluir notas para calculos-chave e seccoes do modelo

---

Integracao Descomplicar

Acesso a ficheiros via MCP filesystem

# Ler ficheiros do sistema local
mcp__filesystem__read_file(path="/media/ealmeida/Dados/...")

# Listar ficheiros para encontrar spreadsheets
mcp__filesystem__list_directory(path="/media/ealmeida/Dados/GDrive/Cloud/Descomplicar/")

Integracao com Moloni (facturacao)

Para exportar dados de facturacao Moloni para Excel:

# Obter facturas do Moloni
mcp__moloni__moloni_documents_invoices_getall(company_id=..., year=2026)

# Obter produtos
mcp__moloni__moloni_products_products_getall(company_id=..., category_id=...)

# Obter clientes
mcp__moloni__moloni_entities_customers_getall(company_id=...)

Integracao com Desk CRM

Para exportar dados do CRM para Excel:

# Relatorio de clientes
mcp__desk-crm-v3__get_customers(limit=100)

# Relatorio de facturas
mcp__desk-crm-v3__invoice_analytics(period="this_year")

# Relatorio de despesas
mcp__desk-crm-v3__expense_analytics(period="this_year")

Tabela de precos Descomplicar

O ficheiro de referencia de precos esta em: /media/ealmeida/Dados/GDrive/Cloud/Descomplicar/Servicos/tabela-geral.csv

---

Versao: 1.0.0 | Autor: Descomplicar®