ealmeida/claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

marketing: migra superfície SEO para OpenSEO (motor único)

Browse Source 
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.
This commit is contained in:
ealmeida
2026-07-30 22:39:40 +01:00
parent f90ba6ec76
commit 2d05873642
9 changed files with 545 additions and 497 deletions
Download Patch File Download Diff File Expand all files Collapse all files
marketing/agents/seo-specialist.md
+55 -55
View File
@@ -5,22 +5,21 @@ description: >
Use for SEO strategy, keyword research, technical SEO audits, on-page optimization, Core Web Vitals, rankings monitoring, link building, SERP analysis, Use for SEO strategy, keyword research, technical SEO audits, on-page optimization, Core Web Vitals, rankings monitoring, link building, SERP analysis,
or when user mentions "SEO", "keywords", "rankings", "tráfego orgânico", "SERP", "technical SEO", "link building", "Google", "optimização", "indexação". or when user mentions "SEO", "keywords", "rankings", "tráfego orgânico", "SERP", "technical SEO", "link building", "Google", "optimização", "indexação".
author: Descomplicar® Crescimento Digital author: Descomplicar® Crescimento Digital
version: 2.0.0 version: 3.0.0
category: business category: business
model: sonnet model: sonnet
tools: Read, Glob, Grep, ToolSearch tools: Read, Glob, Grep, ToolSearch
# Dependencies # Dependencies
# Nota: MCPs como desk-crm-v3, moloni, easypanel, lighthouse, authentik, spaceship e youtube # OpenSEO é o motor único de SEO. O stack antigo (gsc, lighthouse, Ahrefs,
# estão desligados por omissão — pedir activação via /mcp (regra 57) antes de os usar. # SEO Tools API) está desligado ou não existe — não o invocar.
primary_mcps: primary_mcps:
- gsc - openseo
- google-analytics
- desk-crm-v3
recommended_mcps: recommended_mcps:
- lighthouse - chrome-devtools
- google-workspace
- context7 - context7
allowed-mcps: ssh-unified, google-workspace, gsc, lighthouse, google-analytics, tavily allowed-mcps: openseo, chrome-devtools, google-workspace, context7
skills: skills:
- _core - _core
- seo-audit - seo-audit
@@ -31,18 +30,18 @@ desk_task: 1516
# SEO Specialist Descomplicar # SEO Specialist Descomplicar
Especialista em optimizacao para motores de busca, focado em crescimento de trafego organico atraves de SEO tecnico, optimizacao de conteudo e estrategias de link building. Especialista em optimização para motores de busca, focado em crescimento de tráfego orgânico através de SEO técnico, optimização de conteúdo e estratégias de link building.
## Responsabilidades ## Responsabilidades
- Conduzir pesquisa de keywords e analise competitiva - Conduzir pesquisa de keywords e análise competitiva
- Optimizar elementos on-page (titulos, meta descriptions, headers) - Optimizar elementos on-page (títulos, meta descriptions, headers)
- Melhorar SEO tecnico (velocidade, crawlability, indexacao, Core Web Vitals) - Melhorar SEO técnico (velocidade, crawlability, indexação, Core Web Vitals)
- Desenvolver estrategias de link building e autoridade de dominio - Desenvolver estratégias de link building e autoridade de domínio
- Monitorizar rankings e reportar metricas de trafego organico - Monitorizar rankings e reportar métricas de tráfego orgânico
## Knowledge Sources (Consultar SEMPRE) ## Knowledge Sources (Consultar SEMPRE)
### NotebookLM (Primario - usar PRIMEIRO) ### NotebookLM (Primário — usar PRIMEIRO)
``` ```
mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"keywords rankings optimizacao SERP" mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf5655" query:"keywords rankings optimizacao SERP"
@@ -51,13 +50,13 @@ mcp__notebooklm__notebook_query notebook_id:"76647e0f-3ae2-4c00-a0a8-f457aebf565
## System Prompt ## System Prompt
### Papel ### Papel
Especialista SEO responsavel por aumentar trafego organico atraves de optimizacao tecnica, keyword research e estrategias de link building alinhadas com algoritmos 2026. Especialista SEO responsável por aumentar tráfego orgânico através de optimização técnica, keyword research e estratégias de link building alinhadas com algoritmos 2026.
### Regras Obrigatorias ### Regras Obrigatórias
1. SEMPRE priorizar Core Web Vitals (LCP, FID, CLS) 1. SEMPRE priorizar Core Web Vitals (LCP < 2,5s, INP < 200ms, CLS < 0,1 — o INP substituiu o FID)
2. NUNCA usar black-hat SEO (keyword stuffing, PBNs, cloaking) 2. NUNCA usar black-hat SEO (keyword stuffing, PBNs, cloaking)
3. Keyword research baseado em search intent, nao volume 3. Keyword research baseado em search intent, não volume
4. E-E-A-T obrigatorio (Experience, Expertise, Authority, Trust) 4. E-E-A-T obrigatório (Experience, Expertise, Authority, Trust)
5. Mobile-first indexing (testar sempre em mobile) 5. Mobile-first indexing (testar sempre em mobile)
6. Structured data (Schema.org) para rich snippets 6. Structured data (Schema.org) para rich snippets
@@ -69,73 +68,74 @@ Especialista SEO responsavel por aumentar trafego organico atraves de optimizaca
## Workflows ## Workflows
### Workflow 1: Keyword Research ### Workflow 1: Keyword Research
1. Seed keywords: Brainstorm com cliente, analise concorrentes 1. **Search Console primeiro** (grátis): `get_search_console_performance` — o que já posiciona
2. Expansion: Google Keyword Planner, Ahrefs, SEMrush 2. Striking distance: filtrar pos 4-20 com impressões ≥ 25 (o GSC não filtra por posição)
3. Intent mapping: Informacional, navegacional, transaccional 3. Hidratar: `get_keyword_metrics` — até 700 keywords/chamada, volume + KD + intenção
4. Difficulty: Avaliar competicao (DA de top 10) 4. Expandir (só se necessário): `research_keywords`, 1-5 seeds
5. Priorization: Quick wins (low difficulty, medium volume) 5. Priorizar: quick wins (KD baixo, volume médio, intenção comercial)
6. Mapping: Atribuir keywords a paginas/conteudos 6. Mapear keywords a páginas; guardar com `save_keywords`
### Workflow 2: Technical SEO Audit ### Workflow 2: Technical SEO Audit
1. Crawl: Screaming Frog, Google Search Console 1. GSC por página: conta quantas páginas têm procura real
2. Core Web Vitals: PageSpeed Insights, Lighthouse 2. `run_site_audit` com **maxPages ≥ páginas do GSC + 25%** (o default 50 cega a auditoria)
3. Indexation: Sitemap, robots.txt, canonicals, redirects 3. `get_audit_status` em poll até "completed"; depois `get_audit_issues` por severidade
4. Structure: URL structure, internal linking, breadcrumbs 4. Priorizar issues pelas páginas com impressões — nunca por contagem bruta
5. Mobile: Responsive design, tap targets, viewport 5. Core Web Vitals das páginas que importam: `chrome-devtools → performance_start_trace`
6. Schema: Structured data validation (Google Rich Results Test) 6. Indexação: `inspect_urls` (até 10 URLs)
### Workflow 3: On-Page Optimization ### Workflow 3: On-Page Optimization
1. Title tag: Keyword + brand, <60 chars 1. Title tag: Keyword + brand, <60 chars
2. Meta description: CTR-focused, <160 chars 2. Meta description: CTR-focused, <160 chars
3. Headers: H1 (1x), H2/H3 hierarchy com keywords 3. Headers: H1 (1x), H2/H3 hierarchy com keywords
4. Content: E-E-A-T, >1000 words para pillar content 4. Content: E-E-A-T, >1000 words para pillar content
5. Images: Alt text descritivo, compressao, lazy loading 5. Images: Alt text descritivo, compressão, lazy loading
6. Internal links: Link para conteudo relacionado 6. Internal links: Link para conteúdo relacionado
## MCPs Relevantes ## MCPs Relevantes
- ssh-unified: Optimizacoes tecnicas em servidores WP - **openseo**: motor único — crawl, Search Console, keywords, SERP, backlinks
- google-workspace: GSC data, relatorios em Sheets - **chrome-devtools**: Core Web Vitals e Lighthouse por página
- **google-workspace**: exportar relatórios para Docs/Sheets
## Metricas Chave ## Métricas Chave
- **Organic Traffic**: Visitantes de search engines - **Organic Traffic**: Visitantes de search engines
- **Rankings**: Posicoes keywords alvo (top 3 = sucesso) - **Rankings**: Posições das keywords alvo (top 3 = sucesso)
- **CTR**: Click-through rate em SERPs - **CTR**: Click-through rate em SERPs
- **Core Web Vitals**: LCP <2.5s, FID <100ms, CLS <0.1 - **Core Web Vitals**: LCP < 2,5s, INP < 200ms, CLS < 0,1
- **Backlinks**: Numero e qualidade (DA dos sites) - **Backlinks**: Número e qualidade (DA dos sites)
## Colaboracao ## Colaboração
- Reports to: Digital Marketing Manager - Reports to: Digital Marketing Manager
- Colabora com: Content Manager, Copywriter, Web Designer, WordPress Developer - Colabora com: Content Manager, Copywriter, Web Designer, WordPress Developer
## Your Available MCPs ## Your Available MCPs
### Primary MCPs (Your Domain) ### Primary MCPs (Your Domain)
✓ **ssh-unified** (infra) ✓ **openseo** (motor SEO)
- SSH, SFTP, servidor management - Crawl e issues, Search Console, keywords, SERP, backlinks, rank tracking
- Usage: `mcp__ssh-unified__*` - Ferramentas grátis primeiro; pagas só depois de esgotar as grátis
- Mercado PT obrigatório: `locationCode: 2620`, `languageCode: "pt"`
✓ **google-workspace** (integration) ✓ **chrome-devtools** (performance)
- Email, calendário, docs, drive - `lighthouse_audit`, `performance_start_trace` — CWV reais por página
- Usage: `mcp__google-workspace__*`
### Recommended for seo ### Recommended for seo
- **gsc** - Google Search Console - **google-workspace** — Exportar relatórios (Docs, Sheets)
- **lighthouse** - Performance audits - **context7** — Documentação de bibliotecas e frameworks
- **google-analytics** - Google Analytics 4
- **tavily** - AI-powered search API - web search optimizado para LLMs
### All Available (32 total) ### Desligados — NÃO invocar
desk-crm-v3, moloni, context7, gitea, n8n, cwp, filesystem, imap, outline-api, youtube-research, youtube-uploader, mcp-time, mem0, puppeteer, mcp-mermaid, mcp-echarts, powerpoint, penpot, pixabay, pexels, elevenlabs, magic, vimeo, design-systems, replicate `gsc`, `lighthouse`, `google-analytics` estão em disabledServers. `Ahrefs` e a
`SEO Tools API` (localhost:3000) não existem. Se precisares de um deles, pedir
activação via `/mcp` — nunca contornar com bash/curl.
**Discovery:** Use ToolSearch to find specific tools. **Discovery:** Use ToolSearch to find specific tools.
**Example:** `ToolSearch("ssh upload")` finds SSH upload tools. **Example:** `ToolSearch("ssh upload")` finds SSH upload tools.
## Your Available Skills ## Your Available Skills
### Primary Skills (Your Domain) ### Primary Skills (Your Domain)
✓ **/seo-audit** - Auditoria SEO completa usando todas as ferramentas instaladas - Lighthouse, SEO ✓ **/seo-audit** - Auditoria SEO completa com dados reais via OpenSEO (crawl, GSC, SERP, backlinks)
- Invoke: `/seo-audit` - Invoke: `/seo-audit`
✓ **/seo-report** - Relatório SEO completo com dados de múltiplas fontes (Lighthouse, GSC, SEO Tools ✓ **/seo-report** - Relatório SEO para cliente com OpenSEO, exportado para Google Docs
- Invoke: `/seo-report` - Invoke: `/seo-report`
### Recommended for seo ### Recommended for seo
marketing/skills/seo-audit/SKILL.md
+141 -135
View File
@@ -1,202 +1,208 @@
--- ---
name: seo-audit name: seo-audit
description: Auditoria SEO completa com recomendacoes de optimizacao. Analisa SEO tecnico, conteudo, backlinks e desempenho. description: Auditoria SEO completa com dados reais via OpenSEO (crawl, Search Console, SERP, backlinks, keywords). Analisa SEO técnico, conteúdo, autoridade e desempenho, e prioriza por retorno. Usar quando "auditoria SEO", "audit", "analisar site", "Core Web Vitals", "Search Console", "striking distance", "porque não tenho tráfego".
--- ---
# SEO Audit - Auditoria Completa # SEO Audit — Auditoria Completa (OpenSEO)
Skill para realizar auditorias SEO completas usando o stack de ferramentas instalado. Best practices 2026. Auditoria SEO com dados reais. **Motor único: OpenSEO** (`seo.descomplicar.pt`), que substituiu o stack antigo (SEO Tools API + Ahrefs + GSC MCP + Lighthouse MCP) — ver `references/ferramentas-api.md` para a tabela de migração.
--- ---
## Contexto NotebookLM ## Regra zero — a ordem é económica, não estética
ANTES de executar, consultar notebook para contexto especializado: O OpenSEO tem ferramentas **grátis** e ferramentas **que gastam créditos**. Executar pela ordem errada gasta dinheiro a produzir conclusões que as ferramentas grátis já davam.
| Notebook | ID | Consultar quando | | Fase | Ferramentas | Custo | Porquê nesta ordem |
|----------|-----|-----------------| |---|---|---|---|
| Marketing Digital PT | `4c595973` | Sempre | | 1 | `get_search_console_performance`, `inspect_urls` | **grátis** | Dados de primeira mão. Diz o que já posiciona e quais páginas importam |
| 2 | `run_site_audit`, `get_audit_issues`, `get_audit_pages` | **grátis** | Estado técnico. O dimensionamento do crawl depende da fase 1 |
| 3 | `get_keyword_metrics` | pago (lote) | Hidrata até 700 keywords conhecidas de uma vez — a melhor relação valor/crédito |
| 4 | `get_ranked_keywords`, `get_domain_overview`, `get_backlinks_overview` | pago | Contexto competitivo |
| 5 | `get_serp_results`, `find_serp_competitors` | pago (~30-60/keyword) | Só nas keywords que sobreviveram à filtragem |
``` **Nunca começar pela fase 3 ou acima.** As fases 1-2 resolvem a maioria das auditorias sem gastar um crédito.
mcp__notebooklm__notebook_query({
notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3",
query: "<adaptar ao contexto — ex: auditoria SEO tecnico, Core Web Vitals, backlinks, E-E-A-T>"
})
```
**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando a auditoria envolve email deliverability.
--- ---
## Quando Usar ## Pré-voo obrigatório (3 verificações, 30 segundos)
- Auditar um site completo (tecnico + conteudo + performance) ```
- Verificar Core Web Vitals e ranking factors 1. openseo → whoami → confirma ligação, org, modo
- Analisar backlinks e autoridade de dominio 2. openseo → list_projects → obtém projectId E o mercado do projecto
- Obter dados reais do Google Search Console 3. confirmar mercado → PT = locationCode 2620, languageCode "pt"
- Identificar oportunidades de optimizacao ```
- Comparar com concorrencia
**GATE — mercado.** Se o projecto estiver em `2840/en` (EUA/inglês, que é o default) e o cliente for português, **todas** as chamadas pagas devolvem dados do mercado errado. Ou se corrige o mercado do projecto, ou se passa `locationCode`/`languageCode` explicitamente em **cada** chamada. Um esquecimento = créditos gastos em lixo.
> `locationCode: 2620` = Portugal — confirmado empiricamente (SERP devolve domínios `.pt`). Não inventar códigos: se houver dúvida, correr uma query de teste e validar pelos resultados.
--- ---
## Google Updates 2026 ## Fase 1 — Search Console primeiro (grátis, é o mapa)
### Core Algorithm Updates ```
openseo → get_search_console_performance
dimensions: ["query"] dateRange: "last_3_months" rowLimit: 1000
openseo → get_search_console_performance
dimensions: ["page"] dateRange: "last_3_months" rowLimit: 1000
```
| Update | Data | Impacto | Paginar com `startRow` enquanto o cabeçalho disser `more available`.
|--------|------|---------|
| **Helpful Content Q1** | Jan 2026 | Penaliza conteudo AI de baixa qualidade |
| **Core Web Vitals 3.0** | Mar 2026 | INP substitui FID, thresholds mais rigorosos |
| **E-E-A-T Focus** | Q1-Q2 | Experiencia pratica obrigatoria |
| **Mobile-First Index** | Universal | 100% dos sites |
### Novos Ranking Factors 2026 ### As três armadilhas do GSC
1. **INP (Interaction to Next Paint)** -- Bom: < 200ms | Medio: 200-500ms | Mau: > 500ms **1. Vista por query ≠ vista por página.** O GSC anonimiza queries raras, por isso os totais por query são sempre **muito menores** que os totais por página. A vista por **página** é a real; usar essa para números globais.
2. **E-E-A-T** -- Autor identificado com bio, credenciais verificaveis, experiencia real
3. **Page Experience Signals** -- HTTPS obrigatorio, intrusive interstitials penalizados **2. O GSC não filtra por posição.** `striking distance` tem de ser filtrado do lado do cliente, depois de puxar as linhas.
**3. Há lixo nas queries.** Colagens de relatórios do Google Ads, operadores `site:`, strings com mojibake. Filtrar antes de contar, ou as métricas mentem.
```python
def is_noise(k):
return ('ativado' in k and 'correspond' in k) or k.startswith('-site:') \
or k.startswith('=') or len(k) > 90 or '0,00' in k
```
### O que extrair
| Métrica | Cálculo | Leitura |
|---|---|---|
| CTR global | cliques ÷ impressões (vista por página) | < 1% = problema de captação, não de ranking |
| Distribuição por posição | buckets 1-3 / 4-10 / 11-20 / 21-50 / 51+ | Impressões concentradas em 21+ = visibilidade inútil |
| Branded vs não-branded | queries com o nome da marca vs resto | Se só a marca converte, o SEO não está a trabalhar |
| **Striking distance** | pos 4-20 **e** impressões ≥ 25 | **É aqui que está o retorno** |
| Desperdício | pos > 40 **e** impressões ≥ 300 | Páginas com procura real enterradas |
### O sinal mais accionável de todos
**Posição 4-10 com CTR perto de 0%.** Não é problema de ranking — o site está na primeira página. É o **título e a meta description** a não convencerem. Cruzar esta lista com os issues `missing-meta-description` e `title-too-long` da fase 2: a intersecção é a lista de trabalho, por ordem.
--- ---
## Workflow de Auditoria Completa ## Fase 2 — Auditoria técnica (grátis)
### Passo 1: Analise Tecnica Basica (3 min)
``` ```
1. SEO Tools API -> /seo-audit -> Meta tags, headings, estrutura HTML openseo → run_site_audit
2. SEO Tools API -> /page-speed-analyzer -> Velocidade, sugestoes url: "<url>" maxPages: <N> runLighthouse: true
3. Lighthouse -> run_audit -> Performance, SEO, Accessibility scores openseo → get_audit_status (poll até "completed")
openseo → get_audit_issues (severity: critical → warning → info)
``` ```
**Checklist Critico:** ### GATE — `maxPages` (o erro que cega a auditoria)
- [ ] Meta title (50-60 chars)
- [ ] Meta description (150-160 chars)
- [ ] H1 unico com keyword
- [ ] Canonical URL definido
- [ ] Robots.txt acessivel
- [ ] Sitemap.xml presente
- [ ] HTTPS activo
- [ ] Mobile-friendly
### Passo 2: Core Web Vitals (2 min) **`maxPages` tem default 50.** Um site de 600 páginas auditado com o default devolve um relatório limpo e falso: descreve 8% do site e omite exactamente o hub de conteúdo que gera o tráfego.
**Regra:** `maxPages` ≥ número de páginas com impressões no GSC (fase 1), com folga de ~25%. Por isso é que a fase 1 vem primeiro — é ela que dimensiona o crawl.
> Caso real (descomplicar.pt, 07-2026): auditoria com default 50 → 25 URLs únicos, 92 issues, **zero críticos**, nenhuma das 119 páginas `/guia-*`. Relançada com `maxPages: 600` → **1337 issues, 9 críticos**. O relatório "limpo" descrevia 4% do site.
### Prioridade dos issues
| Severidade | Tipos | Acção |
|---|---|---|
| **critical** | `broken-internal-link`, `blocked-page`, `server-error`, `broken-page` | Corrigir já — sangram autoridade e crawl budget |
| **warning** | `missing-h1`, `missing-meta-description`, `duplicate-content`, `multiple-h1`, `duplicate-title` | Priorizar pelas páginas com impressões (fase 1) |
| **info** | `title-too-long`, `noindex-page`, `slow-response`, `heading-order-skip` | Lote; só vale a pena onde há procura |
**Nunca tratar a lista de issues por ordem de contagem.** 300 metas em falta em páginas sem impressões valem menos que 6 em páginas na posição 8. A fase 1 é que ordena a fase 2.
### Limitação conhecida — issues sem URL
`get_audit_issues` e `get_audit_pages` devolvem **apenas contagens agregadas** através da bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega; `get_audit_pages` trunca a listagem em ~25 linhas independentemente do `limit`.
**Contorno:** o campo `details.mcpMeta.url` da resposta traz o link do relatório na UI. Entregar esse link ao humano para os URLs concretos:
```
https://seo.descomplicar.pt/p/<projectId>/audit?auditId=<auditId>
```
Declarar esta limitação no relatório — não fingir que se verificaram URLs que não se viram.
### Core Web Vitals por página
`run_site_audit` com `runLighthouse: true` corre Lighthouse numa amostra (até 20 páginas). Para uma página específica, usar `chrome-devtools`:
``` ```
1. Lighthouse -> get_core_web_vitals -> LCP, INP, CLS (mobile + desktop) chrome-devtools → lighthouse_audit (SEO, acessibilidade, best practices)
2. Lighthouse -> compare_mobile_desktop -> Identificar gaps chrome-devtools → performance_start_trace (LCP, INP, CLS reais)
3. Lighthouse -> get_lcp_opportunities -> Sugestoes optimizacao
``` ```
**Thresholds 2026:** **Thresholds 2026:** LCP < 2,5s · **INP** < 200ms · CLS < 0,1
(INP substituiu o FID — se algum documento ainda disser FID, está desactualizado.)
| Metrica | Bom | Necessita Melhoria | Mau | ---
|---------|-----|-------------------|-----|
| **LCP** | < 2.5s | 2.5-4s | > 4s |
| **INP** | < 200ms | 200-500ms | > 500ms |
| **CLS** | < 0.1 | 0.1-0.25 | > 0.25 |
### Passo 3: Analise de Conteudo (3 min) ## Fase 3 — Hidratar keywords (pago, lote)
``` ```
1. SEO Tools API -> /content-optimization -> On-page SEO, keyword density openseo → get_keyword_metrics
2. SEO Tools API -> /internal-linking -> Estrutura links internos keywords: [<as keywords em striking distance da fase 1>]
3. SEO Ahrefs -> keyword_generator -> Keywords relacionadas, volume, KD locationCode: 2620 languageCode: "pt"
``` ```
**Checklist E-E-A-T:** Até **700 keywords numa só chamada** — volume, dificuldade (KD), intenção, CPC, tendência. É a forma barata de priorizar. Só depois disto se decide onde vale a pena competir.
- [ ] Autor identificado com bio
- [ ] Credenciais verificaveis
- [ ] Data publicacao/actualizacao
- [ ] Fontes citadas (links externos autoritativos)
- [ ] Experiencia real demonstrada
### Passo 4: Backlinks e Autoridade (2 min) Guardar o que sobreviver: `openseo → save_keywords` (grátis, idempotente).
---
## Fase 4 — Contexto competitivo (pago)
``` ```
1. SEO Tools API -> /backlink-checker -> Backlinks basicos, DR/UR openseo → get_domain_overview (tráfego orgânico estimado, nº keywords, backlinks)
2. SEO Ahrefs -> get_backlinks_list -> Lista detalhada (DR, anchor text) openseo → get_ranked_keywords (onde o domínio posiciona, por mercado)
3. SEO Ahrefs -> get_traffic -> Trafego estimado mensal openseo → get_backlinks_overview (~50 créditos por domínio)
``` openseo → get_backlinks_profile (linhas detalhadas: anchors, dofollow, spam)
**Metricas Autoridade:**
- **DR (Domain Rating)**: 0-100 (forca backlink profile)
- **UR (URL Rating)**: 0-100 (forca pagina especifica)
- **Backlinks**: Quantidade + qualidade (DR > 30)
- **Referring Domains**: Numero de dominios unicos
### Passo 5: Dados Reais GSC (3 min)
```
1. GSC -> get_search_analytics -> Queries, impressoes, CTR real (ultimos 90 dias)
2. GSC -> check_indexing_issues -> Problemas de indexacao
3. GSC -> get_sitemaps -> Status sitemaps submetidos
```
**Metricas GSC a Analisar:**
- **Impressoes vs Cliques**: CTR medio > 2%
- **Posicao media**: Top 3 para keywords principais
- **Cobertura**: % paginas indexadas vs submetidas
- **Mobile Usability**: Erros especificos mobile
### Passo 6: Concorrencia (opcional, 2 min)
```
SEO Tools API -> /competitor-analysis -> Comparar com 2-3 concorrentes
- Keywords gap
- Backlinks gap
- Content gap
``` ```
--- ---
## Propriedades GSC Disponiveis ## Fase 5 — SERP (pago, por último)
``` ```
sc-domain:descomplicar.pt openseo → get_serp_results (1-10 keywords por chamada, ~30-60 créditos cada)
https://emanuelalmeida.pt/ openseo → find_serp_competitors (quem compete num conjunto de keywords)
https://carstuff.pt/
https://solarfvengenharia.com/
https://aquisevende.pt/
https://alojadamaria.com/
https://e-commerce.descomplicar.pt/
``` ```
--- Ler a SERP como **estrutura**, não como lista: se o top-10 estiver cheio de directórios e artigos "melhores X", a intenção é comparativa e uma homepage não entra — é preciso uma página de comparação. Se estiver cheio de homepages de concorrentes, é disputa de marca.
## Notas Importantes Local/Maps: `get_local_serp_results`, `search_local_businesses`, `get_google_business_questions`.
### Requisitos
- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh`
- **GSC** requer autenticacao OAuth na primeira utilizacao
- **GA** requer ADC credentials configuradas
### Limitacoes
- Ahrefs API tem rate limiting (100 req/day free tier)
- GSC data maximo: 16 meses historico
- Lighthouse scores variam +/- 5 pontos entre execucoes
--- ---
## References (conteudo detalhado) ## Custos — o que sabemos e o que não sabemos
| Ficheiro | Conteudo | `whoami` **não expõe saldo de créditos** em modo self-hosted (verificado antes e depois de uma chamada paga: output idêntico). Os `~30-60 créditos/keyword` são a **estimativa do schema**, não uma medição.
|----------|----------|
| `references/template-relatorio-auditoria.md` | Template completo do relatorio com todas as seccoes e tabelas | **Consequência prática:** não há medidor no OpenSEO. O contador real vive na conta DataForSEO. Para lotes grandes, confirmar saldo aí primeiro. Nunca reportar custo consumido como facto — reportar como estimativa.
| `references/ferramentas-api.md` | Endpoints SEO Tools API, Lighthouse MCP, Ahrefs, GSC, GA |
--- ---
## Anti-Patterns ## Anti-patterns
- Auditar sem dados reais (nunca simular metricas) - **Correr `run_site_audit` com o `maxPages` por omissão.** Produz relatórios limpos e falsos.
- Ignorar gap mobile vs desktop - **Começar por ferramentas pagas.** O GSC é grátis e responde a metade das perguntas.
- Nao verificar se site esta no GSC antes de recolher dados - Usar totais por query como totais do site (o GSC anonimiza — usar a vista por página).
- Recomendacoes sem priorizacao (critico/importante/melhoria) - Priorizar issues por contagem em vez de por impressões da página afectada.
- Esquecer E-E-A-T na analise de conteudo - Correr chamadas pagas sem confirmar o mercado do projecto.
- Apresentar contagens de issues como se fossem URLs verificados.
- Auditar sem dados reais ou simular métricas.
- Recomendações sem prioridade (crítico/importante/melhoria) e sem esforço estimado.
--- ---
**Versao:** 2.1.0 | **Autor:** Descomplicar ## References
| Ficheiro | Conteúdo |
|---|---|
| `references/ferramentas-api.md` | Inventário OpenSEO completo + tabela de migração do stack antigo |
| `references/template-relatorio-auditoria.md` | Template do relatório com todas as secções e tabelas |
---
**Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO
## Healing Log ## Healing Log
<!-- Registo automático de erros e correcções nesta skill --> <!-- Registo automático de erros e correcções nesta skill -->
```jsonl
{"date":"2026-07-30","issue":"Skill dependia de SEO Tools API (localhost:3000), Ahrefs MCP, GSC MCP e Lighthouse MCP — todos inexistentes ou desligados. Nenhum dos 6 passos era executável.","fix":"Reescrita completa sobre OpenSEO, com ordem por custo, gates de mercado e maxPages.","source":"auto"}
```
marketing/skills/seo-audit/references/ferramentas-api.md
+94 -64
View File
@@ -1,75 +1,113 @@
# Ferramentas e APIs - SEO Audit # Ferramentas SEO — OpenSEO
## 1. SEO Tools API (http://localhost:3000) Motor único do SEO Descomplicar®. Substituiu integralmente o stack anterior.
UI: `https://seo.descomplicar.pt` · Projecto default: `1e5ad4d6-a285-4fd3-9633-339abef4b6af`
```bash ---
# Auditoria basica
curl "http://localhost:3000/seo-audit?url=URL"
# Velocidade PageSpeed Insights style ## 1. Migração — o que morreu e o que o substitui
curl "http://localhost:3000/page-speed-analyzer?url=URL"
# Backlinks + DR/UR O stack antigo desta skill (v2.1.0) apontava para quatro dependências. **Nenhuma está operacional** (verificado 30-07-2026):
curl "http://localhost:3000/backlink-checker?url=URL"
# Rankings para keywords | Dependência antiga | Estado real | Substituto OpenSEO |
curl "http://localhost:3000/rank-checker?url=URL&keywords=keyword1,keyword2" |---|---|---|
| **SEO Tools API** `localhost:3000` | `~/mcp-servers/seo-tools-api/` **não existe em disco** | ver tabela abaixo |
| **Ahrefs MCP** | nunca esteve em nenhuma config MCP | `get_backlinks_*`, `get_domain_overview`, `get_keyword_metrics` |
| **GSC MCP** | em `disabledServers` | `get_search_console_performance`, `inspect_urls` |
| **Lighthouse MCP** | em `disabledServers` | `run_site_audit` (`runLighthouse`) ou `chrome-devtools` |
# Optimizacao conteudo on-page ### Endpoint a endpoint
curl "http://localhost:3000/content-optimization?url=URL"
# Internal linking structure | Antigo | Novo | Nota |
curl "http://localhost:3000/internal-linking?url=URL" |---|---|---|
| `/seo-audit` | `run_site_audit` + `get_audit_issues` | Atenção ao `maxPages` |
| `/page-speed-analyzer` | `run_site_audit` com `runLighthouse: true` | Amostra até 20 páginas |
| `/content-optimization` | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | |
| `/internal-linking` | `get_audit_issues` (`orphan-page`, `broken-internal-link`, `no-outgoing-links`) | |
| `/backlink-checker` | `get_backlinks_overview` | |
| `/rank-checker` | `get_rank_tracker` (grátis) ou `get_ranked_keywords` (pago) | |
| `/competitor-analysis` | `find_serp_competitors` + `get_domain_overview` | |
| `/sitemap-generator` | **sem equivalente** | Usar plugin WP ou gerar à mão |
| Ahrefs `keyword_generator` | `research_keywords` (novas) / `get_keyword_metrics` (conhecidas) | |
| Ahrefs `get_backlinks_list` | `get_backlinks_profile` | |
| Ahrefs `get_traffic` | `get_domain_overview` | Estimado |
| Lighthouse `run_audit` | `chrome-devtools → lighthouse_audit` | Por página |
| Lighthouse `get_core_web_vitals` | `chrome-devtools → performance_start_trace` | LCP/INP/CLS reais |
| GSC `get_search_analytics` | `get_search_console_performance` | |
| GSC `check_indexing_issues` | `inspect_urls` | Até 10 URLs por chamada |
| GSC `get_sitemaps` | **sem equivalente** | Ver na UI do Search Console |
# Sitemap XML generator ---
curl "http://localhost:3000/sitemap-generator?url=URL"
# Analise concorrencia ## 2. Inventário OpenSEO (24 ferramentas)
curl "http://localhost:3000/competitor-analysis?url=URL&competitors=site1.com,site2.com"
```
## 2. Lighthouse MCP ### Grátis — não tocam no DataForSEO
| Tool | Funcao | Output | | Ferramenta | Função |
|------|--------|--------| |---|---|
| `run_audit(url)` | Auditoria completa | Performance, SEO, A11y, Best Practices | | `whoami` | Utilizador, org, modo, scopes. **Não mostra saldo em self-hosted** |
| `get_performance_score(url)` | Score performance | 0-100 | | `list_projects` | Projectos + `projectId` + mercado default |
| `get_core_web_vitals(url)` | LCP, INP, CLS | Mobile + Desktop | | `create_project` | Novo projecto (nome, domínio, mercado) |
| `get_accessibility_score(url)` | Acessibilidade | 0-100 + issues | | `run_site_audit` | Crawl same-origin, robots-aware. `maxPages` **default 50** |
| `get_seo_analysis(url)` | Analise SEO tecnico | Meta, headings, indexabilidade | | `get_audit_status` | Progresso (fase, páginas, Lighthouse) |
| `get_security_audit(url)` | Seguranca | HTTPS, mixed content, headers | | `get_audit_issues` | Relatório priorizado. Filtros `severity`/`issueType` |
| `compare_mobile_desktop(url)` | Comparacao | Diferencas performance | | `get_audit_pages` | Páginas crawladas com dados SEO por página |
| `get_lcp_opportunities(url)` | Optimizacoes LCP | Preload, lazy load | | `get_search_console_performance` | Search Analytics: cliques, impressões, CTR, posição |
| `find_unused_javascript(url)` | JS nao usado | Tamanhos, % savings | | `inspect_urls` | URL Inspection do GSC (até 10 URLs): indexação, canónico |
| `get_rank_tracker` | Configs de rank tracking + último snapshot |
| `save_keywords` | Guardar keywords no projecto (idempotente) |
| `list_saved_keywords` | Keywords guardadas + métricas em cache |
## 3. SEO Ahrefs MCP (via API) ### Pagas — consomem créditos
| Tool | Funcao | Dados | | Ferramenta | Custo aprox. | Função |
|------|--------|-------| |---|---|---|
| `get_backlinks_list(domain)` | Lista backlinks | DR, UR, anchor text | | `get_keyword_metrics` | lote | **Até 700 keywords/chamada**: volume, KD, intenção, CPC, tendência |
| `keyword_generator(keyword, country)` | Ideias keywords | Volume, KD, CPC | | `research_keywords` | ~30-100/seed | 1-5 seeds → ideias novas + métricas |
| `get_traffic(domain)` | Trafego estimado | Visitas mensais, keywords | | `get_serp_results` | ~30-60/keyword | Google orgânico ao vivo, 1-10 keywords |
| `keyword_difficulty(keyword)` | Dificuldade keyword | 0-100 (KD score) | | `find_serp_competitors` | pago | Domínios que competem num conjunto de keywords |
| `get_ranked_keywords` | pago | Keywords onde um domínio posiciona, por mercado |
| `get_domain_overview` | pago | Tráfego orgânico, nº keywords, backlinks, ref. domains |
| `get_domain_keyword_suggestions` | pago | Lista detalhada de keywords de um domínio |
| `get_backlinks_overview` | ~50/domínio, ~25/página | Resumo do perfil de backlinks |
| `get_backlinks_profile` | pago | Linhas detalhadas: anchors, dofollow, spam, lost/broken |
| `get_local_serp_results` | pago | Google Maps / Local Finder junto a coordenadas |
| `search_local_businesses` | pago | Negócios locais perto de coordenadas |
| `get_google_business_questions` | pago | Q&A de Google Business Profile |
## 4. Google Search Console MCP ---
| Tool | Funcao | Dados Reais | ## 3. Mercados
|------|--------|-------------|
| `list_properties` | Listar sites verificados | URLs properties |
| `get_search_analytics(site, period)` | Queries, cliques, CTR | Ultimos 16 meses |
| `inspect_url_enhanced(site, url)` | Inspeccionar URL | Indexacao, mobile usability |
| `check_indexing_issues(site, urls)` | Problemas indexacao | Erros, avisos |
| `get_sitemaps(site)` | Listar sitemaps | Status, URLs submetidos |
## 5. Google Analytics MCP | Mercado | `locationCode` | `languageCode` |
|---|---|---|
| **Portugal** | `2620` | `pt` |
| EUA (default do projecto) | `2840` | `en` |
| Tool | Funcao | Metricas | `2620` = Portugal, confirmado empiricamente (SERP devolve domínios `.pt`). **Não inventar códigos** — validar sempre por uma query de teste. Referência oficial: `dataforseo.com/help-center/locations`.
|------|--------|----------|
| `get_account_summaries` | Listar contas | Properties disponiveis |
| `run_report(property, metrics, dimensions)` | Relatorio custom | Sessions, users, bounce rate |
| `run_realtime_report(property)` | Tempo real | Utilizadores activos now |
## Propriedades GSC Disponiveis **Aviso:** alguns países são servidos por dados do Google Ads — volume/CPC funcionam, mas KD, intenção e analytics de domínio não estão disponíveis.
---
## 4. Limitações conhecidas (verificadas, não presumidas)
1. **Issues sem URL.** `get_audit_issues` e `get_audit_pages` devolvem só contagens agregadas via bridge MCP. As linhas por URL vivem em `structuredContent.issues`, que a bridge não entrega. `get_audit_pages` trunca em ~25 linhas mesmo com `limit: 1000`.
→ Contorno: `details.mcpMeta.url` traz o link do relatório na UI.
2. **Sem medidor de créditos.** `whoami` em self-hosted devolve o mesmo output antes e depois de chamadas pagas. Os custos documentados são estimativas do schema. O contador real está na conta DataForSEO.
3. **`maxPages` default 50.** A causa mais comum de auditorias falsamente limpas.
4. **GSC anonimiza queries.** Totais por query são sempre inferiores aos totais por página. Usar a vista por página para números globais.
5. **GSC não filtra por posição.** Striking distance filtra-se do lado do cliente.
6. **Lag do GSC:** os últimos ~3 dias podem estar incompletos. Datas em Pacific Time. Máximo 16 meses de histórico.
---
## 5. Propriedades Search Console disponíveis
``` ```
sc-domain:descomplicar.pt sc-domain:descomplicar.pt
@@ -81,14 +119,6 @@ https://alojadamaria.com/
https://e-commerce.descomplicar.pt/ https://e-commerce.descomplicar.pt/
``` ```
## Requisitos ---
- **SEO Tools API** deve estar a correr: `~/mcp-servers/seo-tools-api/start.sh` **Actualizado:** 30-07-2026 | Substitui a versão baseada em SEO Tools API + Ahrefs + GSC/Lighthouse MCP
- **GSC** requer autenticacao OAuth na primeira utilizacao
- **GA** requer ADC credentials configuradas (`gcloud auth application-default login`)
## Limitacoes
- Ahrefs API tem rate limiting (100 req/day free tier)
- GSC data maximo: 16 meses historico
- Lighthouse scores variam +/- 5 pontos entre execucoes (network dependent)
marketing/skills/seo-audit/references/template-relatorio-auditoria.md
+8 -5
View File
@@ -183,11 +183,14 @@ H1: [Texto] OK
--- ---
## Ferramentas Utilizadas ## Ferramentas Utilizadas
- SEO Tools API (localhost:3000) - OpenSEO — crawl e issues (`run_site_audit`, `get_audit_issues`)
- Lighthouse MCP - OpenSEO — Search Console (`get_search_console_performance`)
- SEO Ahrefs MCP - OpenSEO — keywords e SERP (`get_keyword_metrics`, `get_serp_results`)
- Google Search Console MCP - OpenSEO — autoridade (`get_backlinks_overview`, `get_domain_overview`)
- Google Analytics MCP (opcional) - chrome-devtools — Core Web Vitals por página (opcional)
**Cobertura do crawl**: [N páginas crawladas] de [M páginas com impressões no GSC]
**Chamadas pagas**: [listar] — custo estimado, não medido (OpenSEO não expõe saldo)
--- ---
marketing/skills/seo-content-optimization/SKILL.md
+17 -11
View File
@@ -161,20 +161,26 @@ mcp__notebooklm__notebook_query({
## Ferramentas Recomendadas ## Ferramentas Recomendadas
### Validacao ### No stack (usar primeiro — são estes que temos)
- **Google Search Console** - Monitorizacao, indexacao | Necessidade | Ferramenta OpenSEO | Custo |
- **PageSpeed Insights** - Core Web Vitals |---|---|---|
- **Schema Validator** - Testar structured data (schema.org/validator) | Monitorização, indexação | `get_search_console_performance`, `inspect_urls` | grátis |
- **Mobile-Friendly Test** - Google mobile test | Auditoria técnica completa | `run_site_audit` → `get_audit_issues` | grátis |
- **Rich Results Test** - Google rich results | Conteúdo fino, títulos, metas | `get_audit_issues` (`thin-content`, `title-*`, `meta-description-*`) | grátis |
| Keyword research | `get_keyword_metrics` (conhecidas) / `research_keywords` (novas) | pago |
| Backlinks | `get_backlinks_overview`, `get_backlinks_profile` | pago |
| Core Web Vitals | `chrome-devtools → performance_start_trace` | grátis |
### Analise Inventário e tabela de migração: `../seo-audit/references/ferramentas-api.md`
- **Screaming Frog** - Auditoria tecnica completa ### Externas (validação manual)
- **Ahrefs/Semrush** - Keyword research, backlinks
- **AnswerThePublic** - Long-tail questions - **Schema Validator** — testar structured data (schema.org/validator)
- **Google Trends** - Sazonalidade keywords - **Rich Results Test** — Google rich results
- **Mobile-Friendly Test** — Google mobile test
- **AnswerThePublic** — long-tail questions
- **Google Trends** — sazonalidade de keywords
### Optimizacao ### Optimizacao
marketing/skills/seo-content-optimization/references/structured-data.md
+10 -7
View File
@@ -249,13 +249,16 @@ https://site.pt/este-url-e-muito-longo-com-muitas-palavras-desnecessarias/
### Ferramentas ### Ferramentas
| Ferramenta | Uso | Métricas | | Ferramenta | Uso | Métricas | Custo |
|------------|-----|----------| |------------|-----|----------|-------|
| Google Keyword Planner | Volume, CPC | Volume mensal, competição | | **OpenSEO** `get_keyword_metrics` | Hidratar até 700 keywords conhecidas | Volume, KD, intenção, CPC, tendência | pago (lote) |
| Ahrefs | KD, SERP analysis | Keyword Difficulty, DR necessário | | **OpenSEO** `research_keywords` | Descobrir keywords novas (1-5 seeds) | Volume, KD, ideias relacionadas | pago (~30-100/seed — estimativa do schema, não medida) |
| Semrush | Concorrência | Gap analysis, trending | | **OpenSEO** `get_search_console_performance` | O que já posiciona (dados próprios) | Cliques, impressões, CTR, posição | **grátis** |
| AnswerThePublic | Long-tail questions | Questões reais utilizadores | | **OpenSEO** `get_ranked_keywords` | Keywords de um domínio (nosso ou concorrente) | Posição, volume, tráfego | pago |
| Google Trends | Sazonalidade | Tendência temporal | | AnswerThePublic | Long-tail questions | Questões reais de utilizadores | grátis |
| Google Trends | Sazonalidade | Tendência temporal | grátis |
**Ordem obrigatória:** Search Console primeiro (grátis e são dados de primeira mão), só depois as pagas. Mercado PT: `locationCode: 2620`, `languageCode: "pt"`.
### Keyword Difficulty Benchmarks ### Keyword Difficulty Benchmarks
marketing/skills/seo-report/SKILL.md
+76 -105
View File
@@ -1,30 +1,13 @@
--- ---
name: seo-report name: seo-report
description: Relatorio de auditoria SEO completo com Lighthouse, Google Search Console e exportacao para Google Docs. Analisa Core Web Vitals, desempenho, SEO on-page e gera recomendacoes accionaveis. 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 # Skill: /seo-report
Gera relatorio SEO completo com dados de multiplas fontes e exporta automaticamente para Google Docs. 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.
## Contexto NotebookLM
ANTES de executar, consultar notebook para contexto especializado:
| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| Marketing Digital PT | `4c595973` | Sempre |
```
mcp__notebooklm__notebook_query({
notebook_id: "4c595973-ba10-420a-a3bf-e4389e424ad3",
query: "<adaptar ao contexto — ex: auditoria SEO, relatorio performance, recomendacoes tecnicas>"
})
```
**Procedimento relacionado:** `PROC-DMARC-Email-Entregabilidade.md` -- consultar quando o relatorio envolve email deliverability.
--- ---
@@ -32,127 +15,115 @@ mcp__notebooklm__notebook_query({
`/seo-report <url>` ou `/seo-report <url> <email_destino>` `/seo-report <url>` ou `/seo-report <url> <email_destino>`
---
## Exemplos
```bash ```bash
# Relatorio basico (envia para emanuelalmeidaa@gmail.com)
/seo-report https://descomplicar.pt /seo-report https://descomplicar.pt
# Relatorio para cliente especifico
/seo-report https://cliente.pt cliente@email.com /seo-report https://cliente.pt cliente@email.com
# Relatorio com analise concorrencia
/seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt /seo-report https://site.pt --competitors=concorrente1.pt,concorrente2.pt
``` ```
--- ---
## Fontes de Dados ## Fontes de dados
| Fonte | Dados Recolhidos | Tempo | | Fonte | Ferramenta | Dados | Custo |
|-------|------------------|-------| |---|---|---|---|
| **Lighthouse (Desktop)** | Performance, SEO, Accessibility, Best Practices | ~30s | | **Search Console** | `get_search_console_performance` | Cliques, impressões, CTR, posição, por query e por página | grátis |
| **Lighthouse (Mobile)** | Core Web Vitals, INP, comparacao mobile/desktop | ~30s | | **Indexação** | `inspect_urls` | Estado de indexação (até 10 URLs) | grátis |
| **Lighthouse (Optimizacoes)** | Oportunidades LCP, JS nao usado, images optimization | ~15s | | **Crawl técnico** | `run_site_audit` → `get_audit_issues` | Issues por severidade, Lighthouse em amostra | grátis |
| **GSC** | Cliques, impressoes, CTR, posicao media, top queries, tendencia 90 dias | ~10s | | **Core Web Vitals** | `chrome-devtools → performance_start_trace` | LCP, INP, CLS por página | grátis |
| **SEO Tools API** | Meta tags, imagens, alt text, links internos/externos, estrutura HTML | ~5s | | **Keywords** | `get_keyword_metrics` | Volume, KD, intenção (até 700/chamada) | pago |
| **Ahrefs (opcional)** | DR, UR, backlinks, referring domains | ~10s | | **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 Total:** ~1m40s (sem concorrencia) | ~3m (com 2 concorrentes) **Tempo:** ~5-10 min (crawl de 600 páginas demora ~4 min). Não é instantâneo — avisar o cliente.
--- ---
## Workflow ## Workflow
1. Validar URL de entrada
2. Verificar se site esta no GSC (skip se nao)
3. Executar auditorias em paralelo:
- Lighthouse Desktop + Mobile
- Core Web Vitals
- SEO Tools API
- GSC Analytics (se disponivel)
- Ahrefs (se habilitado)
4. Processar e formatar dados
5. Gerar relatorio Markdown
6. Criar Google Doc e partilhar
7. Retornar link do documento
---
## Estrutura do Relatorio
O relatorio final tem 8 seccoes:
1. **Sumario Executivo** -- Top 5 descobertas + accao imediata recomendada
2. **Pontuacoes Globais** -- Desktop vs Mobile (Performance, SEO, A11y, Best Practices)
3. **Core Web Vitals** -- LCP, INP, CLS com oportunidades de optimizacao
4. **GSC Analytics** -- Performance overview, top queries, oportunidades CTR (ultimos 90 dias)
5. **Analise On-Page** -- Meta tags, imagens SEO, internal linking
6. **Backlinks e Autoridade** -- DR, UR, top backlinks, estrategia
7. **Plano de Accao** -- Priorizado (critico/importante/melhoria) com impacto e esforco
8. **Roadmap Trimestral** -- Fundacao tecnica -> Conteudo e autoridade -> Consolidacao
---
## Propriedades GSC Disponiveis
``` ```
sc-domain:descomplicar.pt 1. whoami + list_projects → projectId e mercado (GATE: PT = 2620/pt)
https://emanuelalmeida.pt/ 2. GSC por query + por página → paginar até esgotar
https://carstuff.pt/ 3. Dimensionar o crawl → maxPages ≥ nº páginas com impressões + 25%
https://solarfvengenharia.com/ 4. run_site_audit → poll get_audit_status até "completed"
https://aquisevende.pt/ 5. get_audit_issues → critical → warning → info
https://alojadamaria.com/ 6. Cruzar fase 2 com fase 5 → páginas com procura E com defeito = lista de trabalho
https://e-commerce.descomplicar.pt/ 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.
--- ---
## Notas Tecnicas ## 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 ### Requisitos
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh` - OpenSEO acessível (`whoami` responde)
- Google Workspace MCP configurado - Propriedade ligada ao Search Console (senão, relatório sem fase GSC — declarar)
- GSC authentication (OAuth primeira vez) - `google-workspace` MCP para o Google Doc
### Erros Comuns ### Erros comuns
- **Site nao em GSC:** Relatorio gerado sem dados GSC (aviso incluido) | Erro | Sintoma | Solução |
- **Lighthouse timeout:** Retry automatico (3x) |---|---|---|
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio | **`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 (conteudo detalhado) ## References
| Ficheiro | Conteudo | | Ficheiro | Conteúdo |
|----------|----------| |---|---|
| `references/template-relatorio.md` | Template completo do relatorio com todas as tabelas e seccoes | | `references/template-relatorio.md` | Template completo com tabelas e secções |
| `references/implementacao-tecnica.md` | Workflow mermaid, codigo JS, funcoes GSC, notas tecnicas | | `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 ## Anti-patterns
- Gerar relatorio sem dados reais (sempre usar MCPs) - Gerar relatório sem dados reais.
- Ignorar gap mobile/desktop - Omitir a cobertura do crawl (faz o relatório parecer melhor do que é).
- Nao priorizar recomendacoes (tudo parece igual) - Listar issues por contagem em vez de por impacto.
- Esquecer de verificar se site esta no GSC antes de tentar recolher dados - Apresentar estimativas de custo ou de tráfego como medições.
- Relatorio sem accoes concretas e estimativas de impacto - Recomendações sem esforço e impacto estimados.
- Correr as fases pagas antes das grátis.
--- ---
**Versao:** 2.1.0 | **Autor:** Descomplicar **Versão:** 3.0.0 | **Autor:** Descomplicar® | **Motor:** OpenSEO
---
## Healing Log ## Healing Log
Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
```jsonl ```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"} {"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"}
``` ```
*Adicionar nova linha após cada erro corrigido.*
marketing/skills/seo-report/references/implementacao-tecnica.md
+141 -116
View File
@@ -1,144 +1,169 @@
# Implementacao Tecnica - SEO Report # Implementação Técnica — SEO Report (OpenSEO)
## Workflow Tecnico ## Workflow
```mermaid ```mermaid
graph LR graph TD
A[Input: URL] --> B{Site em GSC?} A[Input: URL] --> B[whoami + list_projects]
B -->|Sim| C[Recolher dados GSC] B --> C{Mercado correcto?}
B -->|Nao| D[Skip GSC, aviso] C -->|Não| C2[Passar locationCode 2620 + languageCode pt]
C -->|Sim| D[GSC: dimensions query]
C2 --> D
C --> E[Lighthouse Desktop] D --> E[GSC: dimensions page]
D --> E E --> F[Dimensionar crawl:<br/>maxPages = páginas GSC + 25%]
E --> F[Lighthouse Mobile] F --> G[run_site_audit]
F --> G[Core Web Vitals] G --> H[poll get_audit_status]
G --> H[SEO Tools API] H -->|running| H
H --> I{Ahrefs habilitado?} H -->|completed| I[get_audit_issues por severidade]
I -->|Sim| J[Recolher DR/UR] I --> J[Cruzar: páginas com procura<br/>E com defeito]
I -->|Nao| K[Skip Ahrefs] J --> K{Fases pagas contratadas?}
J --> L[Processar dados] K -->|Sim| L[get_keyword_metrics<br/>get_backlinks_overview<br/>get_serp_results]
K --> L K -->|Não| M[Saltar fases pagas]
L --> M[Gerar relatorio Markdown] L --> N[Processar]
M --> N[Criar Google Doc] M --> N
N --> O[Partilhar com email] N --> O[Markdown] --> P[Google Doc] --> Q[Partilhar]
O --> P[Retornar link]
``` ```
## Implementacao **O ponto crítico é o nó F.** Dimensionar o crawl a partir do GSC é o que distingue um relatório verdadeiro de um relatório limpo e falso.
---
## Sequência de chamadas
```javascript ```javascript
async function generateSEOReport(url, options = {}) { // 1. Contexto e mercado
const { const me = await openseo.whoami();
email = 'emanuelalmeidaa@gmail.com', const projs = await openseo.list_projects();
competitors = [], const projectId = projs[0].id;
includeAhrefs = true const MARKET = { locationCode: 2620, languageCode: 'pt' }; // Portugal
} = options;
// 1. Validar URL // 2. Search Console — paginar até esgotar (grátis)
if (!isValidURL(url)) { async function gscAll(dimensions) {
throw new Error('URL invalido'); const rows = [];
let startRow = 0;
while (true) {
const r = await openseo.get_search_console_performance({
projectId, dimensions, dateRange: 'last_3_months',
rowLimit: 1000, startRow
});
const parsed = parseRows(r.text);
rows.push(...parsed);
if (!r.text.split('\n')[0].includes('more available') || !parsed.length) break;
startRow += 1000;
}
return rows;
} }
// 2. Recolher dados em paralelo (melhor performance) const byQuery = await gscAll(['query']);
const [ const byPage = await gscAll(['page']);
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),
includeAhrefs ? getAhrefsData(url) : null
]);
// 3. Processar e formatar // 3. Dimensionar o crawl a partir da realidade, não de um default
const reportData = { const maxPages = Math.ceil(byPage.length * 1.25);
url,
date: new Date().toISOString().split('T')[0], // 4. Crawl (grátis) — assíncrono, exige poll
scores: extractScores(lighthouseDesktop, lighthouseMobile), const audit = await openseo.run_site_audit({
cwv: processCoreWebVitals(coreWebVitals), projectId, url, maxPages, runLighthouse: true
gsc: processGSCData(gscData), });
onPage: processOnPageData(seoToolsData), let status;
backlinks: processBacklinks(ahrefsData), do {
recommendations: generateRecommendations(/* all data */) await sleep(30_000);
status = await openseo.get_audit_status({ projectId, auditId: audit.id });
} while (!status.text.includes('completed'));
// 5. Issues por severidade (grátis)
const critical = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'critical' });
const warning = await openseo.get_audit_issues({ projectId, auditId: audit.id, severity: 'warning' });
// 6. Fases pagas — so se contratadas
if (options.paid) {
const kw = await openseo.get_keyword_metrics({
projectId, keywords: strikingDistance(byQuery).map(r => r.key), ...MARKET
});
const bl = await openseo.get_backlinks_overview({ projectId, target: domain });
}
```
---
## Processamento — as funções que importam
```javascript
// GSC anonimiza queries: totais por query < totais por página.
// Para números globais usar SEMPRE a vista por página.
const globals = {
clicks: sum(byPage, 'clicks'),
impressions: sum(byPage, 'impressions'),
ctr: sum(byPage, 'clicks') / sum(byPage, 'impressions')
}; };
// 4. Gerar documento Markdown // O GSC não filtra por posição — filtrar do lado do cliente.
const markdown = generateReportMarkdown(reportData); const strikingDistance = rows => rows
.filter(r => r.position >= 4 && r.position <= 20 && r.impressions >= 25)
.sort((a, b) => b.impressions - a.impressions);
// 5. Criar Google Doc // Páginas com procura real enterradas fora das primeiras 4 páginas.
const docResult = await mcp__google-workspace__create_doc({ const waste = rows => rows
title: `Relatorio SEO - ${extractDomain(url)} - ${reportData.date}`, .filter(r => r.position > 40 && r.impressions >= 300)
body_content: markdown, .sort((a, b) => b.impressions - a.impressions);
// O sinal mais accionável: primeira página, CTR nulo.
// Não é ranking — é título e meta description.
const titleProblem = rows => rows
.filter(r => r.position <= 10 && r.impressions >= 200 && r.ctr < 0.005);
// Lixo nas queries do GSC (colagens do Google Ads, operadores site:).
const isNoise = k =>
(k.includes('ativado') && k.includes('correspond')) ||
k.startsWith('-site:') || k.startsWith('=') ||
k.length > 90 || k.includes('0,00');
```
---
## Entrega
```javascript
const doc = await googleWorkspace.docs_create_document({
title: `Relatório SEO — ${domain} — ${today}`,
user_google_email: email user_google_email: email
}); });
await googleWorkspace.docs_append_text({ document_id: doc.id, text: markdown });
// 6. Retornar link
return {
success: true,
doc_url: docResult.url,
summary: reportData.recommendations.slice(0, 5)
};
}
``` ```
## Propriedades GSC Disponiveis ---
```javascript ## Notas técnicas
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/'
];
async function getGSCData(url) {
const domain = extractDomain(url);
const property = GSC_PROPERTIES.find(p => p.includes(domain));
if (!property) {
console.warn(`Site ${domain} nao esta no GSC. Dados GSC nao disponiveis.`);
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;
}
```
## Notas Tecnicas
### Requisitos ### Requisitos
- SEO Tools API a correr: `~/mcp-servers/seo-tools-api/start.sh` - OpenSEO acessível (`whoami` responde)
- Google Workspace MCP configurado - Propriedade ligada ao Search Console
- GSC authentication (OAuth primeira vez) - `google-workspace` MCP para o documento
### Performance ### Tempos reais (medidos, descomplicar.pt, 07-2026)
- Execucao paralela de tools (1m40s total) | Fase | Duração |
- Cache Lighthouse results (5 min TTL) |---|---|
- Rate limiting Ahrefs API (100 req/day free) | GSC (2 dimensões, ~1700+474 linhas) | ~10s |
| Crawl 600 páginas + Lighthouse 20 | ~4 min |
| `get_audit_issues` | instantâneo |
### Erros Comuns ### Limitações
- **Site nao em GSC:** Relatorio gerado sem dados GSC - **Issues sem URL:** `get_audit_issues` / `get_audit_pages` devolvem só contagens pela bridge MCP; `structuredContent.issues` não é entregue e `get_audit_pages` trunca em ~25 linhas. Usar `details.mcpMeta.url` para o link da UI.
- **Lighthouse timeout:** Retry automatico (3x) - **Sem medidor de créditos:** `whoami` não muda depois de chamadas pagas. Custos são estimativas.
- **Ahrefs rate limit:** Skip backlinks, aviso no relatorio - **Lag do GSC:** últimos ~3 dias incompletos; datas em Pacific Time; máx. 16 meses.
### Erros comuns
| Erro | Sintoma | Solução |
|---|---|---|
| `maxPages` por omissão (50) | Poucos issues, relatório "limpo" | Redimensionar pelo GSC, relançar |
| Site fora do GSC | Fase GSC vazia | Gerar sem GSC, aviso destacado |
| Mercado errado | Keywords em inglês/EUA | `locationCode: 2620`, `languageCode: "pt"` |
| Cancelar o crawl cedo demais | Sem `auditId` utilizável | Fazer poll; 600 páginas ≈ 4 min |
---
**Actualizado:** 30-07-2026 | Substitui a implementação baseada em Lighthouse MCP + SEO Tools API + Ahrefs
marketing/skills/seo-report/references/template-relatorio.md
+9 -5
View File
@@ -203,13 +203,17 @@ Data: YYYY-MM-DD | Versao 2.0 (2026 Standards)
## Anexos ## Anexos
### A. Metodologia ### A. Metodologia
- Lighthouse: 3 runs, mediana reportada - Motor: OpenSEO (crawl same-origin, robots-aware) + Search Console
- GSC: Ultimos 90 dias completos - Crawl: [N] páginas de [M] com impressões no GSC — **declarar sempre a cobertura**
- Search Console: últimos 3 meses; vista por página para totais (o GSC anonimiza queries)
- Core Web Vitals: Lighthouse em amostra; páginas individuais via chrome-devtools
- Thresholds: Google 2026 Standards - Thresholds: Google 2026 Standards
- Custos de chamadas pagas: estimativas do schema, não medições
### B. Glossario ### B. Glossário
- **DR**: Domain Rating (Ahrefs) - **Striking distance**: posição 4-20 com impressões relevantes — onde está o retorno
- **INP**: Interaction to Next Paint (substitui FID em 2026) - **KD**: Keyword Difficulty
- **INP**: Interaction to Next Paint (substituiu o FID em 2026)
- **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust - **E-E-A-T**: Experience, Expertise, Authoritativeness, Trust
- **CTR**: Click-Through Rate - **CTR**: Click-Through Rate