Emanuel Almeida
6b3a6f2698
- 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>
5.3 KiB
name, description
| name | description |
|---|---|
| expense | Gestao de despesas Desk CRM com PDF obrigatorio. Registar, categorizar e analisar despesas com verificacao de duplicados, upload SFTP e arquivo mensal automatico. |
/expense - Gestao de Despesas
Skill para gestao de despesas com verificacao obrigatoria de categorias existentes.
Quando Usar
- Registar nova despesa
- Criar/gerir categorias de despesas
- Consultar despesas por periodo/categoria
- Associar despesas a projectos/clientes
- Analise e relatorios de despesas
- Processar despesas de tickets de contabilidade (departamento 3)
- Importar recibos de servicos (Anthropic, Hetzner, etc.)
Quando NAO Usar
- Para facturas a clientes (usar /invoice)
- Para orcamentos (usar /orcamento)
- Para pagamentos recebidos (usar /crm)
REGRA CRITICA: CATEGORIAS
PROIBIDO criar categoria sem verificar se ja existe.
1. Listar categorias: get_expense_categories(with_stats=true)
2. Pesquisar por nome similar na lista
3. SE encontrar match ou similar: USAR a categoria existente
4. SE realmente nao existe: PERGUNTAR "Nao encontrei categoria para X. Criar nova?"
5. SO CRIAR apos confirmacao explicita
Violacao desta regra causa duplicados que prejudicam relatorios financeiros.
Para mapeamento completo de fornecedores, emails e padroes PDF para categorias: ver references/category-mapping.md
Protocolo: Registar Despesa
Gate PDF obrigatorio: Sem documento, nao regista. Unica excepcao: bypass explicito do utilizador (AT/Salario sem recibo).
1. GATE PDF: Verificar que existe ficheiro PDF
- SE utilizador forneceu PDF: prosseguir
- SE nao forneceu: PEDIR o ficheiro
- SE nao tem e pede bypass: PERGUNTAR "Confirmas despesa sem documento?"
- Bypass valido apenas para: AT, Salarios, transferencias bancarias
2. LER O PDF: Extrair dados reais do documento
- NUNCA copiar valor de um PDF para outro
3. OBRIGATORIO: get_expense_categories(with_stats=true)
4. Identificar categoria correcta na lista
5. VERIFICAR DUPLICADOS:
- get_expenses(search: "<fornecedor>")
- Mesmo fornecedor + valor + data = duplicado
- Mesmo numero factura = duplicado
6. Recolher dados:
- category_id, amount, currency (EUR=3, USD=2), date (YYYY-MM-DD)
- note (incluir numero factura), send_invoice_to_customer = 0
- Opcionais: client_id, project_id, billable, tax
7. CONFIRMAR com utilizador (mostrar resumo)
8. create_expense
9. UPLOAD PDF ao Desk via SFTP:
a. mkdir -p no servidor: /home/ealmeida/desk.descomplicar.pt/uploads/expenses/<id>
b. mcp__ssh-unified__sftp_upload(server:"desk", local_path, remote_path)
c. chown -R ealmeida:ealmeida
d. INSERT INTO tblfiles (rel_id, rel_type='expense', ...)
10. ARQUIVO MENSAL: Mover PDF para Contabilidade/YYYY/NN-NomeMes/
11. Confirmar criacao ao utilizador
Protocolo: Criar Categoria
1. get_expense_categories() - listar todas
2. Verificar se existe categoria similar
3. SE existe similar: USAR ESSA, nao criar
4. SE nao existe: perguntar confirmacao ao utilizador
5. SO APOS confirmacao: criar
Protocolo: Consultar Despesas
1. get_expenses com filtros: category, date_from/date_to, client_id, project_id, limit
2. Apresentar resumo ao utilizador
Protocolo: Analise de Despesas
1. expense_analytics: period ("month"/"quarter"/"year"), breakdown_by ("category"/"client"/"project")
2. Apresentar insights: total por categoria, tendencias, categorias mais usadas
Processar Despesas de Tickets
Para protocolo completo de processamento de tickets de contabilidade: ver references/ticket-processing.md
Resumo: Obter ticket -> verificar anexos -> verificar duplicados -> extrair dados -> confirmar -> criar despesa -> upload PDF -> arquivo mensal.
Comandos
| Comando | Descricao |
|---|---|
/expense create |
Registar nova despesa |
/expense list |
Listar despesas recentes |
/expense categories |
Listar categorias disponiveis |
/expense report [periodo] |
Relatorio de despesas |
/expense search [termo] |
Pesquisar despesas |
MCP Tools
Despesas: get_expenses, create_expense, update_expense, delete_expense, bill_expense_to_customer
Categorias: get_expense_categories (usar with_stats=true)
Analise: expense_analytics
Anti-Patterns (NUNCA fazer)
Categorias:
- Criar categoria sem listar existentes primeiro
- Assumir que categoria nao existe
- Criar categoria com nome similar a existente
Despesas: 4. Criar despesa sem category_id 5. Nao validar data (formato YYYY-MM-DD) 6. Criar despesa sem verificar duplicados primeiro
Valores de PDFs: 7. Assumir que ficheiros com nomes semelhantes tem o mesmo valor 8. SEMPRE ler CADA PDF individualmente para extrair o valor real
Tickets: 9. Processar ticket sem verificar anexos PDF 10. Assumir que ticket com recibo = despesa nao lancada
Checklist Pre-Operacao
- Listar categorias existentes
- Validar categoria correcta
- Confirmar dados com utilizador
- Usar formato data YYYY-MM-DD
- Incluir nota descritiva
Referencias
references/category-mapping.md- Mapeamento fornecedores, emails, padroes PDF, campos, moedas, SQLreferences/ticket-processing.md- Protocolo completo de processamento de ticketsreferences/changelog.md- Historico de alteracoes
Criado: 2026-02-05 | Actualizado: 2026-02-12