Guia de Skills: como configurar Claude Code, Codex e Gemini sem se perder

Skills, extensões e Gems parecem a mesma coisa à primeira vista: uma forma de ensinar um assistente de IA a repetir um trabalho. Na prática, cada produto usa uma estrutura diferente, tem permissões diferentes e exige cuidados diferentes. Este guia organiza o caminho para criar ou instalar configurações reutilizáveis sem transformar um repositório aleatório em algo que roda com acesso ao seu computador.

O objetivo aqui não é decorar comandos. É saber onde está cada tipo de configuração, como testar com pouco risco e como manter uma versão que outra pessoa consiga entender depois. Os passos foram conferidos nas documentações oficiais listadas ao fim.

Antes de começar: descubra o que você está instalando

Uma skill normalmente é um pacote de orientações, e às vezes exemplos, scripts e arquivos de apoio, para repetir um fluxo. Uma extensão de linha de comando pode incluir uma skill, mas também pode trazer comandos, servidores MCP, hooks e configuração. Já uma Gem é um conjunto de instruções salvo dentro do Gemini Apps.

Essa diferença muda a revisão de segurança. Um arquivo de instruções em Markdown não tem o mesmo impacto de uma extensão que declara um servidor MCP ou pede uma chave de API. Antes de instalar qualquer item externo, abra os arquivos, identifique o mantenedor, confira a licença e leia quais permissões, comandos e variáveis de ambiente ele solicita. A checagem automática de uma plataforma ajuda, mas não substitui sua análise.

Claude Code: onde guardar e como chamar uma skill

No Claude Code, uma skill é organizada em uma pasta que contém um arquivo SKILL.md. A documentação separa três escopos: pessoal, de projeto e de plugin. A escolha é importante: uma skill pessoal acompanha seus projetos; uma skill de projeto deve viajar com o repositório e ser revisada junto com ele; uma skill de plugin faz parte de um pacote que pode incluir outras capacidades.

Estrutura mínima

minha-skill/
└── SKILL.md

O arquivo começa com um bloco de metadados em YAML e continua com as instruções em Markdown. Para uma primeira versão, mantenha-o curto e específico. A descrição serve para o produto entender quando aquela skill faz sentido; o restante deve deixar claro o resultado esperado, entradas, limites e passos de validação.

---
name: revisar-fontes
description: Organiza fontes primárias e aponta lacunas antes da publicação.
---

## Objetivo
Revisar uma pauta sem inventar dados.

## Processo
1. Separar fonte primária de fonte secundária.
2. Registrar links e a data de consulta.
3. Indicar o que ainda não foi confirmado.

## Limites
Não publicar nem afirmar números sem fonte acessível.

Como testar sem perder o controle

1. Crie a pasta no escopo que faz sentido para você. Para uma skill pessoal, a documentação do Claude Code indica ~/.claude/skills/<nome>/SKILL.md; para um projeto, o caminho é .claude/skills/<nome>/SKILL.md.
2. Escreva primeiro uma tarefa pequena, sem comandos destrutivos e sem acesso a credenciais.
3. Abra o Claude Code no projeto de teste e invoque a skill pelo nome, ou faça um pedido que corresponda à descrição.
4. Revise a resposta. Se ela ficou vaga, não aumente o arquivo de uma vez: melhore a descrição, o objetivo e um critério de aceitação.
5. Quando a skill for compartilhada, inclua uma licença e descreva requisitos e riscos. Isso evita que outra pessoa instale algo sem saber o que precisa preparar.

O ponto que costuma confundir é a precedência: o Claude Code documenta que configurações em escopos diferentes podem se sobrepor. Evite reutilizar o mesmo nome para skills que fazem trabalhos diferentes. Um nome explícito reduz a chance de chamar a versão errada.

Quando parar: se a skill pede para liberar ferramentas, executar scripts baixados ou ler diretórios que não fazem parte do objetivo, interrompa e revise os arquivos de apoio antes de continuar.

Codex: como estruturar uma skill reutilizável

Skills no ecossistema OpenAI são fluxos reutilizáveis que podem reunir instruções, exemplos e código. A documentação oficial informa que o formato segue o padrão aberto Agent Skills, o que ajuda na portabilidade, mas não garante que todos os campos ou recursos se comportem igual em cada produto. Por isso, uma boa skill começa por texto claro e só ganha automações quando elas forem realmente necessárias.

Um roteiro que outra pessoa consegue usar

Em vez de montar uma skill como uma lista longa de preferências, divida-a em cinco partes:

• Gatilho: em que tipo de pedido ela deve ser usada.
• Entrada: quais informações mínimas precisa receber.
• Execução: etapas concretas, em ordem.
• Validação: como saber se o resultado está completo.
• Limites: o que ela nunca pode inventar, publicar ou alterar sem aprovação.

---
name: briefing-de-conteudo
description: Cria um briefing verificável para uma pauta editorial.
license: MIT
compatibility: Requer acesso a fontes públicas e revisão humana.
---

## Entrada mínima
- tema
- público
- objetivo da peça

## Entrega
1. Ângulo editorial
2. Fontes a consultar
3. Riscos e dúvidas abertas
4. Rascunho de estrutura

## Não faça
- não crie citações;
- não publique;
- não trate rumor como fato.

Depois de criar, instale ou envie a skill somente pela interface permitida pela sua conta e pelo seu ambiente. A documentação do OpenAI orienta revisar arquivos de uma skill antes do upload, especialmente quando ela veio de outra organização: uma skill pode conter instruções, recursos de apoio e código. Esse cuidado vale mesmo quando a página de instalação informa que uma verificação foi concluída.

Teste de aceitação em três perguntas

1. Uma pessoa nova consegue entender a finalidade lendo apenas a descrição?
2. O resultado tem formato verificável, e não apenas “faça o melhor possível”?
3. Há uma regra clara para parar quando faltar fonte, permissão ou contexto?

Se a resposta for “não” em qualquer uma delas, ajuste o arquivo antes de compartilhar. Isso é mais útil do que transformar a skill em um prompt gigante.

Gemini CLI: como instalar e administrar extensões

No Gemini CLI, extensões podem agrupar prompts, servidores MCP, comandos personalizados, temas, hooks, subagentes e agent skills. É um escopo maior que o de um simples arquivo de instruções; portanto, a revisão precisa começar antes do comando de instalação.

Checklist antes do comando

• Confirme se o repositório é do mantenedor esperado e se há histórico público de alterações.
• Abra o gemini-extension.json. Procure servidores MCP, comandos executáveis, hooks e variáveis de ambiente.
• Evite o argumento que pula confirmações enquanto ainda estiver avaliando a extensão.
• Prefira uma tag ou commit específico quando a procedência exigir reprodutibilidade.

Instalar, conferir e manter

# confira o que já está instalado
gemini extensions list

# instale a partir de uma origem que você revisou
gemini extensions install <URL-do-repositorio-ou-pasta-local>

# atualize uma extensão conhecida
gemini extensions update <nome>

# remova quando não precisar mais
gemini extensions uninstall <nome>

Os comandos de instalação e atualização são executados no terminal, não dentro do modo interativo do CLI. Depois de alterações, reinicie a sessão para que o Gemini CLI recarregue as configurações. A documentação também explica que extensões instaladas a partir do GitHub exigem Git no computador e que a instalação cria uma cópia local; atualizações não chegam sozinhas a menos que você as solicite ou tenha configurado esse comportamento conscientemente.

Para desativar temporariamente, use gemini extensions disable <nome> --scope user ou escolha o escopo de workspace quando o objetivo for só aquele projeto. Essa é uma alternativa mais segura que apagar arquivos no impulso quando você está investigando um problema.

Gemini Apps: como criar uma Gem com instruções claras

Uma Gem é diferente de uma extensão: ela é uma configuração reutilizável criada dentro do Gemini Apps. A criação começa em Explorar Gems e depois Nova Gem. Dê um nome, escreva as instruções, use o painel de prévia para testar e salve quando estiver satisfeito. A prévia não salva a Gem automaticamente.

Modelo de instrução que funciona melhor

A orientação oficial do Gemini organiza instruções em quatro blocos. Você não precisa usar todos em toda Gem, mas esse formato reduz respostas inconsistentes:

• Persona: qual papel a Gem deve assumir e qual tom deve evitar.
• Tarefa: o que ela deve produzir ou analisar.
• Contexto: informações que não podem ser presumidas.
• Formato: como a resposta precisa chegar.

Você é uma revisora de briefing editorial.

Tarefa: organize a pauta em fatos confirmados, dúvidas e próximos passos.
Contexto: o texto será lido por uma pessoa responsável pela publicação.
Formato:
- resumo de até cinco linhas;
- fontes e links;
- lacunas de confirmação;
- nenhuma citação inventada.

Como revisar antes de salvar

1. Teste com um pedido claro e outro deliberadamente incompleto.
2. Veja se a Gem pede informação quando faltam dados, em vez de completar lacunas por conta própria.
3. Se você anexar arquivos para contexto, envie somente o que a tarefa precisa e revise se contêm dados pessoais, credenciais ou informações internas.
4. Salve a versão que passou no teste e registre a data da revisão em uma nota sua.

O que muda de um ecossistema para outro

Uma rotina curta para não se perder

Guarde a fonte original, o nome do mantenedor e a data da última revisão em um lugar simples. Quando for atualizar, compare o manifesto, as permissões e os arquivos executáveis, não só a descrição da página. E, se uma configuração deixou de fazer sentido, desative-a antes de substituí-la. Uma coleção menor, compreendida e revisada é muito mais útil do que dezenas de downloads que ninguém consegue auditar.

Fontes oficiais consultadas

• Claude Code Docs, Extend Claude with skills
• OpenAI Help, Skills no ChatGPT
• Gemini CLI, Extensions
• Gemini CLI, Extension reference
• Gemini Apps Help, Tips para criar Gems personalizadas

Última checagem editorial: 10 de agosto de 2026. Interfaces e comandos podem mudar; quando houver divergência, a documentação oficial mais recente prevalece.