Skill /ghl para Claude Code — Integração GoHighLevel
LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill
Controle seu CRM GoHighLevel direto do Claude — sem deixar o terminal
Ver no GitHubSkill Python que integra o Claude Code ao GoHighLevel, permitindo criar e atualizar contatos, oportunidades, campos personalizados e tags via API v2. Resolve pegadinhas comuns (Cloudflare, deduplicação, normalização de telefone) e importa bases inteiras de planilhas com segurança.
Instalação
npx convez-ai LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Importar bases de leads com deduplicação automática
- Criar e atualizar contatos e oportunidades em massa
- Gerenciar campos personalizados e tags por automação
- Integrar pipelines de dados com o GHL
Veredito

Skill bem-documentada e pragmática que resolve frustações reais da API v2 do GHL (Cloudflare, dedup fraca, normalizações). Ideal para quem usa GoHighLevel e quer automatizar operações repetitivas via IA — requer credenciais e conhecimento da plataforma.
README
A tradução para o português deste README ainda está na fila.
🚀 Skill /ghl para Claude Code — opere o GoHighLevel direto do terminal
Uma skill do Claude Code que transforma a IA num operador
do seu CRM GoHighLevel (GHL / HighLevel). Com um simples /ghl você passa a criar e
atualizar contatos, oportunidades, campos personalizados e tags, além de importar bases
inteiras (planilhas) com deduplicação — tudo via API v2, sem abrir a interface pra tarefa
repetitiva.
Construída e disponibilizada pelo Luiz Otávio — Engenheiro Digital, pra comunidade. Pega, instala, e bota a IA pra trabalhar no seu GHL. 100% genérica e sem nenhum segredo: você pluga as SUAS credenciais.
🤔 O que é o GoHighLevel (GHL)?
GoHighLevel é uma plataforma all-in-one de CRM e automação de marketing muito usada por agências e
infoprodutores: funis (pipelines), contatos, oportunidades, campos personalizados, tags, automações
(workflows), smart lists, disparos etc. Ele expõe uma API v2 em services.leadconnectorhq.com.
🧠 O que essa skill faz por você
Depois de instalada, é só conversar com o Claude. Exemplos do que ele resolve:
- "Cria um contato pra fulano com email X e telefone Y, e abre uma oportunidade no funil de vendas."
- "Importa essa planilha de 2 mil leads, sem duplicar quem já existe."
- "Lista meus funis, etapas e campos personalizados com os IDs."
- "Cria um campo personalizado
Lead Scorenumérico." - "Adiciona a tag
status:cliente-ativoem todo mundo que fechou." - "Acha o contato com esse telefone e me mostra."
E, importante: a skill já conhece as pegadinhas do GHL (veja abaixo), então o Claude não cai nos erros que fazem todo mundo perder horas.
⚠️ As pegadinhas que essa skill já resolve
- Cloudflare "Error 1010". Sem um User-Agent de navegador, o GHL bloqueia chamadas de bibliotecas Python padrão. O cliente já injeta o header certo.
- A API v2 não cria tudo. Funis/etapas, workflows e smart lists só pela interface. A API cria contatos, oportunidades, campos e tags. A skill sabe a diferença e te dá a "receita de cliques" quando algo é UI-only.
- A deduplicação do GHL é fraca (só casa email OU telefone exato). A skill faz merge em memória antes de subir — uma pessoa real = um contato só.
- Telefone tem que ser E.164 (
+55...). A skill normaliza e cria uma chave de dedup canônica. - Planilhas vêm com linhas vazias de padding — a skill filtra antes de contar/importar.
- Nome só de fonte confiável (nada de "Lead #123" ou "@handle" como nome).
- Uma oportunidade por funil por pessoa (o GHL barra duplicada no mesmo funil).
Tudo isso está documentado dentro de ghl/SKILL.md — é o que o Claude lê pra agir.
📦 Instalação
Pré-requisitos
- Claude Code instalado.
- Python 3 (já vem no macOS/Linux).
- Uma conta/subconta no GoHighLevel.
1. Baixe a skill
Clone o repositório (ou baixe o ZIP em Code → Download ZIP):
git clone https://github.com/LUIZOTAVIOENGENHARIADIGITAL/ghl-claude-skill.git
cd ghl-claude-skill
2. Copie a skill pra pasta do Claude
A pasta ghl/ é a skill. Copie pra ~/.claude/skills/:
mkdir -p ~/.claude/skills
cp -R ghl ~/.claude/skills/ghl
3. Pegue suas credenciais do GHL
Na sua subconta: Settings → Private Integrations → Create new integration. Dê os escopos de
Contacts, Opportunities, Custom Fields e Tags. Copie o token (começa com pit-...) e o
locationId da subconta.
4. Configure as variáveis de ambiente
Exporte no seu shell (ex.: ~/.zshrc ou ~/.bashrc):
export GHL_TOKEN="pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export GHL_LOCATION="seu-location-id"
Veja
.env.examplepro formato. Nunca comite suas credenciais.
5. Teste
python3 ~/.claude/skills/ghl/scripts/ghl.py whoami
Se aparecer sua location, seus funis e o total de contatos, está funcionando. ✅
6. Use no Claude
Abra o Claude Code e digite:
/ghl lista meus funis e campos
ou simplesmente peça em linguagem natural: "cria um contato no GHL pra ...".
🛠️ Uso direto do cliente (sem o Claude)
O scripts/ghl.py também roda sozinho:
python3 ghl/scripts/ghl.py whoami # location + funis + total de contatos
python3 ghl/scripts/ghl.py pipelines # funis e etapas (com IDs)
python3 ghl/scripts/ghl.py fields contact # campos de contato
python3 ghl/scripts/ghl.py fields opportunity # campos de oportunidade
python3 ghl/scripts/ghl.py tags # tags da conta
python3 ghl/scripts/ghl.py count # total de contatos
python3 ghl/scripts/ghl.py find email@ou.telefone
E como módulo Python, pra construir seus próprios importadores:
from ghl import upsert, create_opp, find_field, find_stage
c = upsert({"firstName": "Maria", "email": "maria@exemplo.com",
"phone": "+5511999999999", "tags": ["status:lead", "source:youtube"]})
create_opp("Maria - Lead", "Funil de Vendas", "Novos Leads", "open",
c["id"], value=997, source="youtube")
🔐 Segurança
- Zero segredos no repositório. O código lê tudo de variáveis de ambiente.
- Seu
.envé ignorado pelo git (veja.gitignore). - O token é seu e dá acesso ao seu CRM — trate como senha.
📁 Estrutura do repositório
ghl-claude-skill/
├── ghl/ # a skill (copie pra ~/.claude/skills/)
│ ├── SKILL.md # instruções que o Claude lê pra operar o GHL
│ └── scripts/
│ └── ghl.py # cliente Python da API v2 (UA correto, rate-limit, retry)
├── .env.example # modelo de credenciais
├── .gitignore
├── LICENSE # MIT
└── README.md
📺 Conteúdo
Quer aprender a estruturar CRM, funis e automações do jeito certo (dados > achismo)? Acompanhe o canal do Luiz Otávio — Engenheiro Digital no YouTube.
📄 Licença
MIT — use, modifique e distribua à vontade. Se ajudar, deixa uma ⭐ no repo!