As Skills do Claude são a coisa mais fácil do mundo de escrever. Um arquivo de texto, quatro linhas de instrução, e o Claude passa a fazer algo que antes não fazia.
E sabe a melhor parte? Você nem precisa escrever. Existe uma Skill cuja única função é escrever Skills: você diz o que precisa, ela faz duas perguntas e devolve pronta para usar. O Claude escrevendo as próprias instruções.
Tem milhares para baixar. Curadas, gratuitas, prontas.
Aí você escreve uma. Uma de verdade, feita para o seu trabalho e os seus clientes. E vem a vontade mais natural do mundo: compartilhar com o seu time.
É aí que começa a confusão.
O que você precisa para começar
Antes do como, vamos tirar do caminho a pergunta que trava todo o resto: quanto custa se colocar em condição de fazer isso.
- Uma conta Cloudflare. Gratuita. É onde o servidor roda e onde ficam as credenciais.
- Uma conta GitHub. Gratuita. É o canal de distribuição — e também o canal de login, então é ele que permite identificar o usuário.
- Uma assinatura do Claude (ou de outro assistente de código) para escrever o código do servidor. Essa você provavelmente já tem, se chegou até aqui.
Nenhuma infraestrutura para comprar. Nenhum plano enterprise para ativar. Nenhum fornecedor para ligar.
Para um time de três pessoas a conta é zero por mês. O custo real é uma tarde de trabalho.
Como fomos parar nessa bagunça
Vou contar como nasceu, assim você entende o problema na hora.
Você abre a sua empresa. Está com gás total. Trabalha para um cliente, depois para outro, depois passa dois dias arrumando o próprio site. Seus sócios fazem mais ou menos o mesmo.
No fim do dia você abre o Kimai — a ferramenta com que lançamos as horas nos projetos — cria um apontamento e escreve que passou duas horas num projeto e quatro em outro.
Você faz uma vez. Faz duas… na terceira você se sente um homem das cavernas.
Você trabalha com IA horas por dia, e à noite faz digitação manual como em 2010?
Inaceitável!
Então você abre a documentação da API do Kimai e em meia hora monta a sua ferramenta: daí em diante você dita as horas para o agente e ele lança.
Que satisfação.
Aí você entrega para os sócios. E aqui você faz a primeira besteira sem perceber: escreve exatamente o mesmo código três vezes, uma por pessoa, porque cada cópia precisa ter o id de usuário certo dentro — senão as horas do Otoni saem no meu nome.
Passa um mês. Você adiciona o Matomo para acompanhar as visitas do site. Monta a ferramenta de estatísticas, pluga no Claude, funciona lindamente!
Depois você tenta agendar uma tarefa que manda os números toda segunda de manhã.
E para de funcionar.
Por quê? Porque as tarefas agendadas rodam no sandbox do Cowork. E o sandbox não enxerga aquela ferramenta. E, já que estamos falando disso, o Claude Code também não. Mesmo computador, mesma pessoa, três caixas separadas que não conversam.
Enquanto isso, cadê o token do Matomo? Em texto puro, num arquivo no seu notebook.
E aí, o que você faz? Escreve uma Skill com o token dentro e passa para os sócios. Ótimo, agora todo mundo pode perguntar ao Claude como estão as visitas.
Pena que agora esse token está em texto puro em três computadores diferentes.
Cibersegurança: um espetáculo.
E a sua cabeça doente de desenvolvedor não para. A ferramenta de SEO. A que gera os PDFs na identidade da Arkad. A que escaneia os sites dos clientes. Uma atrás da outra.
Algumas semanas depois você olha para trás e encontra isto: um monte de Skills, com tokens em texto puro dentro, que funcionam num ambiente e no outro não, em versões diferentes entre você e os seus sócios.
Me acompanha? Pois é, foi aí que entendi que era hora de parar e pensar numa solução.
Na mesa, cinco obstáculos:
- Distribuição — como minhas Skills chegam aos sócios.
- Atualização — como eles sabem se estão com a última revisão.
- Segredos — onde coloco um token sem espalhar por aí.
- Portabilidade — como faço funcionar em três ambientes que não se falam.
- Identidade — como o servidor sabe qual dos três está usando.
Vamos um por um.
O que são as Claude Skills (e por que não são um MCP)
Precisamos de uma distinção. É ela que destrava todo o resto.
Uma Skill é um arquivo de texto com instruções. Diz ao Claude como se faz uma coisa: que procedimento seguir, em que ordem, com quais cuidados, o que nunca fazer. Não executa nada. É saber, não é braço.
Um conector MCP (Model Context Protocol) é o oposto. É um serviço que expõe funções executáveis. Não explica nada: faz. Consulta um banco, chama uma API, escreve num CRM.
As Skills instruem. Os conectores agem.
Parece sutileza de manual. É, na verdade, a chave de tudo: as duas coisas viajam juntas mas precisam ficar separadas — e mais adiante você vai ver que é justamente dessa separação que nasce a economia de contexto.
Acima das duas está o recipiente. Um plugin é um pacote que junta Skills e conectores numa única unidade versionada: a pessoa instala com um comando e atualiza com outro.
Skills e conectores são as peças. O plugin é a caixa com que você despacha tudo.
O mesmo plugin no Claude Desktop, Claude Code e Cowork
Começo pelo problema mais doloroso, a portabilidade, porque a solução é quase constrangedora de tão simples.
Um conector MCP remoto não vive no seu computador. Vive num servidor — no nosso caso um Worker na Cloudflare, gratuito até volumes que três pessoas não alcançam nem por acidente.
E como vive na internet e não na sua pasta de usuário, todos os ambientes enxergam do mesmo jeito.
Você conecta no Cowork e encontra igualzinho no Claude Code. Abre no desktop e está lá. As tarefas agendadas acham. E como o protocolo é aberto, esse mesmo servidor pode ser usado por qualquer outro cliente que fale MCP — o ChatGPT, por exemplo.
Não resolvi o problema configurando melhor os três ambientes. Resolvi tirando de dentro dos três a coisa que precisava ser configurada.
Primeiro obstáculo derrubado. ✊
Segredos e OAuth: onde os tokens realmente vão parar
O segundo cai quase por consequência. Mas vale olhar de perto, porque é o que convence os clientes mais cautelosos.
Se o servidor está na Cloudflare, o token do Matomo você carrega uma vez só, como secret do Worker. A partir daí ele vive lá: criptografado, fora dos notebooks, fora dos chats, fora dos e-mails. Nenhum dos meus sócios jamais viu esse token. E não precisa ver.
Quando eu roto, atualizo num ponto só. Não existem outros lugares de onde tirar, porque ele nunca esteve em outro lugar.
E os sócios, como entram, se não têm o token?
Com OAuth. O servidor pede a quem se conecta que se identifique e em troca dá um acesso próprio, rastreável, revogável individualmente. É o mesmo mecanismo de quando você entra num app usando a conta Google.
A diferença eu resumiria assim: o segredo não se guarda em três cópias, se escreve uma vez por todas no servidor.
Segundo obstáculo derrubado. Toca aqui 🖐️
Ei servidor, sou o Fabrizio: o problema da identidade
Agora a parte que ninguém conta, e que na minha opinião é o verdadeiro motivo para construir um MCP próprio.
Hoje todo fornecedor tem o seu conector. Google Drive tem. Gmail tem. Notion tem. Sai um novo toda semana. Então por que escrever o seu?
Porque o conector oficial resolve o caso fácil: o serviço dele, a sua conta, um de cada vez. Fora disso sobram três casos descobertos, e são justamente os que eu encontrei.
O conector não existe. Sua ferramenta interna, o script que você escreveu em cima da API de um sistema de gestão, o banco de dados de casa: nenhum fornecedor vai escrever o conector da sua ferramenta pessoal.
Você precisa de duas contas do mesmo serviço. Hoje cada conector segura uma só: você conecta o seu Gmail e a caixa contact@ da empresa fica de fora.
Lá na frente existe uma chave só para todos. O acesso funciona muito bem, mas o sistema do outro lado vê um usuário único para o time inteiro. O acesso está resolvido. Quem é você, não.
Pega o Kimai, o sistema em que registramos as horas nos projetos dos clientes. O servidor tem um token de administrador: um só, poderosíssimo, capaz de lançar as horas de qualquer pessoa. Cômodo para o servidor. Inútil para nós.
Porque se eu lanço três horas num projeto, essas três horas precisam aparecer no meu nome. Não no nome do sócio que configurou o token primeiro. Não no nome de um usuário genérico "Arkad".
Isso se chama rastreabilidade. Sem ela, o registro de horas é papel picado: você não sabe quem fez o quê, não fatura com precisão, não entende para onde está indo o tempo do time.
Como isso costuma ser resolvido? Mal. Três chaves de API diferentes, uma por sócio, cada uma para guardar, cada uma para rotacionar, cada uma para reconfigurar em três ambientes. Voltamos ao ponto de partida, multiplicado por três.
O caminho limpo que escolhemos: cada um se autentica com a própria conta GitHub, dentro de uma organização do GitHub à qual só nós temos acesso.
Duas coisas decorrem disso:
- O muro. Só membros da organização podem usar o conector. Quem não está dentro não entra — e no dia em que alguém sai do time, você tira da organização e a pessoa perde o acesso a tudo. Um gesto só, não uma caça às chaves espalhadas.
- O nome. O servidor sabe quem você é a cada chamada. Então quando eu lanço as horas não preciso dizer que sou o Fabrizio: ele já sabe, e coloca meu nome no lugar certo sozinho.
Nenhum de nós três tem chave de API do Kimai. Não precisamos ter. Autenticamos uma vez com o GitHub e o resto o servidor faz, sabendo exatamente quem pediu o quê.
E já que o servidor é você quem escreve, leva um segundo benefício junto. O conector oficial de um fornecedor traz para dentro quarenta ferramentas e permissões largas: você carrega todas, sempre, mesmo usando duas. O seu expõe seis, só leitura, com as regras escritas no servidor. Menos contexto ocupado — volto nisso adiante — e uma superfície bem menor para defender. Para um cliente cauteloso isso não é detalhe técnico: é argumento de venda.
Terceiro obstáculo derrubado.
Aqui está, mais ou menos, como se esquematiza o nosso sistema de autenticação MCP.
Como instalar um plugin no Claude Code
Antes de mostrar o repositório inteiro, o passo prático, porque é a dúvida que aparece primeiro.
Um marketplace se adiciona uma vez. Um plugin se instala pelo nome. No Claude Code, dentro da sessão:
/plugin marketplace add <organização>/<repositório>
/plugin install <nome-do-plugin>@<nome-do-marketplace>A ordem importa: a instalação falha enquanto o marketplace não tiver sido adicionado. Fora da sessão, no terminal puro, os mesmos comandos existem como claude plugin marketplace add … e claude plugin install ….
No Cowork o caminho é outro: baixa-se o arquivo .plugin — que é um zip do diretório do plugin — e importa-se em Configurações → Plugins.
E o login? Se o plugin traz um conector protegido por OAuth, não existe token para colar. No Claude Code local você dispara o fluxo com /mcp → Authenticate e o navegador resolve sozinho. No claude.ai, no Desktop e no Cowork você conecta em Configurações → Conectores. Aqui vai o detalhe que economiza uma hora de suporte: não use o link de autorização gerado dentro do chat numa sessão remota — ele carrega um callback em localhost que só funciona para o Claude Code rodando na sua própria máquina.
Como criar suas próprias Skills
Uma Skill é uma pasta com um SKILL.md dentro. O arquivo tem um frontmatter com name e description, e abaixo o corpo em Markdown com as instruções.
A description é a parte que a maioria escreve mal, e é a única que o modelo lê o tempo todo. Ela não descreve a Skill: ela diz quando acionar. Liste as frases reais que a pessoa digita — nos idiomas em que ela realmente escreve — em vez de um resumo elegante do conteúdo.
No corpo vale a regra que salva tempo depois: escreva o procedimento, não a teoria. Que ferramenta chamar, em que ordem, o que fazer quando o retorno vem vazio, o que nunca fazer. Se a Skill acompanha arquivos — modelos, CSS, imagens — eles moram numa pasta assets/ dentro da própria Skill e viajam junto com o plugin.
E se der preguiça de começar do zero: peça ao próprio Claude. Existe uma Skill que escreve Skills, ela faz duas perguntas e devolve a estrutura pronta. Você só revisa a description.
Como se instala o plugin a partir de um marketplace no GitHub
Ficaram distribuição e atualização, que no fundo são o mesmo problema visto em dois momentos.
A resposta é um repositório GitHub configurado como marketplace: um registro que lista os plugins disponíveis. Dentro está tudo: o catálogo, um plugin por família de ferramentas, e — desde que juntamos os dois repositórios — o código do Worker também. Skill e ferramenta mudam no mesmo commit.
arkad-marketplace/
├── .claude-plugin/
│ └── marketplace.json # o catálogo: nome, dono, lista de plugins
├── plugins/
│ ├── arkad-documents/ # plugin só de Skills: sem MCP, sem segredos
│ │ └── skills/arkad-documents/
│ │ ├── SKILL.md
│ │ └── assets/ # modelos e logos viajam dentro da Skill
│ └── arkad-tools/ # plugin com conector: um MCP, dez Skills
│ ├── .claude-plugin/
│ │ └── plugin.json # nome e versão — a versão é o interruptor de release
│ ├── .mcp.json # quatro linhas: tipo http e URL. Nenhum token.
│ └── skills/ # arkad-connect, arkad-seo, arkad-kimai…
├── arkad-tools.plugin # o zip do plugin: é assim que o Cowork instala
└── gateway/ # o Worker Cloudflare, no mesmo repositório
├── src/index.js # o OAuth que envolve o handler MCP
├── src/github-auth.js # login GitHub e allowlist da organização
├── src/mcp.js # JSON-RPC: initialize, tools/list, tools/call
├── src/tools/ # um arquivo por família: matomo, seo, kimai…
└── wrangler.toml # o binding do KV e a lista dos segredosRepare no arkad-documents: nenhum .mcp.json. São só instruções e modelos, não toca em sistema nenhum — e por isso não custa nada em contexto até ser invocado.
Um sócio adiciona o marketplace uma vez e instala o plugin. Daí em diante o ciclo é este: eu altero uma Skill, corrijo o código e faço push no GitHub. Ele roda a atualização e está com a última versão. Todas as Skills, o conector, tudo junto. Sem que eu mande nada para ele.
O número de versão não é etiqueta decorativa: é por ele que o Claude Code entende que há algo novo para baixar.
E como está tudo no Git, fica o histórico das alterações. Dá para ver quem mudou o quê.
Últimos dois obstáculos derrubados juntos.
Depois de alguns meses de uso real, o efeito composto é este: ninguém mais pergunta como é que você configurou o seu?. A pergunta deixou de fazer sentido.
E largamos também o outro hábito: mandar arquivo por WhatsApp, porque é ali que a gente conversa. Um baixava, o outro não. Três semanas depois, o que não tinha baixado escrevia dizendo que o download havia expirado e que precisava de novo — e nesse meio-tempo você já estava na versão seis.
O plugin é um, a versão é uma, as credenciais são de cada um, as Skills são escritas uma vez só e o agente sabe usar as ferramentas do jeito certo sem que ninguém explique nada.
MCP não morreu: o custo real de contexto
Chega então a objeção. E chega sempre com certa segurança: MCP morreu, consome contexto, hoje se usa Skills.
Tem um fundo de verdade. Um conector carrega as descrições das ferramentas na janela de contexto na inicialização. Sempre, usando você ou não. Uma Skill só é carregada quando serve. Nisso, quem diz tem razão.
Mas daí a dizer que morreu vai uma distância.
O consumo de contexto é consequência de como você escreve as descrições. O truque está inteiro aí.
Mantenha as descrições das ferramentas MCP no mínimo indispensável: o que a função faz, quais parâmetros quer, ponto. Todo o resto — quando convém usar, em que ordem, como se lê o resultado, quais erros são normais — vai para uma Skill do mesmo plugin, carregada só no momento em que realmente serve.
Feito assim, nos meus plugins o peso em contexto fica em torno de 1%. Você pode medir sozinho com um simples /context no Claude Code.
1% para ter acesso direto aos meus sistemas de qualquer ambiente não é preço. É arredondamento.
O que vale para nós três, e o que vai mudar
Uma última coisa, porque não quero vender essa arquitetura por mais do que ela é.
GitHub não é a resposta. É a nossa resposta.
Escolhemos por um motivo banal: somos três, todos já tínhamos conta no GitHub e uma organização nossa onde ficam os projetos, então não havia nada para criar nem nada para explicar. Mas o servidor na Cloudflare se configura exatamente do mesmo jeito com Google, ou com qualquer outro provedor de identidade que a empresa já use.
O padrão não é "usem GitHub". O padrão é: apoiem-se no cadastro que vocês já têm, seja qual for. No dia em que entrar uma pessoa que não escreve código, ou em que essa arquitetura for para a casa de um cliente não técnico, GitHub é a escolha errada e Google Workspace é a certa. Muda o fornecedor, não muda o desenho.
E existe um limite honesto a declarar.
Hoje temos todos permissões idênticas: qualquer um de nós pode usar qualquer ferramenta. Então o servidor precisa saber uma coisa só, quem é você, e ele sabe. Basta e sobra.
No dia em que dermos acesso a um funcionário, não bastará mais. Vai ser preciso definir papéis no servidor, associar cada papel a um conjunto de ferramentas e atribuir um papel a quem se conecta conforme a posição dele na organização. Quem tem o papel certo enxerga aquela ferramenta, os outros não.
As coisas vão se complicar. Não escondo.
Mas é um problema que teremos quando tivermos. Enquanto isso, essa solução mudou a nossa vida de verdade, e nesse campo tudo se move tão rápido que a única promessa sensata é essa: quando for preciso mudar, mudamos.
Em resumo
- Skills são fáceis de escrever e impossíveis de manter sincronizadas na mão em três cópias.
- Skills e conectores MCP não são a mesma coisa: as primeiras instruem, os segundos agem. Mantê-los separados é o que faz o contexto respirar.
- Um conector remoto é visto do mesmo jeito pelo Claude Code, pelo Cowork e pelas tarefas agendadas, porque não vive em nenhum dos três.
- Os segredos ficam criptografados no servidor, num ponto só. Cada um se autentica por conta própria.
- Com a autenticação via organização do GitHub você ganha duas coisas juntas: fica de fora quem não é do time, e o servidor sabe o nome de quem está chamando. Acabaram as chaves de API uma por sócio.
- Um marketplace no GitHub leva cada atualização ao time inteiro com um comando, e guarda o histórico de quem mudou o quê.
- MCP não morreu. Num plugin bem cuidado custa cerca de 1% da janela de contexto, e compra a única coisa que as Skills sozinhas não dão: a capacidade de agir.
- GitHub é a nossa instância do padrão, não o padrão: no lugar dele serve Google ou qualquer cadastro corporativo já existente. E enquanto as permissões forem idênticas para todos, basta a identidade; com um funcionário, vão ser precisos os papéis.
É uma tarde de trabalho. São duas contas gratuitas.
E depois não tem mais volta.
Boa tarde, então. Até breve 👋
A Arkad Consulting ajuda times e empresas a colocar IA em produção sem enrolação: de agentes internos a plugins Claude Code compartilhados. Vamos conversar.
Artigo escrito por Fabrizio Scanavini para Arkad Consulting. Agosto de 2026.