claude-plugins/marketing/skills/seo-report/SKILL.md

---
name: seo-report
description: >
  Complete SEO audit report with Lighthouse, Google Search Console, SEO Tools API and exports to Google Docs. Analyzes Core Web Vitals, performance, on-page SEO, backlinks and generates actionable recommendations.
  Use when auditing website SEO, analyzing performance metrics, generating client reports, or when user mentions
  "seo audit", "lighthouse", "core web vitals", "search console", "seo analysis", "performance report", "website audit", "google docs report".
author: Descomplicar® Crescimento Digital
version: 2.1.0
user_invocable: true
tags: [seo, audit, lighthouse, gsc, google-docs, core-web-vitals, performance]
desk_task: 1483
allowed-tools: mcp__lighthouse__run_audit, mcp__lighthouse__get_core_web_vitals, mcp__gsc__get_search_analytics, mcp__google-workspace__create_doc, WebFetch
category: content
quality_score: 90
updated: "2026-02-04T18:00:00Z"
---

# Skill: /seo-report

Gera relatório SEO completo com dados de múltiplas fontes e exporta automaticamente para Google Docs.

---

## 🎯 Trigger

`/seo-report <url>` ou `/seo-report <url> <email_destino>`

---

## 💡 Exemplos

```bash
# Relatório básico (envia para emanuelalmeidaa@gmail.com)
/seo-report https://descomplicar.pt

# Relatório para cliente específico
/seo-report https://cliente.pt cliente@email.com

# Relatório com análise concorrência
/seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt
```

---

## 📊 Fontes de Dados

| Fonte | Dados Recolhidos | Tempo |
|-------|------------------|-------|
| **Lighthouse (Desktop)** | Performance, SEO, Accessibility, Best Practices | ~30s |
| **Lighthouse (Mobile)** | Core Web Vitals, INP, comparação mobile/desktop | ~30s |
| **Lighthouse (Optimizações)** | Oportunidades LCP, JS não usado, images optimization | ~15s |
| **GSC** | Cliques, impressões, CTR, posição média, top queries, tendência 90 dias | ~10s |
| **SEO Tools API** | Meta tags, imagens, alt text, links internos/externos, estrutura HTML | ~5s |
| **Ahrefs (opcional)** | DR, UR, backlinks, referring domains | ~10s |

**Tempo Total:** ~1m40s (sem concorrência) | ~3m (com 2 concorrentes)

---

## 📄 Output - Google Doc

### Estrutura do Documento

```markdown
# Relatório SEO - [DOMÍNIO]
Data: YYYY-MM-DD | Versão 2.0 (2026 Standards)

---

## 🎯 Sumário Executivo

**Principais Descobertas (Top 5):**
1. [Crítico] Core Web Vitals - INP > 500ms (target < 200ms)
2. [Importante] E-E-A-T - Sem autor identificado em 80% dos artigos
3. [Melhoria] CTR GSC - Posição 4-10 com CTR < 3%
4. [Oportunidade] 15 keywords posição 11-20 (easy wins)
5. [Acção Imediata] 47 imagens sem alt text (SEO + A11y)

**Acção Imediata Recomendada:**
> Optimizar INP removendo 350KB JS não usado (-40% bundle size)
> ROI esperado: Posição média +2 ranks, CTR +0.8pp

---

## 📊 1. Pontuações Globais

### Desktop vs Mobile

| Métrica | Desktop | Mobile | Gap | Target 2026 |
|---------|---------|--------|-----|-------------|
| **Performance** | 85/100 🟡 | 62/100 🔴 | -23 | > 90 |
| **SEO** | 92/100 🟢 | 88/100 🟡 | -4 | > 95 |
| **Accessibility** | 78/100 🟡 | 78/100 🟡 | 0 | > 90 |
| **Best Practices** | 95/100 🟢 | 92/100 🟢 | -3 | > 95 |

**Análise Gap Mobile:** Dispositivos móveis representam 75% do tráfego. Gap de -23 pontos é crítico.

---

## ⚡ 2. Core Web Vitals

### Comparação Mobile vs Desktop

| Métrica | Mobile | Desktop | Threshold 2026 | Status |
|---------|--------|---------|----------------|--------|
| **LCP** | 2.8s | 1.9s | < 2.5s | 🟡 / ✅ |
| **INP** | 520ms | 180ms | < 200ms | 🔴 / ✅ |
| **CLS** | 0.08 | 0.05 | < 0.1 | ✅ / ✅ |

**Diagnóstico INP Mobile:**
- Main thread bloqueado 3.2s durante load
- Event handlers complexos (listeners + 200ms)
- Third-party scripts: Google Analytics, Facebook Pixel, Hotjar

### Oportunidades LCP

| Oportunidade | Savings | Prioridade |
|--------------|---------|------------|
| Preload imagem hero (`/images/hero.jpg`) | 1.2s | 🔴 Crítico |
| Lazy load below-fold (15 imagens) | 800ms | 🟡 Alto |
| Optimizar TTFB (servidor response) | 400ms | 🟡 Alto |
| Comprimir imagens WebP (85% quality) | 600ms | 🟢 Médio |

### Oportunidades INP

| Oportunidade | Savings | Prioridade |
|--------------|---------|------------|
| Remover JS não usado (350KB) | 280ms | 🔴 Crítico |
| Code splitting (carregar on-demand) | 180ms | 🟡 Alto |
| Defer third-party scripts | 120ms | 🟡 Alto |
| Optimizar event listeners | 80ms | 🟢 Médio |

---

## 🔍 3. GSC Analytics (Últimos 90 dias)

### Performance Overview

| Métrica | Valor | vs 90 dias anteriores | Tendência |
|---------|-------|------------------------|-----------|
| **Cliques** | 12,450 | +18% (+1,890) | 📈 |
| **Impressões** | 245,800 | +22% (+44,300) | 📈 |
| **CTR Médio** | 5.1% | -0.3pp | 📉 |
| **Posição Média** | 12.8 | +2.1 (pior) | 📉 |

**Análise de Tendência:**
- ✅ **Impressões crescem** - Conteúdo está a ganhar visibilidade
- ⚠️ **Posição média caiu** - Concorrência aumentou
- ⚠️ **CTR desceu** - Meta descriptions precisam optimização

### Top 10 Queries

| Query | Cliques | Impr. | CTR | Pos. | Oportunidade |
|-------|---------|-------|-----|------|--------------|
| energia solar fotovoltaica | 850 | 15,200 | 5.6% | 8.2 | 🟡 Optimizar para top 5 |
| painéis solares preço | 720 | 9,800 | 7.3% | 4.5 | ✅ Manter |
| instalação solar | 680 | 22,400 | 3.0% | 14.8 | 🔴 Melhorar CTR + posição |
| como funciona energia solar | 520 | 12,100 | 4.3% | 11.2 | 🟡 Easy win (target top 10) |
| ... | ... | ... | ... | ... | ... |

### Oportunidades Identificadas

**🎯 Quick Wins (Posição 11-20, > 1000 impressões):**
15 keywords com potencial top 10 através de optimização on-page

**🔴 CTR Abaixo da Média (Posição 1-10, CTR < 5%):**
8 keywords necessitam meta description rewrite

**📈 Trending Up (Crescimento > 50% impressões):**
- "bateria solar" - +120% impressões
- "autoconsumo energia" - +85% impressões

---

## 🛠️ 4. Análise On-Page

### Meta Tags Audit

| Página | Title | Description | Issues |
|--------|-------|-------------|--------|
| Homepage | ✅ 58 chars | ⚠️ 175 chars (muito longo) | Description > 160 chars |
| /servicos | ✅ 52 chars | ✅ 155 chars | - |
| /blog/energia-solar | ❌ 28 chars (curto) | ❌ Duplicado (5 páginas) | Title curto, description duplicada |
| ... | ... | ... | ... |

**Problemas Globais:**
- 12 páginas com title < 40 chars
- 8 páginas com description > 160 chars
- 5 páginas com meta description duplicada
- 3 páginas sem canonical URL

### Imagens SEO

| Métrica | Valor | Target | Status |
|---------|-------|--------|--------|
| **Total Imagens** | 127 | - | - |
| **Com Alt Text** | 80 (63%) | 100% | 🔴 |
| **Alt Text Descritivo** | 52 (41%) | 100% | 🔴 |
| **Formato WebP** | 15 (12%) | > 80% | 🔴 |
| **Lazy Loading** | 45 (35%) | 100% (below-fold) | 🟡 |

**Acção:** Adicionar alt text descritivo às 47 imagens sem texto.

### Internal Linking

| Métrica | Valor | Benchmark |
|---------|-------|-----------|
| **Links Internos Médios/Página** | 8.5 | > 10 bom |
| **Orphan Pages** | 3 | 0 ideal |
| **Broken Internal Links** | 7 | 0 |
| **Anchor Text Optimizado** | 42% | > 70% |

**Orphan Pages (sem links internos):**
1. `/blog/manutencao-paineis` (450 impressões/mês GSC)
2. `/faq/garantias` (280 impressões/mês)
3. `/recursos/calculadora` (190 impressões/mês)

---

## 🔗 5. Backlinks e Autoridade

### Perfil de Domínio

| Métrica | Valor | Benchmark | Status |
|---------|-------|-----------|--------|
| **Domain Rating (DR)** | 32 | > 40 bom | 🟡 |
| **URL Rating (UR) Médio** | 18 | > 25 bom | 🔴 |
| **Backlinks Totais** | 1,247 | - | - |
| **Referring Domains** | 87 | > 100 bom | 🟡 |
| **DoFollow** | 68% | > 60% | ✅ |

### Top 10 Backlinks (por DR)

| Domínio | DR | Anchor Text | DoFollow | Tipo |
|---------|-----|-------------|----------|------|
| portal-energia.pt | 58 | energia solar portugal | Sim | Editorial |
| apren.pt | 72 | apren-renewable-energy | Sim | Associação |
| jornaleconomico.pt | 65 | sector fotovoltaico | Sim | Media |
| energias-renovaveis.com | 48 | [Brand Name] | Sim | Directório |
| ... | ... | ... | ... | ... |

### Estratégia Backlinks Q1-Q2 2026

**🎯 Objectivo:** DR 40+ até Junho 2026

**Táticas:**
1. **Guest Posts** (Target: 6 posts, DR > 40)
   - portal-energia.pt - Artigo sobre inovação solar
   - ambientemagazine.pt - Case study instalação comercial
   - idealista.pt - Guia valorização imóvel com solar

2. **Broken Link Building** (15 oportunidades identificadas)
   - Links quebrados em sites DR > 35 no sector

3. **Digital PR**
   - Press release: Projecto inovador cliente X
   - Participação podcast "Energia do Futuro"
   - Webinar parceria APREN

---

## 🏆 6. Benchmarks vs Concorrência

### Comparação Performance

| Métrica | [Site] | Concorrente A | Concorrente B | Gap |
|---------|--------|---------------|---------------|-----|
| DR | 32 | 45 | 38 | -13 |
| Traffic Estimado | 12.5K/mês | 28K/mês | 18K/mês | -15.5K |
| Ranking Keywords | 450 | 820 | 610 | -370 |
| Backlinks | 1,247 | 3,200 | 2,100 | -1,953 |

### Keywords Gap

**Oportunidades (Keywords concorrentes não exploramos):**
1. "energia solar empresas" - Vol 2.4K, KD 35 (Concorrente A pos 3)
2. "comparar paineis solares" - Vol 1.8K, KD 28 (Concorrente B pos 5)
3. "custos instalação solar" - Vol 3.2K, KD 42 (Ambos top 10)

---

## 🎯 7. Plano de Acção (Priorizado)

### 🔴 Crítico (Semana 1-2)

| Acção | Impacto Estimado | Esforço | ROI |
|-------|------------------|---------|-----|
| **Optimizar INP Mobile** (remover JS não usado 350KB) | Posição média +2, CTR +0.8pp | 8h | 🔥 Alto |
| **Adicionar alt text 47 imagens** | Acessibilidade +15 pontos, SEO +5% | 3h | 🔥 Alto |
| **Corrigir 7 links internos quebrados** | UX, crawl efficiency +10% | 1h | ⭐ Médio |
| **Reescrever 8 meta descriptions** (CTR baixo) | CTR +1.2pp estimado | 2h | 🔥 Alto |

### 🟡 Importante (Semana 3-4)

| Acção | Impacto Estimado | Esforço | ROI |
|-------|------------------|---------|-----|
| **Optimizar 15 keywords posição 11-20** | +1,200 cliques/mês | 12h | ⭐ Médio |
| **Implementar E-E-A-T** (autor, bio, datas) | Trust signals, rankings +5% | 6h | ⭐ Médio |
| **Internal linking 3 orphan pages** | Indexabilidade, link equity | 2h | ⭐ Médio |
| **Converter imagens WebP** | LCP -600ms | 4h | ⭐ Médio |

### 🟢 Melhoria (Mês 2-3)

| Acção | Impacto Estimado | Esforço | ROI |
|-------|------------------|---------|-----|
| **Criar conteúdo keywords gap** (3 artigos) | +2K visitas/mês | 20h | ⭐ Médio |
| **Campanha backlinks DR > 40** (6 guest posts) | DR +5, autoridade | 30h | ⚡ Baixo |
| **Optimizar structured data** | Rich snippets, CTR +0.5pp | 6h | ⚡ Baixo |

---

## 📅 8. Roadmap Trimestral

### Mês 1: Fundação Técnica
**Objectivo:** Core Web Vitals All Green, SEO Score > 95

- Semana 1-2: Críticos (INP, alt text, links quebrados, meta descriptions)
- Semana 3-4: Importantes (keywords 11-20, E-E-A-T, orphan pages)

**KPIs:**
- INP Mobile < 200ms ✅
- SEO Score > 95 ✅
- CTR médio > 5.5% ✅

### Mês 2: Conteúdo e Autoridade
**Objectivo:** +30% tráfego orgânico, DR 38+

- Criar 3 artigos keywords gap (2.4K + 1.8K + 3.2K vol)
- 3 guest posts DR > 40
- Optimizar 20 artigos existentes (posição 11-30)

**KPIs:**
- Tráfego orgânico: 16K/mês (+28%) ✅
- Backlinks novos: +15 DR > 35 ✅
- DR: 38+ ✅

### Mês 3: Consolidação e Escala
**Objectivo:** Top 10 para 10+ keywords principais

- Monitorizar rankings e ajustar on-page
- 3 guest posts adicionais
- Expandir internal linking (cluster content)
- Actualizar conteúdo underperforming

**KPIs:**
- Keywords top 10: 25+ ✅
- Cliques GSC: 18K/mês (+44%) ✅
- Posição média: < 10.0 ✅

---

## 🔧 Ferramentas Utilizadas

- ✅ **Lighthouse MCP** - Performance, Core Web Vitals, Accessibility
- ✅ **Google Search Console MCP** - Queries, cliques, CTR, posição
- ✅ **SEO Tools API** - Meta tags, imagens, internal linking
- ✅ **Ahrefs API** (opcional) - DR, UR, backlinks
- ✅ **Google Workspace MCP** - Criação e partilha Google Doc

---

## 📊 Anexos

### A. Metodologia
- Lighthouse: 3 runs, mediana reportada
- GSC: Últimos 90 dias completos
- Thresholds: Google 2026 Standards

### B. Glossário
- **DR**: Domain Rating (Ahrefs)
- **INP**: Interaction to Next Paint (substitui FID em 2026)
- **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust
- **CTR**: Click-Through Rate

---

**Próxima Auditoria Recomendada:** [Data + 3 meses]
**Contacto Suporte:** recursos@descomplicar.pt
```

---

## 🔄 Workflow Técnico

```mermaid
graph LR
    A[Input: URL] --> B{Site em GSC?}
    B -->|Sim| C[Recolher dados GSC]
    B -->|Não| D[Skip GSC, aviso]

    C --> E[Lighthouse Desktop]
    D --> E

    E --> F[Lighthouse Mobile]
    F --> G[Core Web Vitals]
    G --> H[SEO Tools API]
    H --> I{Ahrefs habilitado?}

    I -->|Sim| J[Recolher DR/UR]
    I -->|Não| K[Skip Ahrefs]

    J --> L[Processar dados]
    K --> L

    L --> M[Gerar relatório Markdown]
    M --> N[Criar Google Doc]
    N --> O[Partilhar com email]

    O --> P[Retornar link]
```

### Implementação

```javascript
async function generateSEOReport(url, options = {}) {
  const {
    email = 'emanuelalmeidaa@gmail.com',
    competitors = [],
    includeAhrefs = true
  } = options;

  // 1. Validar URL
  if (!isValidURL(url)) {
    throw new Error('URL inválido');
  }

  // 2. Recolher dados em paralelo (melhor performance)
  const [
    lighthouseDesktop,
    lighthouseMobile,
    coreWebVitals,
    seoToolsData,
    gscData,
    ahrefsData
  ] = await Promise.allSettled([
    mcp__lighthouse__run_audit(url, 'desktop'),
    mcp__lighthouse__run_audit(url, 'mobile'),
    mcp__lighthouse__get_core_web_vitals(url),
    fetch(`http://localhost:3000/seo-audit?url=${url}`).then(r => r.json()),
    getGSCData(url), // Verifica se property existe
    includeAhrefs ? getAhrefsData(url) : null
  ]);

  // 3. Processar e formatar
  const reportData = {
    url,
    date: new Date().toISOString().split('T')[0],
    scores: extractScores(lighthouseDesktop, lighthouseMobile),
    cwv: processCoreWebVitals(coreWebVitals),
    gsc: processGSCData(gscData),
    onPage: processOnPageData(seoToolsData),
    backlinks: processBacklinks(ahrefsData),
    recommendations: generateRecommendations(/* all data */)
  };

  // 4. Gerar documento Markdown
  const markdown = generateReportMarkdown(reportData);

  // 5. Criar Google Doc
  const docResult = await mcp__google-workspace__create_doc({
    title: `Relatório SEO - ${extractDomain(url)} - ${reportData.date}`,
    body_content: markdown,
    user_google_email: email
  });

  // 6. Retornar link
  return {
    success: true,
    doc_url: docResult.url,
    summary: reportData.recommendations.slice(0, 5)
  };
}
```

---

## 🎨 Propriedades GSC Disponíveis

```javascript
const GSC_PROPERTIES = [
  'sc-domain:descomplicar.pt',
  'https://emanuelalmeida.pt/',
  'https://carstuff.pt/',
  'https://solarfvengenharia.com/',
  'https://aquisevende.pt/',
  'https://alojadamaria.com/',
  'https://e-commerce.descomplicar.pt/'
];

// Verificar se site está em GSC antes de tentar recolher dados
async function getGSCData(url) {
  const domain = extractDomain(url);
  const property = GSC_PROPERTIES.find(p => p.includes(domain));

  if (!property) {
    console.warn(`Site ${domain} não está no GSC. Dados GSC não disponíveis.`);
    return null;
  }

  const analytics = await mcp__gsc__get_search_analytics({
    site_url: property,
    start_date: daysAgo(90),
    end_date: 'today',
    dimensions: ['query'],
    row_limit: 100
  });

  return analytics;
}
```

---

## 📚 Datasets Dify (Consultar SEMPRE)

| Dataset | ID | Uso |
|---------|----|----|
| **SEO (Search Engine Optimization)** | `b93c6475-2f22-412e-ba9d-666eb081b872` | Técnicas SEO, Google updates |
| **Neil Patel** | `6ff761b3-a054-435c-8fc3-a6e6c3a0afaf` | Link building, estratégias |
| **Marketing de Conteúdo** | `061f19a3-d4b6-4383-9f44-620742167201` | E-E-A-T, criação conteúdo |
| **Marketing Digital** | `c1ec779f-4cb1-4ecf-ba11-6b39b93d4e24` | Estratégia geral |

### Como Consultar

```javascript
// Validar recomendações técnicas
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "b93c6475-2f22-412e-ba9d-666eb081b872",
  query: "INP optimization javascript performance 2026"
})

// Estratégias link building
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "6ff761b3-a054-435c-8fc3-a6e6c3a0afaf",
  query: "guest posting outreach backlinks"
})
```

---

## ⚙️ Notas Técnicas

### Requisitos
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh`
- Google Workspace MCP configurado
- GSC authentication (OAuth primeira vez)

### Performance
- Execução paralela de tools (1m40s total)
- Cache Lighthouse results (5 min TTL)
- Rate limiting Ahrefs API (100 req/day free)

### Erros Comuns
- **Site não em GSC:** Relatório gerado sem dados GSC
- **Lighthouse timeout:** Retry automático (3x)
- **Ahrefs rate limit:** Skip backlinks, aviso no relatório

---

## 📈 Instrumentação Automática

```sql
INSERT INTO tblskill_agent_metrics (
  type, name, duration_ms, status, staff_id,
  kb_consulted, kb_cache_hit, tool_calls, project_id
) VALUES (
  'skill', '/seo-report', {DURACAO_MS}, '{STATUS}', 25,
  {KB_CONSULTADO}, {CACHE_HIT}, {TOOL_CALLS}, {PROJECT_ID}
);
```

---

**Versão:** 2.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-03
**Desk Task:** #1483 | **Output:** Google Docs automático