# 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. ## 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ística | Skill Básica | Plugin Modular | | :--- | :--- | :--- | | **Propósito principal** | Descrever regras e processos passo a passo para uma tarefa específica | Pacote completo de extensão do ambiente do agente | | **Composição do pacote** | Arquivo de texto `SKILL.md` + arquivos de referência adicionais | Conjunto de Skills, servidores MCP, hooks de ciclo de vida, configuração | | **Integrações externas** | Não suporta conexão com APIs de serviços de terceiros | Integra serviços externos via protocolo MCP (Model Context Protocol) | | **Distribuição** | Cópia manual de arquivos para o diretório de trabalho do projeto | Instalação com um único comando ou clique através dos Marketplaces | | **Atualização** | Substituição manual de arquivos pelo usuário | Atualização automática via CLI ou catálogo de extensões | > [!NOTE] > 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"] } } } ``` > [!IMPORTANT] > 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. > [!WARNING] > **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 :::tabs @tab Visualizar instalados ```bash # Вивести перелік усіх встановлених на поточній машині плагінів codex plugin list ``` @tab Visualizar disponíveis ```bash # Переглянути список усіх плагінів, доступних у підключених маркетплейсах codex plugin list --available # Отримати детальний список у машиночитаному форматі JSON codex plugin list --available --json ``` @tab Instalar plugin ```bash # Встановити плагін за унікальним ім'ям codex plugin add github-toolkit # Встановити плагін із конкретного підключеного маркетплейсу codex plugin add dev-suite@company-internal ``` @tab Remover plugin ```bash # Повністю видалити встановлений плагін із системи codex plugin remove github-toolkit # Видалити плагін з прив'язкою до конкретного джерела codex plugin remove dev-suite@company-internal ``` ::: 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: :::tabs @tab Abreviação GitHub ```bash # Скорочений запис для публічних або доступних репозиторіїв GitHub (owner/repo) codex plugin marketplace add orlov-ai/community-plugins ``` @tab URL HTTPS Git ```bash # Стандартне підключення через HTTPS (підходить для публічних GitLab/Bitbucket) codex plugin marketplace add https://github.com/company/internal-codex-plugins.git ``` @tab URL SSH Git ```bash # Підключення через приватні SSH-ключі для закритих корпоративних репозиторіїв codex plugin marketplace add git@github.com:enterprise/secure-plugins.git ``` @tab Diretório local ```bash # Підключення локальної папки для тестування власного маркетплейсу codex plugin marketplace add ./my-local-marketplace ``` ::: ### Atualizar e remover marketplaces ```bash # Оновити метадані конкретного маркетплейсу (завантажити свіжі версії плагінів) codex plugin marketplace upgrade community-plugins # Оновити всі підключені Git-маркетплейси одночасно codex plugin marketplace upgrade # Видалити маркетплейс зі списку джерел codex plugin marketplace remove community-plugins ``` > [!TIP] > 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). > [!WARNING] > **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. --- ## 8. Ciclo de vida: desativação, remoção de plugin ou desconexão de catálogo 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ção | Comando | O que acontece com os arquivos | Consequências para as sessões | | :--- | :--- | :--- | :--- | | **Desativar plugin (Disable)** | Via interruptor `/plugins` | O plugin permanece no disco, a configuração é preservada | Skills e ferramentas MCP ficam inativas em novas sessões | | **Remover plugin (Uninstall)** | `codex plugin remove ` | Todos os arquivos do plugin são excluídos do ambiente local | Limpeza completa; para reutilização, é necessário novo download | | **Remover marketplace** | `codex plugin marketplace remove ` | Apenas a fonte é removida; plugins já instalados permanecem | Impossí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 # Встановити плагін codex plugin add # Встановити з конкретного джерела codex plugin remove # Видалити плагін # ─── Робота з Marketplaces ──────────────────────────────────────── codex plugin marketplace list # Список підключених каталогів codex plugin marketplace add # Додати маркетплейс (GitHub / URL / локальний) codex plugin marketplace upgrade # Оновити конкретний каталог codex plugin marketplace upgrade # Оновити всі підключені каталоги codex plugin marketplace remove # Видалити каталог зі списку # ─── Графічний інтерфейс ───────────────────────────────────────── /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.