ealmeida
2d05873642
As skills de SEO assentavam em quatro dependências, nenhuma operacional: SEO Tools API (localhost:3000, pasta inexistente em disco), Ahrefs MCP (nunca esteve em config), gsc e lighthouse (em disabledServers). Os seis passos da /seo-audit e o workflow inteiro da /seo-report apontavam para tooling morto — não eram executáveis. - seo-audit v3.0: ordem por custo (grátis → lote pago → unitário pago), gate de mercado (PT = 2620/pt) e gate de maxPages - seo-report v3.0: cobertura de crawl obrigatória no entregável - ferramentas-api.md: inventário das 24 ferramentas OpenSEO + tabela de migração endpoint a endpoint - implementacao-tecnica.md: striking distance, desperdício e filtro de ruído do GSC em código - seo-specialist v3.0: primary_mcps [openseo], bloco de MCPs desligados, FID → INP nos Core Web Vitals maxPages tem default 50: descomplicar.pt auditado com o default deu 25 URLs e 92 issues sem críticos; com maxPages 600 deu 1337 issues e 9 críticos. Documentado como gate — a fase Search Console dimensiona o crawl. Limitações declaradas nas skills: get_audit_issues devolve contagens sem URLs pela bridge MCP (structuredContent.issues não é entregue) e o whoami não expõe saldo de créditos em self-hosted.
130 lines
5.8 KiB
Markdown
130 lines
5.8 KiB
Markdown
---
|
||
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"}
|
||
```
|