O Codex oferece três formas de estender um agente: skills, que carregam o seu processo; servidores MCP, que alcançam sistemas em tempo real; e plugins, que reúnem os dois para uma equipe. Este artigo mostra como cada um fica no disco, quanto custa em contexto e como escolher entre eles.
Abra o navegador de plugins do Codex e você verá skills, servidores MCP e plugins listados lado a lado, como se fossem três versões da mesma coisa. Não são. Misturá-los é o que leva as pessoas a escrever um arquivo de instruções de 400 linhas quando precisavam de um conector de dez linhas, ou a configurar um servidor quando uma lista de verificação de uma página resolveria o trabalho.
Aqui vai a versão curta antes dos detalhes. Uma skill ensina o Codex a fazer um trabalho. Um servidor MCP dá ao Codex acesso em tempo real a uma ferramenta ou a uma fonte de dados. Um plugin é a caixa que reúne skills, servidores e conexões com apps, para que outra pessoa instale tudo em um único passo. O restante deste artigo mostra como cada um fica no disco, quanto custa em contexto, onde falha e como escolher o certo para o seu próprio trabalho.
Três objetos sobre uma mesma bancada tornam a divisão fácil de lembrar. A chave é uma ferramenta que você pega. O fichário diz como executar um trabalho. A caixa é um pacote que alguém montou para ser entregue a um colega.
SKILL.md que diz ao Codex quando e como executar um fluxo de trabalho repetível.Nenhum deles substitui os outros. Um plugin não é um quarto tipo de capacidade. É o empacotamento das duas primeiras, mais conexões com apps, com um número de versão anexado.
Uma skill é uma ficha de receita: passos em ordem, quantidades e a descrição do que significa "pronto". Um servidor MCP é um eletrodoméstico ligado na parede: faz coisas que o cozinheiro não consegue fazer à mão, como bater ou refrigerar. Um plugin é o kit de refeição: a ficha, os ingredientes e uma nota sobre qual eletrodoméstico você precisa, tudo em uma só caixa.
💡 Regra prática: se o problema é "o Codex não conhece o nosso processo", escreva uma skill. Se é "o Codex não consegue acessar aquele sistema", adicione um servidor MCP. Se é "os colegas vivem me perguntando como eu configurei isso", crie um plugin.
O Model Context Protocol é um padrão aberto, apresentado pela Anthropic no fim de 2024, que permite a um cliente de IA conversar com ferramentas externas por meio de uma interface comum. O Codex faz o papel de cliente. O servidor é aquilo para que você o apontar: um conector do GitHub, uma ponte para banco de dados, uma busca em documentação, um gerador de imagens.
Um servidor MCP responde a uma pergunta: o que você pode fazer agora, e com quais dados? Ele lista ferramentas com nomes, descrições e esquemas de entrada. Quando o Codex decide que uma ferramenta serve para a tarefa, ele a chama e lê o resultado. Nada no servidor diz como a sua equipe prefere usá-la. Um servidor de banco de dados executa qualquer consulta que você permitir, mas não vai dizer ao Codex que ninguém mexe nas tabelas de cobrança numa sexta-feira à tarde.
Essa lacuna é o motivo pelo qual servidores e skills combinam tão bem. O servidor fornece o alcance. A skill fornece o discernimento.
O Codex guarda as configurações do MCP em ~/.codex/config.toml, com configurações de escopo de projeto possíveis em .codex/config.toml. Um servidor local que o próprio Codex inicia (STDIO) fica assim:
[mcp_servers.docs]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
Um servidor remoto por streamable HTTP usa uma URL no lugar:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
Você também pode executar codex mcp add <name> -- <command> para escrever a entrada por você, codex mcp list para ver o que está configurado e codex mcp login <server-name> para executar o OAuth em servidores que o exigem.
Algumas configurações merecem atenção. startup_timeout_sec tem como padrão 10 segundos, o que pode ser pouco para um download lento da primeira npx. tool_timeout_sec tem como padrão 60 segundos, o que vai interromper trabalhos longos, como a renderização de um vídeo. enabled_tools e disabled_tools permitem reduzir um servidor apenas às chamadas que você realmente quer que o agente veja.
Os custos do MCP são reais. Cada servidor conectado acrescenta definições de ferramentas que o modelo precisa carregar, um processo ou um salto de rede que pode falhar e uma nova fronteira de confiança. Um servidor que pode escrever no seu repositório também pode escrever algo que você não pretendia.
Uma skill é uma pasta. Dentro dela há um arquivo SKILL.md que começa com um cabeçalho curto em YAML, delimitado por duas linhas de cerca no topo do arquivo. O cabeçalho traz um name e uma description:
name: release-notes
description: Use when the user asks for release notes or a changelog built from merged pull requests. Do not use for commit message drafts.
Abaixo do cabeçalho, as instruções são markdown simples:
1. List the pull requests merged since the last tag.
2. Group them under Added, Changed and Fixed.
3. Write one plain sentence per item.
4. Save the result to docs/releases/<version>.md.
A pasta também pode conter scripts, documentos de referência, modelos e recursos para os quais as instruções apontam. O Codex procura skills em .agents/skills dentro do repositório (o diretório de trabalho, seus diretórios superiores e a raiz do repositório), em $HOME/.agents/skills para skills pessoais, em /etc/codex/skills para skills compartilhadas no computador inteiro e no conjunto embutido que vem com o Codex.
As skills usam divulgação progressiva. No início de uma sessão, o Codex vê apenas a lista de nomes e descrições das skills, e essa lista é limitada a cerca de 2% da janela de contexto (ou 8.000 caracteres quando o tamanho da janela é desconhecido). O SKILL.md completo só é carregado depois que uma skill é selecionada. Funciona como um catálogo de cartões: você lê as fichas até achar a gaveta certa e só então puxa o arquivo inteiro.
A consequência é prática. Você pode manter dezenas de skills instaladas sem pagar por todas elas a cada pedido. Também significa que a linha description faz o trabalho pesado. Uma descrição vaga, como "ajuda com documentação", nunca dispara. Uma descrição precisa, que diz quando usar a skill e quando deixá-la de lado, dispara de forma confiável.
Há duas formas de executar uma skill. Explícita: digite $release-notes na CLI do Codex ou na extensão para IDE (o ChatGPT usa @release-notes). Implícita: o Codex escolhe a skill por conta própria quando o seu pedido combina com a descrição. Um arquivo agents/openai.yaml opcional ajusta como a skill aparece na interface, sua política de invocação e as ferramentas de que ela depende.
💡 Se uma skill nunca é acionada sozinha, reescreva a descrição antes de reescrever as instruções. A descrição é o gatilho.
O suporte a plugins chegou ao Codex em março de 2026, e o lançamento inicial, com mais de 20 plugins, incluiu Box, Figma, Linear, Notion, Sentry, Slack, Gmail e Hugging Face. A razão de existirem os plugins é a distribuição. Uma skill pode ser copiada para uma pasta e um servidor pode ser colado em um arquivo de configuração, mas entregar os dois a dez colegas, com versões compatíveis, é trabalhoso e fácil de errar.
my-plugin/
plugin.json
mcp.json
skills/
release-notes/
SKILL.md
hooks/
assets/
scripts/
plugin.json na raiz é o manifesto, e .codex-plugin/plugin.json ainda funciona como alternativa. Ele traz o name em kebab case, uma version, uma description e os dados do autor. As skills ficam em skills/<skill-name>/SKILL.md e são encontradas nessa pasta sem precisar ser declaradas. Os servidores MCP ficam em mcp.json dentro de mcpServers, com "type": "streamable-http" para endpoints remotos. Os hooks executam comandos em pontos definidos do ciclo de vida.
Para testar localmente, adicione uma entrada cujo source.path aponte para a sua pasta em um arquivo de marketplace em ~/.agents/plugins/marketplace.json ou $REPO_ROOT/.agents/plugins/marketplace.json, e depois instale-o pelo diretório de plugins. O auxiliar @plugin-creator pode montar a pasta e a entrada do marketplace para você.
Na CLI do Codex, execute /plugins para abrir o navegador de plugins e instalar a partir dos marketplaces que você configurou. No aplicativo de desktop do ChatGPT ou na web, abra a aba Plugins, pesquise, clique no botão de mais e conecte qualquer serviço externo quando for solicitado. Depois disso, você pode pedir em linguagem natural ("Resuma os e-mails não lidos do Gmail de hoje") ou digitar @ seguido do nome do plugin para chamá-lo explicitamente.
Um plugin também acrescenta um manifesto, uma versão para manter e uma entrada de marketplace. Se você é a única pessoa que usa o fluxo de trabalho, uma skill em $HOME/.agents/skills e um bloco em config.toml fazem o mesmo trabalho com menos cerimônia.
💡 A documentação do Codex muda rápido. Os nomes de arquivos e comandos acima seguem as páginas da OpenAI sobre plugins, MCP e skills em outubro de 2026. Confira antes de construir.
| Skill | Servidor MCP | Plugin | |
|---|---|---|---|
| O que é | Pasta com SKILL.md | Ferramenta ou serviço de dados em execução | Pacote instalável |
| Dá ao Codex | Um procedimento | Alcance em tempo real e ações | Os dois, mais conexões com apps |
| Fica em | .agents/skills | config.toml | plugin.json e mcp.json |
| Carrega | Nome e descrição primeiro, corpo sob demanda | Definições de ferramentas na conexão | O que ele reúne |
| Precisa de código | Não | Sim, ou um servidor hospedado | Só se reunir um servidor |
| Melhor para | Processo repetível da equipe | Sistemas que o Codex não consegue acessar | Compartilhar uma configuração completa |
| Principal risco | Descrição vaga nunca dispara | Permissões amplas demais | Desvio de versão, servidores embutidos ocultos |
As skills são as mais baratas dos três, porque apenas uma descrição curta fica no contexto até que a skill seja necessária. Um servidor MCP é mais pesado: a lista de ferramentas é carregada na sessão, quer a tarefa a use ou não, então dez servidores tagarelas podem ocupar o espaço do trabalho real. Um plugin herda o custo de tudo o que há dentro dele.
Um hábito economiza muitos tokens. Antes de adicionar um servidor, pergunte-se se uma skill com um script curto poderia fazer o mesmo. Os scripts dentro de uma skill só rodam quando a skill roda. Um servidor fica conectado o tempo todo.
Uma skill é texto mais scripts opcionais, então seu perigo está nos comandos que as instruções mandam o Codex executar. Um servidor é um processo ativo com credenciais próprias, o que torna as permissões a principal preocupação. Restrinja-o com enabled_tools e disabled_tools, e use default_tools_approval_mode para decidir quanto o Codex pode fazer sem pedir permissão.
Um plugin pode reunir servidores, skills e hooks de uma vez, então abra a pasta plugin.json, a pasta mcp.json e a pasta de hooks antes de instalar um plugin de alguém que você não conhece. Guarde os tokens em variáveis de ambiente, do jeito que bearer_token_env_var espera, e nunca em um arquivo que você versiona.
AGENTS.md basta.Quando não tiver certeza, comece pela menor opção e suba. Comece com um prompt. Se você repetir três vezes, transforme-o em uma skill. Se a skill precisar de um sistema que o Codex não alcança, adicione um servidor. Se outras pessoas precisarem do mesmo conjunto, empacote tudo em um plugin.
Colocar o processo dentro de um servidor. As descrições de ferramentas servem para explicar o que uma ferramenta faz, não como a sua equipe trabalha. Um texto longo de política dentro de um servidor incha cada sessão. Mova-o para uma skill.
Reconstruir um conector com scripts de shell. Se já existe um servidor MCP mantido para o sistema que você quer, uma skill cheia de comandos curl vai demorar mais para escrever e será mais difícil de manter funcionando.
Empacotar cedo demais. Um plugin com um autor e um usuário é sobrecarga. Espere até que uma segunda pessoa peça a sua configuração.
Imagine uma pequena equipe de marketing que precisa de fotos consistentes para o blog. As três peças se separam com clareza. A skill, chamada brand-photos, guarda as regras: 16:9 para imagens de artigos, luz natural, nenhum texto dentro da imagem, um padrão de nome de arquivo e quem aprova o conjunto final. O servidor MCP faz a geração em si. O plugin entrega os dois a todos os colegas, para que ninguém precise editar um arquivo de configuração à mão.
A PicassoIA oferece uma API para desenvolvedores em api.picassoia.com/v1 e um conector MCP para seus modelos de imagem e vídeo, incluindo PicassoIA Image e PicassoIA Image Editor Pro. Isso torna a parte servidor deste padrão disponível hoje. Os detalhes da conexão ficam na sua conta, então confirme que o seu cliente oferece suporte ao conector antes de configurá-lo.
A skill então diz ao Codex como usar bem esse alcance: qual estrutura de prompt seguir, qual proporção pedir e quando parar e perguntar a um humano. O servidor nunca precisa saber nada disso.
Você não precisa escrever o primeiro SKILL.md à mão. Um modelo de programação como o GPT 5.6 Sol ou o Claude Sonnet 5 pode produzir um rascunho em segundos.
.agents/skills/brand-photos/SKILL.md.$brand-photos e um pedido real. Se o Codex não a encontrar sozinho, reforce a descrição e tente de novo.💡 Trate a saída do modelo como um primeiro rascunho. Uma skill só é tão boa quanto as verificações que você acrescenta depois de vê-la rodar em uma tarefa real.
Skills, servidores e plugins são mais fáceis de avaliar quando você os vê produzir algo. Abra a Picasso IA e recrie as fotos deste artigo: a mesa de carvalho de um desenvolvedor na hora dourada, um rolo de lona para ferramentas ao lado de uma pilha de fichas e uma caixa kraft embalada para envio. Comece com PicassoIA Image, mude um detalhe por vez, como a lente, a direção da luz ou a textura da superfície, e veja como a imagem muda.
Depois, pergunte o que a segunda execução precisou que a primeira não precisou. Era uma regra que você repetia? Essa é uma skill esperando para ser escrita. Era um sistema que você teve de abrir à mão? Isso é um servidor. Era uma configuração que você quer passar para um amigo? Isso é um plugin. Teste alguns prompts na Picasso IA hoje e deixe o seu próprio fluxo de trabalho dizer qual você precisa.
Escolha seu idioma
