Quando a Cabgo publica uma atualização do skill público do servidor MCP, os operadores que instalaram a versão original sem modificá-la recebem as melhorias de forma direta: novas ferramentas disponíveis, instruções de sistema corrigidas, padrões de uso otimizados. Os operadores que editaram o skill diretamente para adicionar suas convenções internas — nomes de zonas, limiares próprios, fluxos de escalonamento — enfrentam o mesmo dilema a cada nova versão: sobrescrevem com a atualização e perdem suas adições, ou ficam com a sua versão e acumulam dívida de funcionalidade. Esse dilema tem uma solução que não exige escolher entre os dois caminhos — exige separar as duas camadas desde o começo.
Este artigo é para o operador que já tem o skill instalado e funcionando, começou a adicionar contexto específico da sua operação e quer uma forma de manter essas convenções sem que cada atualização da plataforma seja uma decisão sobre o que perder. O padrão descrito aqui — separar o skill base do contexto do operador em arquivos distintos — não exige conhecimentos avançados de desenvolvimento. É uma decisão de estrutura que qualquer pessoa que já tenha editado as instruções de sistema do agente uma vez consegue implementar em menos de uma hora, e que transforma cada futura atualização do skill em uma operação de dez minutos, sem conflitos.
O skill público como base de configuração, não como destino final
O skill público que a Cabgo publica contém as definições das ferramentas do servidor MCP, um conjunto de instruções de sistema que orienta o agente sobre os padrões de uso esperados, e exemplos de prompts para as tarefas mais comuns. O que o skill não pode incluir por design — porque é o mesmo para todos os operadores — são as convenções específicas de cada operação: o nome que a equipe usa para a zona de alta demanda do aeroporto, o limiar de disponibilidade que aquele operador considera alerta na baixa temporada, o critério interno de quando escalar uma ocorrência ao coordenador de turno em vez do dono do negócio. Essa segunda camada é a que transforma o skill genérico em uma ferramenta útil para aquela operação específica, com aqueles motoristas, naquelas zonas, com aqueles critérios.
O problema aparece quando essa segunda camada é adicionada diretamente dentro dos mesmos arquivos que definem a primeira. Editar o arquivo de instruções de sistema do skill para incluir as convenções próprias não está tecnicamente errado — o agente funciona e os resultados melhoram. O erro é de arquitetura: quando a plataforma publicar uma versão nova do skill com instruções melhoradas ou novas ferramentas disponíveis, o operador terá que decidir entre atualizar os arquivos base e perder suas adições, ou manter a sua versão modificada e ficar sem as melhorias. Os dois custos são reais e recorrentes.
Onde a personalização costuma entrar e por que esse lugar cria atrito futuro
A maioria dos operadores que personaliza o skill faz isso em um ou dois pontos: adiciona linhas ao arquivo de instruções de sistema do skill instalado e, em alguns casos, ajusta parâmetros das definições de ferramentas para refletir os nomes ou faixas da sua operação específica. As mudanças são razoáveis e na direção correta — o problema não é o que se adiciona, mas em qual arquivo. Os arquivos base do skill são exatamente os que a plataforma vai atualizar quando sair a próxima versão.
O resultado prático: a primeira atualização relevante chega e o operador descobre que tem um conflito entre a versão que usa e a nova. Se escolher o caminho mais rápido e sobrescrever com a atualização, as convenções internas desaparecem e é preciso adicioná-las de novo, de memória. Se decidir não atualizar para conservá-las, começa a acumular distância em relação às melhorias da plataforma — o agente opera com instruções que já não refletem as capacidades atuais do servidor. Os dois caminhos têm custo. A alternativa é não colocar as convenções nos arquivos que a plataforma vai atualizar.
O padrão de camadas: separar o skill base do contexto do operador
O padrão que elimina esse dilema é estruturalmente simples: os arquivos do skill público não são modificados. Eles são instalados exatamente como a plataforma publica e atualizados diretamente quando sai uma nova versão. As convenções internas do operador ficam em um arquivo separado — vamos chamá-lo de `context_operador.md` ou qualquer nome que a equipe preferir — que é carregado nas instruções de sistema do cliente do agente (Claude Desktop, ChatGPT, ou o cliente que a equipe usar), mas que não faz parte do diretório do skill em si.
A separação tem uma implicação prática importante em como se estrutura a seção de instruções de sistema no cliente. A primeira parte referencia o skill público sem alterações — as instruções de ferramentas e os padrões de uso do servidor exatamente como a plataforma publicou. A segunda parte carrega o arquivo de convenções do operador: os nomes de zona, os limiares específicos, o critério de escalonamento interno. Quando a plataforma atualiza o skill, o operador atualiza a primeira parte — ou reinstala os arquivos do skill no diretório. A segunda parte não tem conflitos porque nunca esteve nos arquivos que foram atualizados.
Quais convenções vale a pena manter na sua camada
Nem todo o conhecimento que o operador tem sobre a sua operação precisa estar formalizado no arquivo de convenções. A informação que muda em tempo real — o status de motoristas ativos agora mesmo, os picos do momento — o agente obtém diretamente do servidor MCP em cada consulta. O que realmente vale a pena codificar na camada do operador é o contexto estrutural: aquele que é estável entre turnos e que o agente precisa para interpretar corretamente os dados que recebe do servidor.
- **Nomes de zona e sua correspondência**: se a equipe chama de «Zona Norte» o que o mapa registra como «setor 04», esse mapeamento nas instruções evita ambiguidade em cada consulta — sem ele o agente usa o identificador técnico do servidor e a equipe tem que traduzir mentalmente a cada resposta
- **Limiares de normalidade próprios**: as faixas de disponibilidade, taxa de cancelamento e tempos de espera que são normais para aquela operação específica, por horário e zona — os valores padrão do skill são genéricos e não refletem a realidade de cada mercado
- **Fluxo de escalonamento interno**: quem recebe qual tipo de alerta, por qual canal e em qual horário — o skill não pode saber que o coordenador do turno da noite prefere os alertas de tarifa dinâmica pelo WhatsApp e que o dono do negócio revisa o resumo no dashboard só no final do dia
- **Convenções de tenantId por contexto**: se a operação tem dois tenants (táxi e delivery) e as tarefas de cada tipo sempre usam o mesmo, formalizar isso na camada evita o erro de misturar tenants em consultas rápidas onde não se especifica de forma explícita
- **Resoluções de ocorrências recorrentes**: a solução que já funcionou para os problemas que reaparecem — quando o agente reconhece o padrão e já tem a resolução em contexto, a consulta termina em uma resposta direta, não em um diagnóstico do zero
Como incorporar uma atualização do skill sem afetar a sua camada
Com o padrão de camadas implementado, incorporar uma atualização do skill público é uma sequência de três passos que leva menos de dez minutos. O primeiro é baixar ou atualizar o diretório do skill a partir do repositório da plataforma — se você usa git, um `git pull` na pasta do skill é suficiente. O segundo é revisar o changelog da atualização para entender o que mudou: algumas atualizações adicionam novas ferramentas, outras ajustam os nomes de parâmetros existentes ou o formato das respostas. Se houver mudanças desse tipo, pode ser necessário um ajuste menor na camada do operador — não no skill base. O terceiro é verificar que as instruções de sistema no cliente do agente continuam referenciando corretamente os arquivos atualizados.
Se o operador nunca modificou os arquivos base do skill, esses três passos são tudo o que é necessário. A camada do operador não tem conflitos porque fica em um arquivo distinto. Se as mudanças no skill implicarem ajustes no contexto do operador — por exemplo, uma ferramenta renomeada que o operador menciona pelo nome no seu arquivo de convenções — esses ajustes são feitos no arquivo do operador, não nos arquivos do skill. O resultado: o agente tem as melhorias da plataforma e as convenções internas do operador, sem interferência entre as duas.
Verificar que a camada funciona depois de aplicar uma atualização
A verificação mais direta depois de uma atualização é uma consulta diagnóstica ao agente antes de voltar a usá-lo em produção. Um prompt simples — «Quais zonas você tem definidas como de alta demanda para esta operação? Qual é o limiar de disponibilidade que você considera normal nesta cidade?» — pede ao agente que devolva o que tem em contexto ativo naquele momento. Se a resposta incluir os nomes e valores do arquivo do operador, a atualização não os afetou. Se o agente devolver valores genéricos ou não reconhecer os nomes internos, há um problema em como o arquivo de convenções foi carregado nas instruções de sistema do cliente.
Essa verificação leva dois minutos e tem um valor desproporcional: evita operar um turno com um agente que tem as melhorias do skill mas perdeu o contexto da operação. O sintoma desse estado nem sempre é visível de imediato — o agente responde perguntas, acessa o servidor, produz outputs com o formato correto — mas faz isso sem o enquadramento que produz respostas específicas para aquela operação. Um agente sem convenções carregadas é funcionalmente equivalente a um recém-instalado: correto na forma, mas genérico no conteúdo. Para uma operação que passou meses refinando sua camada de contexto, perder isso silenciosamente em uma atualização tem exatamente o mesmo custo que não tê-la construído.
Na primeira vez que saiu uma atualização do skill, sobrescrevi os arquivos e perdi as instruções para as minhas zonas. Levei um dia para reconstruí-las de memória. A segunda atualização eu já apliquei com o arquivo do operador separado — dez minutos, sem conflitos, e minhas convenções ficaram intactas.
O padrão de camadas não é uma prática avançada de desenvolvimento — é uma decisão sobre onde o operador guarda o conhecimento da sua operação. O skill público da plataforma resolve a interface com o servidor MCP: quais ferramentas existem, como são invocadas, o que retornam. O arquivo de convenções do operador resolve o contexto da operação específica: o que significam os dados que o skill retorna em termos daquela cidade, daquela equipe e daqueles limiares próprios. As duas camadas respondem perguntas distintas e, quando ficam em arquivos distintos, podem ser atualizadas de forma independente sem que uma afete a outra.
Se você está há mais de um mês com o skill instalado e ainda não separou as camadas, o momento mais conveniente para fazer isso é antes de chegar a próxima atualização importante. O inventário do que tornaria a sua camada útil não é extenso: cinco a oito convenções que a equipe usa com frequência suficiente para valer a pena documentá-las em um lugar fixo. Criar o arquivo, mover para lá o que você já tem espalhado nas instruções de sistema, e atualizar as referências no cliente leva menos de uma tarde. As próximas atualizações do skill serão uma operação de dez minutos, em vez de uma decisão sobre o que perder.
