feat: refactor 30+ skills to Anthropic progressive disclosure pattern
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
374
dev-tools/skills/xlsx/SKILL.md
Normal file
374
dev-tools/skills/xlsx/SKILL.md
Normal file
@@ -0,0 +1,374 @@
|
||||
---
|
||||
name: xlsx
|
||||
description: 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**:
|
||||
|
||||
```python
|
||||
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
|
||||
```python
|
||||
# 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
|
||||
```python
|
||||
# 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
|
||||
```bash
|
||||
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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
python scripts/recalc.py <ficheiro_excel> [timeout_segundos]
|
||||
```
|
||||
|
||||
Exemplo:
|
||||
```bash
|
||||
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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```python
|
||||
# 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:
|
||||
```python
|
||||
# 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:
|
||||
```python
|
||||
# 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®
|
||||
Reference in New Issue
Block a user