Skip to main content
Todos os guias
Conteúdo do guia

Conteúdo do guia

Tempo de leitura: 15 min
#ai_agents#codex#plugins#skills#mcp#marketplace
Intermediário15 min

Codex Plugins para iniciantes: o que substituiu as Skills tradicionais

Guia abrangente sobre o ecossistema de plugins no Codex: diferenças entre Skills e Plugins, conexão com Marketplaces, instalação via GUI e CLI, integração de servidores MCP e desenvolvimento de plugins personalizados.

Publicado:
PARA AGENTE DE IAChatGPTClaude

1. Evolução do ecossistema: de Skills básicas a Plugins modulares

Nos estágios iniciais do trabalho com ambientes autônomos de desenvolvimento, a principal ferramenta para configurar o comportamento do agente de IA eram as Skills — pastas isoladas contendo instruções em formato Markdown (SKILL.md), que explicavam ao modelo como executar tarefas específicas: realizar code reviews seguindo padrões da equipe, otimizar bancos de dados ou gerar documentação.

As Skills permanecem como a unidade fundamental de conhecimento; no entanto, sua cópia manual entre repositórios, a ausência de gerenciamento padronizado de dependências e a impossibilidade de fornecer ferramentas executáveis junto às instruções levaram ao surgimento de um ecossistema modular completo — os Codex Plugins e os catálogos de Marketplaces.

mermaid
flowchart TD subgraph Distribution ["Рівень дистрибуції"] M["Marketplace (Git-репо або локальний каталог)"] end subgraph Packaging ["Рівень пакетування: Plugin"] P["Codex Plugin"] P --> S["Skills (Інструкції та експертиза)"] P --> T["MCP Tools (Зовнішні API: GitHub, Slack, Figma)"] P --> H["Hooks (Автоматичні тригери подій)"] P --> C["Config (Маніфест plugin.json)"] end subgraph Execution ["Рівень виконання"] Session["Нова робоча сесія Codex"] end M -->|codex plugin add| P P -->|Ініціалізація розширень| Session

Comparação de arquitetura: Skill vs. Plugin

CaracterísticaSkill BásicaPlugin Modular
Propósito principalDescrever regras e processos passo a passo para uma tarefa específicaPacote completo de extensão do ambiente do agente
Composição do pacoteArquivo de texto SKILL.md + arquivos de referência adicionaisConjunto de Skills, servidores MCP, hooks de ciclo de vida, configuração
Integrações externasNão suporta conexão com APIs de serviços de terceirosIntegra serviços externos via protocolo MCP (Model Context Protocol)
DistribuiçãoCópia manual de arquivos para o diretório de trabalho do projetoInstalação com um único comando ou clique através dos Marketplaces
AtualizaçãoSubstituição manual de arquivos pelo usuárioAtualização automática via CLI ou catálogo de extensões
Nota

A analogia mais precisa: Skills são funções individuais de biblioteca, enquanto Plugins são pacotes prontos (módulos npm). Se você precisa apenas de uma instrução breve para seu próprio projeto, uma Skill comum é suficiente. Se deseja fornecer ao modelo ferramentas de interação com GitHub, Slack ou Figma, junto com cenários prontos de uso, escolha um Plugin.

2. Anatomia de um plugin: Skills, servidores MCP, configurações e hooks

Um plugin no Codex não é apenas um grande prompt de sistema. É um catálogo estruturado ou arquivo compactado que contém um manifesto declarativo e todos os artefatos executáveis necessários.

text
my-awesome-plugin/ ├── .codex-plugin/ │ └── plugin.json # Manifesto obrigatório do plugin ├── skills/ │ ├── code-review/ │ │ └── SKILL.md # Primeira habilidade integrada │ └── perf-audit/ │ └── SKILL.md # Segunda habilidade integrada ├── mcp/ │ └── server-config.json # Configuração de conexão do servidor MCP └── README.md # Documentação para desenvolvedores

Componentes de um plugin moderno

  1. Manifesto (.codex-plugin/plugin.json): O arquivo de configuração principal, que define o identificador único do plugin, sua versão, autor, dependências e pontos de entrada.
  2. Conjunto de skills (skills/): Um ou mais diretórios contendo arquivos SKILL.md, que ensinam ao Codex abordagens especializadas para a base de código.
  3. Servidores MCP (Model Context Protocol): Servidores executáveis ou adaptadores que fornecem novas ferramentas ao agente — por exemplo, a capacidade de ler pull requests no GitHub, criar tarefas no Linear ou carregar mockups de design do Figma.
  4. Hooks de ciclo de vida (Lifecycle Hooks): Scripts ou comandos que são executados automaticamente quando certos eventos ocorrem na sessão (por exemplo, verificação com linter antes da criação de um commit).
json
{ "name": "developer-toolkit", "version": "1.2.0", "description": "Розширений набір інструментів для аудиту коду та автоматизації GitHub", "author": "Engineering Team", "skills": [ "./skills/code-review", "./skills/perf-audit" ], "mcpServers": { "github-connector": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }
Importante

Diferentemente dos prompts comuns, os plugins podem expandir diretamente as capacidades técnicas do agente (tooling capability). Sem um plugin com servidor MCP, o agente apenas raciocina sobre o trabalho com o GitHub; com o plugin conectado, ele recebe comandos nativos para chamar a API do GitHub.

3. O que são Marketplaces: catálogos de extensões e fontes de distribuição

Para busca, validação e distribuição centralizada de plugins, o Codex utiliza o conceito de Marketplaces (catálogos de extensões).

Um Marketplace é um registro ou repositório que contém a lista de plugins disponíveis, seus metadados e endereços de origem para download. Em vez de baixar manualmente arquivos de sites não confiáveis, o desenvolvedor conecta um marketplace verificado e instala os pacotes desejados usando seus identificadores curtos.

mermaid
flowchart LR subgraph Sources ["Джерела каталогів"] Official["Офіційний реєстр OpenAI"] Community["Публічний GitHub-каталог"] Private["Внутрішній GitLab компанії"] Local["Локальна папка розробника"] end subgraph Client ["Клієнтське середовище Codex"] Reg["Менеджер Marketplaces"] Reg --> P1["Plugin: GitHub Sync"] Reg --> P2["Plugin: PostgreSQL Inspector"] Reg --> P3["Plugin: Team Styleguide"] end Official --> Reg Community --> Reg Private --> Reg Local --> Reg

Tipos de marketplaces suportados

  • Catálogo público oficial: Registro embutido, disponível por padrão para todos os usuários do Codex. Contém plugins verificados para serviços populares (Figma, Notion, Google Workspace, GitHub).
  • Repositórios Git da comunidade: Qualquer repositório público ou privado no GitHub ou GitLab, formatado conforme a especificação do marketplace.
  • Registros corporativos internos: Catálogos da empresa onde são armazenados plugins fechados para trabalhar com microsserviços internos, VPN e sistemas de compliance.
  • Diretórios locais de desenvolvimento: Diretórios locais comuns no seu computador, usados para desenvolver e testar novos plugins antes de sua publicação.

4. Trabalho através da interface gráfica: comando /plugins e gerenciamento

Para a maioria dos cenários diários de interação, o desenvolvedor não precisa usar longos comandos de terminal — o Codex oferece um navegador gráfico integrado conveniente para gerenciar plugins.

Chamando o catálogo gráfico

Para abrir a interface de gerenciamento de plugins, digite o comando slash na barra de diálogo da sessão ativa do Codex:

bash
/plugins

Após inserir o comando, aparecerá na tela um gerenciador visual, onde você pode:

  • Visualizar plugins instalados: Ver a lista de todas as extensões ativas no sistema e seu status atual.
  • Buscar novas extensões: Usar a barra de pesquisa para encontrar plugins por nome, tags ou categorias (Development, DevOps, Analytics, Design).
  • Alternar entre marketplaces: Filtrar os plugins disponíveis por catálogos conectados específicos.
  • Gerenciar atividade: Habilitar (Enable) ou desabilitar temporariamente (Disable) plugins com um clique, sem removê-los completamente.
Aviso

Regra da nova sessão: Após instalar um novo plugin ou habilitar uma extensão desativada, suas ferramentas e skills tornam-se disponíveis apenas em novas sessões de trabalho. A sessão atual mantém seu estado inicial de execução, portanto, abra obrigatoriamente um novo diálogo após alterar a configuração dos plugins.

5. Gerenciamento de plugins via CLI: listagem, instalação e remoção

Para usuários que preferem o terminal, bem como para automatizar a configuração do ambiente em CI/CD ou containers Docker, o Codex oferece um conjunto completo de comandos CLI sob o subgrupo codex plugin.

Operações básicas com plugins

O comando codex plugin list exibe o status de cada plugin: nome, versão, fonte de instalação, além do estado habilitado/desabilitado.

6. Gerenciamento de Marketplaces: adicionar repositórios, atualizar e remover

Para expandir a lista de plugins disponíveis, o desenvolvedor pode conectar fontes externas usando os subcomandos codex plugin marketplace.

Visualizar catálogos conectados

bash
codex plugin marketplace list

O comando exibe o nome de cada catálogo, o tipo de fonte (git ou local) e o URI atual.

Adicionar novas fontes

O Codex suporta vários formatos de link para marketplaces, dependendo do ambiente e do protocolo de acesso:

Atualizar e remover marketplaces

bash
# Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів) codex plugin marketplace upgrade community-plugins # Оновити всі підключені Git-маркетплейси одночасно codex plugin marketplace upgrade # Видалити маркетплейс зі списку джерел codex plugin marketplace remove community-plugins
Dica

Se um plugin não encontra atualizações ou um pacote recém-publicado pelos colegas não aparece na sua lista, execute codex plugin marketplace upgrade para atualizar o índice local dos catálogos.

7. Plugins com servidores MCP: autorização, permissões e segurança

Quando um plugin instalado contém um servidor MCP, ele ganha a capacidade de interagir com sistemas externos (bancos de dados, armazenamento em nuvem, endpoints de API). Isso transforma o Codex de um gerador passivo de código em um executor ativo de tarefas.

mermaid
sequenceDiagram autonumber actor Dev as Інженер participant Codex as Codex Session participant Plugin as Plugin (MCP Adapter) participant Cloud as Зовнішній сервіс (GitHub API) Dev->>Codex: "Створи issue з результатами аудиту" Codex->>Plugin: Виклик інструменту create_issue() alt Потрібна авторизація Plugin-->>Dev: Запит OAuth-авторизації або токена Dev->>Plugin: Підтвердження облікового запису end Plugin->>Cloud: POST /repos/:owner/:repo/issues Cloud-->>Plugin: HTTP 201 Created (Issue #42) Plugin-->>Codex: Результат виконання з посиланням Codex-->>Dev: "Issue #42 успішно створено!"

Particularidades da autorização de serviços externos

  1. Autenticação OAuth: A maioria dos serviços em nuvem (Google Drive, Slack, GitHub) abrirá uma janela do navegador durante a primeira solicitação, exigindo confirmação de acesso à sua conta.
  2. Tokens de API no ambiente: Para serviços de banco de dados ou servidores internos (PostgreSQL, Supabase), os tokens de acesso são lidos das variáveis de ambiente (.env) ou da configuração global do Codex.
  3. Permissões granulares (Permissions): O Codex sempre solicita confirmação do usuário antes de executar ações potencialmente destrutivas (excluir registros no banco, enviar mensagens, fechar pull request).
Aviso

Segurança dos servidores MCP: Nunca instale plugins de marketplaces duvidosos se eles contiverem servidores MCP. Um servidor MCP malicioso pode acessar seus arquivos locais ou enviar chaves de API confidenciais para servidores externos. Sempre analise o código-fonte antes da instalação.

Iniciantes frequentemente confundem três níveis distintos de desativação de extensões: desativação temporária, remoção completa do plugin e desconexão do marketplace.

AçãoComandoO que acontece com os arquivosConsequências para as sessões
Desativar plugin (Disable)Via interruptor /pluginsO plugin permanece no disco, a configuração é preservadaSkills e ferramentas MCP ficam inativas em novas sessões
Remover plugin (Uninstall)codex plugin remove <name>Todos os arquivos do plugin são excluídos do ambiente localLimpeza completa; para reutilização, é necessário novo download
Remover marketplacecodex plugin marketplace remove <name>Apenas a fonte é removida; plugins já instalados permanecemImpossível atualizar ou instalar novos plugins deste catálogo

Recomendações para escolher a ação

  • Se o plugin causa conflitos ou você não precisa temporariamente de suas ferramentas MCP pesadas — desative-o (Disable) via /plugins.
  • Se você concluiu o projeto e não planeja mais trabalhar com essa tecnologia — remova completamente o plugin (Remove) via CLI.
  • Se o repositório do desenvolvedor terceiro ficou inativo ou obsoleto — remova o marketplace (Marketplace Remove).

9. Desenvolvimento do seu próprio Plugin: manifesto, empacotamento de Skills e teste local

Criar seu próprio plugin é a melhor maneira de padronizar fluxos de trabalho na sua equipe e garantir um nível uniforme de geração de código para todos os engenheiros.

Fluxo de trabalho passo a passo para criar um plugin

Passo 1. Preparação do workspace

Crie um diretório limpo para seu futuro plugin:

bash
mkdir -p my-team-plugin/.codex-plugin mkdir -p my-team-plugin/skills/architecture-review

Passo 2. Criar o manifesto plugin.json

Dentro do diretório .codex-plugin/, crie o arquivo plugin.json:

json
{ "name": "team-architecture-plugin", "version": "1.0.0", "description": "Фірмові правила проєктування сервісів та аудит чистої архітектури", "author": "Architecture Guild", "skills": [ "./skills/architecture-review" ] }

Passo 3. Adicionar instruções em SKILL.md

Crie o arquivo my-team-plugin/skills/architecture-review/SKILL.md:

markdown
--- name: architecture-review description: Verificação da conformidade dos módulos com os princípios do Domain-Driven Design (DDD) --- Ao analisar novos módulos de arquitetura, verifique as seguintes regras: 1. A lógica de negócio não deve importar diretamente o ORM ou o banco de dados. 2. Todas as interfaces externas devem ser definidas como portas (interfaces) na camada interna. 3. Cada mutação de dados deve ser acompanhada pela emissão de eventos de domínio (domain events).

Passo 4. Criar um marketplace de teste e instalar

Para verificar o funcionamento localmente sem publicar no GitHub, crie a pasta do marketplace local local-market/ e adicione seu plugin nela. Depois, execute:

bash
# Підключаємо локальну папку як джерело маркетплейсу codex plugin marketplace add ./local-market # Встановлюємо наш щойно створений плагін codex plugin add team-architecture-plugin # Перевіряємо статус встановлення codex plugin list

Agora, inicie uma nova sessão no Codex e teste o funcionamento do plugin conectado em uma tarefa real de arquitetura de código.

10. Resumo rápido de comandos e checklist de segurança antes da instalação

Salve este guia consolidado para navegação rápida no terminal e durante o trabalho diário.

Guia rápido de comandos CLI

bash
# ─── Робота з плагінами ─────────────────────────────────────────── codex plugin list # Список встановлених плагінів codex plugin list --available # Список доступних плагінів у каталогах codex plugin add <plugin-name> # Встановити плагін codex plugin add <plugin@marketplace> # Встановити з конкретного джерела codex plugin remove <plugin-name> # Видалити плагін # ─── Робота з Marketplaces ──────────────────────────────────────── codex plugin marketplace list # Список підключених каталогів codex plugin marketplace add <source> # Додати маркетплейс (GitHub / URL / локальний) codex plugin marketplace upgrade <name> # Оновити конкретний каталог codex plugin marketplace upgrade # Оновити всі підключені каталоги codex plugin marketplace remove <name> # Видалити каталог зі списку # ─── Графічний інтерфейс ───────────────────────────────────────── /plugins # Відкрити інтерактивний браузер плагінів

Checklist de segurança antes de instalar um plugin de terceiros

  • Reputação da fonte: O repositório do marketplace pertence a um vendor oficial ou a uma comunidade open-source respeitada.
  • Auditoria do manifesto: No plugin.json, não há comandos executáveis suspeitos ou dependências binárias incompreensíveis.
  • Verificação de endereços de rede MCP: Se o plugin contém um servidor MCP, suas requisições de rede são direcionadas exclusivamente aos endereços oficiais do serviço alvo.
  • Minimização de conflitos: As skills do plugin não duplicam nem sobrescrevem regras já instaladas do ambiente de trabalho.
  • Teste em nova sessão: O funcionamento do plugin foi verificado em uma tarefa isolada de teste antes do uso em repositórios de produção.
Este guia é totalmente gratuito. Se ele te poupou uma noite, você pode apoiar o crescimento do projeto.
Apoiar o autor