---
name: seo-report
description: Relatório SEO completo com dados reais via OpenSEO (Search Console, crawl, Core Web Vitals, backlinks) e exportação para Google Docs. Prioriza por retorno e gera plano de acção. Usar quando "relatório SEO", "seo report", "relatório cliente SEO", "auditoria para cliente".
---

# Skill: /seo-report

Relatório SEO para cliente, com dados reais do **OpenSEO**, exportado para Google Docs.

Diferença face a `/seo-audit`: a auditoria é o **diagnóstico técnico interno**; o report é o **entregável ao cliente** — mesma recolha, apresentação orientada a decisão e a orçamento.

---

## Trigger

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

```bash
/seo-report https://descomplicar.pt
/seo-report https://cliente.pt cliente@email.com
/seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt
```

---

## Fontes de dados

| Fonte | Ferramenta | Dados | Custo |
|---|---|---|---|
| **Search Console** | `get_search_console_performance` | Cliques, impressões, CTR, posição, por query e por página | grátis |
| **Indexação** | `inspect_urls` | Estado de indexação (até 10 URLs) | grátis |
| **Crawl técnico** | `run_site_audit` → `get_audit_issues` | Issues por severidade, Lighthouse em amostra | grátis |
| **Core Web Vitals** | `chrome-devtools → performance_start_trace` | LCP, INP, CLS por página | grátis |
| **Keywords** | `get_keyword_metrics` | Volume, KD, intenção (até 700/chamada) | pago |
| **Autoridade** | `get_backlinks_overview`, `get_domain_overview` | Backlinks, ref. domains, tráfego estimado | pago |
| **Concorrência** | `find_serp_competitors`, `get_serp_results` | Quem ocupa a SERP | pago |

**Tempo:** ~5-10 min (crawl de 600 páginas demora ~4 min). Não é instantâneo — avisar o cliente.

---

## Workflow

```
1. whoami + list_projects        → projectId e mercado (GATE: PT = 2620/pt)
2. GSC por query + por página    → paginar até esgotar
3. Dimensionar o crawl           → maxPages ≥ nº páginas com impressões + 25%
4. run_site_audit                → poll get_audit_status até "completed"
5. get_audit_issues              → critical → warning → info
6. Cruzar fase 2 com fase 5      → páginas com procura E com defeito = lista de trabalho
7. [pago, opcional] keywords, backlinks, SERP
8. Gerar Markdown → Google Doc → partilhar
```

**Os passos 1-6 são grátis e produzem o grosso do relatório.** O passo 7 só se o cliente pagar análise competitiva.

---

## Estrutura do relatório (8 secções)

1. **Sumário executivo** — 5 descobertas + a acção imediata. Más notícias primeiro.
2. **Realidade actual** — cliques, impressões, CTR global, distribuição por posição, branded vs não-branded.
3. **Onde está o retorno** — striking distance (pos 4-20, ≥25 impressões) e desperdício (pos >40 com procura alta).
4. **Estado técnico** — issues por severidade, com **cobertura do crawl declarada**.
5. **Core Web Vitals** — LCP / INP / CLS nas páginas que importam (não em todas).
6. **Autoridade** — backlinks e ref. domains, se contratado.
7. **Plano de acção** — prioridade (crítico/importante/melhoria) × esforço × impacto estimado.
8. **Roadmap trimestral** — fundação técnica → conteúdo → consolidação.

---

## Regras de honestidade do relatório

Um relatório SEO é um documento comercial. Isso torna a precisão **mais** importante, não menos.

- **Declarar sempre a cobertura do crawl.** "1337 issues em 600 páginas crawladas de ~640 com impressões." Sem isto, o número de issues não significa nada.
- **Não apresentar contagens como URLs verificados.** Se a bridge só deu contagens, dizê-lo e anexar o link da UI.
- **Custos são estimativas.** O OpenSEO não expõe saldo — nunca escrever "gastámos X créditos" como facto.
- **Separar medido de inferido.** Marcar as inferências. Um cliente que descobre uma inferência apresentada como facto deixa de confiar no resto.
- **CTR baixo em posição alta não é problema de ranking.** É título/meta. Dizer isso — é a recomendação mais barata e de maior retorno que existe.

---

## Notas técnicas

### Requisitos
- OpenSEO acessível (`whoami` responde)
- Propriedade ligada ao Search Console (senão, relatório sem fase GSC — declarar)
- `google-workspace` MCP para o Google Doc

### Erros comuns
| Erro | Sintoma | Solução |
|---|---|---|
| **`maxPages` por omissão** | Relatório limpo demais, poucos issues | Redimensionar pelo nº de páginas do GSC e relançar |
| Site fora do GSC | Fase 2 vazia | Gerar sem GSC, com aviso destacado |
| Mercado errado | Dados de keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
| Crawl a demorar | `get_audit_status` em `crawling` | Normal — 600 páginas ≈ 4 min. Fazer poll, não cancelar |

---

## References

| Ficheiro | Conteúdo |
|---|---|
| `references/template-relatorio.md` | Template completo com tabelas e secções |
| `references/implementacao-tecnica.md` | Workflow, chamadas OpenSEO, processamento |

Inventário completo das ferramentas e tabela de migração: `../seo-audit/references/ferramentas-api.md`

---

## Anti-patterns

- Gerar relatório sem dados reais.
- Omitir a cobertura do crawl (faz o relatório parecer melhor do que é).
- Listar issues por contagem em vez de por impacto.
- Apresentar estimativas de custo ou de tráfego como medições.
- Recomendações sem esforço e impacto estimados.
- Correr as fases pagas antes das grátis.

---

**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO

## Healing Log

```jsonl
{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Lighthouse MCP, GSC MCP e Ahrefs — nenhum operacional. Workflow inteiro não executável.","fix":"Reescrita sobre OpenSEO; fases grátis antes das pagas; cobertura de crawl obrigatória no relatório.","source":"auto"}
```