Guia prático de Codex Skills e Plugins: transforme workflows de equipe em capacidades reutilizáveis

A mesma checklist de revisão de código é copiada em cinco repositórios. A cada PR, alguém ainda precisa lembrar manualmente: “rode primeiro os testes que falham”, “verifique o limite de permissões”, “não esqueça o changelog”. O problema não é o prompt ser curto. O processo ainda não virou algo reutilizável.

Codex Skills e Plugins servem exatamente para resolver essa repetição: tirar workflows recorrentes da equipe de prompts soltos e de um AGENTS.md cada vez maior, e transformar tudo em capacidades reutilizáveis. Um Skill é o formato de autoria para um workflow reutilizável. Um Plugin é uma unidade instalável de distribuição. Eles não substituem regras de projeto: regras permanentes ficam em AGENTS.md; procedimentos de várias etapas, exemplos, scripts e referências longas vão para Skills; distribuição para a equipe vira Plugin.

Uma tabela de decisão já ajuda a escolher entre Skill, Plugin, MCP, AGENTS.md e Subagent. Depois disso, dá para começar com uma árvore mínima de Skill e evoluir para divisão de role-specific plugin, distribuição para equipe e checklist de limites de permissão.

1. Workflows de equipe copiados: o problema não é o prompt

Revisão de código, checks antes de release, fluxo de testes e atualização de documentação costumam ter formato fixo dentro da equipe. Talvez você já cole no Codex, em cada revisão de PR: “confira se falta changelog, se a cobertura de testes caiu e se a documentação da API precisa ser atualizada”. Os problemas aparecem rápido:

• A manutenção fica espalhada: quando a checklist muda, é preciso atualizar cinco arquivos .github/PULL_REQUEST_TEMPLATE.md ou prompts separados.
• A execução varia: o Codex precisa entender o processo do zero a cada vez e pode esquecer passos importantes como “rodar primeiro os testes que falham”.
• Os papéis se misturam: frontend, QA, segurança e documentação ficam empilhados em um prompt, dificultando a escolha do padrão certo.

Algumas equipes colocam tudo isso em AGENTS.md, mas aí surge outro problema: o arquivo de regras do projeto fica longo demais. Comandos permanentes de build, convenções de diretório e instruções temporárias de processo acabam misturados. Isso passa do papel de um arquivo de restrições duradouras.

O Codex permite uma divisão mais clara: AGENTS.md para regras permanentes, Skills para workflows reutilizáveis e Plugins para distribuição. O ponto é saber o que entra em cada camada.

2. Uma tabela para separar Skill, Plugin, MCP e AGENTS.md

Um Skill é um formato de autoria para workflows reutilizáveis, normalmente um SKILL.md com scripts, referências e assets opcionais. Um Plugin é uma unidade instalável no Codex que pode empacotar Skills, app integrations, MCP servers e assets. MCP é o protocolo para conectar ferramentas externas e contexto, como documentação de terceiros, navegador, Figma ou GitHub. AGENTS.md guarda restrições permanentes do projeto: comandos de build, convenções de diretório e expectativas de revisão. Um Subagent delega um papel para tarefas barulhentas ou especializadas.

Quando escolher cada opção

Tipo de conteúdo	Melhor opção	Caso típico	Não use para
Comandos de build, caminhos de scripts de teste, convenções de diretório	AGENTS.md	”Todos os componentes novos vão em src/components/”, “testes rodam com npm run test:unit”	Processos de várias etapas, exemplos, chamadas a ferramentas externas
Workflows de várias etapas com exemplos, scripts ou referências	Skill	Revisão de código em 10 passos, checklist de release com 7 itens, geração de docs API	Uma única regra ou comando
Distribuição de equipe e empacotamento de configuração app/MCP	Plugin	Plugin de papel frontend com 4 Skills de revisão e um Figma connector	Workflow iterado em um único repositório e sem compartilhamento
Chamadas a ferramentas externas e contexto de terceiros	MCP	Buscar specs no Figma, acessar issues via GitHub API	Definição pura de workflow sem dados externos
Delegação de tarefas barulhentas ou especializadas	Subagent	Passar diagnóstico de testes ou análise de logs para um agente dedicado	Processo simples que cabe na conversa principal

Quando tirar algo do AGENTS.md e virar Skill

Estes sinais indicam que o processo passou do limite de um arquivo de regras de projeto:

• A mesma checklist aparece em vários PRs e é colada manualmente.
• O fluxo tem várias etapas e precisa de exemplos, scripts ou referências externas.
• O fluxo tem gatilho claro, como “antes do release” ou “durante a revisão do PR”, em vez de ser uma regra permanente.
• Papéis diferentes têm padrões diferentes e não cabem bem em um único arquivo.
• O processo precisa de versionamento e histórico de mudanças, não de edição direta nas regras do projeto.

Quando evoluir de Skill para Plugin

Um Skill basta enquanto ele está sendo iterado em um repositório ou workflow pessoal. Empacote como Plugin quando aparecerem necessidades como:

• compartilhar entre equipes, não só em uma pasta pessoal ou um repositório;
• empacotar app integrations como Figma, GitHub, ferramentas CI/CD ou configuração de MCP server;
• ter versionamento, changelog e mecanismo de upgrade, em vez de copiar pastas de Skill;
• distribuir pela Plugin Directory do Codex App para workspace members;
• publicar um pacote estável, não um fluxo experimental que muda todo dia.

Uma ordem prática: coloque convenções do repositório em AGENTS.md; instale um Plugin existente se ele resolver; caso contrário, crie um Skill; transforme em Plugin quando distribuição fizer sentido; conecte MCP só quando precisar de sistema externo; use Subagent quando a tarefa for barulhenta ou especializada o bastante para delegar.

3. Skill mínimo útil: comece por revisão de código

Árvore mínima de Skill

Um Skill precisa pelo menos disto:

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

O nome do diretório e o name no frontmatter de SKILL.md precisam bater, usando lowercase alphanumeric + hyphen.

Exemplo de SKILL.md: Skill de revisão de código

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

Design de gatilho na description: before/after

O Codex usa a description para decidir quando invocar um Skill implicitamente. Se ela for vaga, pode disparar errado ou não disparar:

Before, fácil de disparar errado	After, mais confiável
”Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

Escreva limites claros com “Use when…” e “Do not use when…”. Coloque termos de gatilho, como pull request, review e frontend, no começo. Descrições longas podem ser truncadas. Se quiser apenas invocação explícita, defina allow_implicit_invocation: false.

Locais e escopo de Skills

Local	Escopo	Uso típico	Observações
.agents/skills/ na raiz do repositório	Repositório atual	Processos de revisão, teste e release do time	Entra no Git e é compartilhado com a equipe
$HOME/.agents/skills/	Pessoal, multi-projeto	Estilo pessoal e comandos frequentes	Não sincroniza automaticamente com o repositório
/etc/codex/skills/	Organização	Revisões comuns de segurança ou compliance	Precisa de permissão admin
System bundled	Integrado	Skills como $skill-creator e $skill-installer	Não pode ser alterado

Skills com o mesmo nome não são mesclados. A prioridade costuma ser repo > user > admin > system, mas a documentação oficial é a referência se esse comportamento mudar.

Design com progressive disclosure

Não coloque tudo no SKILL.md principal. O Codex usa progressive disclosure em três camadas:

1. Metadata: no começo, vê apenas name, description e file path.
2. Instructions: o SKILL.md completo só é carregado depois que o Skill é selecionado.
3. Resources: references/, scripts/ e assets/ só são lidos quando necessários.

Como regra, mantenha o SKILL.md principal abaixo de 500 linhas. Referências longas vão para arquivos separados. scripts/ deve guardar verificações determinísticas, como runner de testes ou cobertura. references/ recebe checklists detalhadas, contexto e casos históricos. assets/ fica para templates e capturas de exemplo.

Invocação explícita e implícita

A invocação explícita usa $code-review ou o seletor /skills. A implícita deixa o Codex decidir, pela description, se o Skill combina com a tarefa. Para desativar, defina allow_implicit_invocation: false em agents/openai.yaml.

Invocação implícita combina com workflows frequentes e bem delimitados, como revisão de PR. Invocação explícita é mais segura para tarefas raras e com mais julgamento humano, como auditoria trimestral de segurança. Se um Skill inclui scripts externos ou operações sensíveis, prefira invocação explícita.

4. Empacotamento de Plugin e distribuição de equipe: do Skill local à suíte do time

Estrutura mínima de Plugin

Plugin não é só renomear a pasta de Skill. É um pacote instalável e precisa pelo menos de um manifest .codex-plugin/plugin.json:

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

Campos obrigatórios de plugin.json

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

Campos opcionais incluem apps para app integrations, como .app.json for Figma, mcpServers para configuração de MCP server como .mcp.json, e policy para permissões e compartilhamento de dados, sempre sujeito à workspace admin policy.

Estrutura de marketplace: diretório de Plugins da equipe

Um Plugin marketplace é uma lista JSON que aponta para os caminhos dos Plugins:

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local é para Plugins internos ainda não publicados. github aponta para repositórios públicos ou pacotes compartilhados entre equipes.

Checklist de comandos para distribuir Plugin

Comandos de CLI podem mudar, então use a documentação oficial como referência:

# Criar o scaffold de um Plugin novo
codex plugin create frontend-review

# Adicionar Plugin ao marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# Listar Plugins instalados
codex plugin marketplace list

# Atualizar Plugin
codex plugin marketplace upgrade frontend-review

# Remover Plugin
codex plugin marketplace remove frontend-review

No Codex App, a Plugin Directory pode mostrar Curated by OpenAI, Shared with you e Created by you. Um local plugin pode ser compartilhado com workspace members ou groups. Workspace admins podem desativar plugin sharing ou definir managed requirements.

Compartilhar no workspace não é o mesmo que publicar. Conexões com apps externos e MCP servers ainda precisam de autorização, e approval settings continuam valendo.

Organização do marketplace da equipe

Coloque o marketplace do repositório em $REPO_ROOT/.agents/plugins/marketplace.json para Plugins específicos do projeto. Para Plugins de organização, use $HOME/.agents/plugins/marketplace.json ou um repositório de GitHub organization. Declare version no manifest, mantenha changelog no README e valide upgrades em ambiente de teste. Plugins sensíveis, como segurança e compliance, devem ficar no marketplace da organização para evitar instalação casual.

Comece com local skill, itere até estabilizar e só então empacote como Plugin. Criar o Plugin logo de cara normalmente dificulta ajustes.

5. Design de role-specific Plugin: frontend, QA e documentação como papéis

O repositório role-specific-plugins da OpenAI traz templates para Sales, Data Analytics, Product Design e Financial Markets. Times de desenvolvimento não precisam copiar workflows de vendas ou finanças, mas o padrão de divisão é útil: partir de um papel, extrair 3 a 5 Skills pequenos e empacotar como Plugin.

Quadro de divisão: papel → entregável repetido → fontes de dados/ferramentas → Skills pequenos → modelo de compartilhamento

Papel	Entregável repetido	Fontes de dados/ferramentas	Skills a separar	Apps/MCP possíveis	Critério de aceite
Engenheiro frontend	Revisão de componente, checagem de desempenho, validação de acessibilidade	Specs Figma, biblioteca Storybook existente	component-audit, accessibility-check, performance-lint, design-system-sync	Figma connector, Storybook MCP	Todo componente novo passa pelos 4 checks
Engenheiro QA	Relatório de cobertura, diagnóstico de suíte E2E, checklist de regressão	Resultados CI/CD, histórico de falhas	test-coverage-check, e2e-suite-runner, flaky-test-diagnosis, regression-suite-builder	Ferramentas CI/CD como GitHub Actions/Jenkins	Testes falhos primeiro, sem queda de cobertura
Redator técnico	Atualização de API docs, changelog, guias de migração	API schema, Git commit history	api-doc-generator, changelog-builder, readme-audit, migration-guide-writer	GitHub API, ferramentas de schema	Docs atualizadas quando a API muda
Engenheiro de segurança	Revisão de limites de permissão, secrets scan, segurança de dependências	Manifests de dependências, configuração de secrets	auth-boundary-check, secrets-scan, dependency-security	Snyk, Dependabot MCP	Checklist de segurança antes de cada release

Exemplo de divisão para Plugin de papel frontend

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit verifica se um componente novo segue as normas da equipe, como nome, diretório e tipos de props. accessibility-check roda um script com axe-core. performance-lint verifica métricas principais com Lighthouse. design-system-sync compara a implementação com as specs do Figma.

Exemplo de divisão para Plugin de papel QA

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check detecta queda de cobertura e marca arquivos sem cobertura. e2e-suite-runner executa testes E2E por prioridade. flaky-test-diagnosis analisa logs históricos para encontrar testes instáveis. regression-suite-builder cria uma checklist de regressão a partir da área alterada.

Checklist para substituir connector placeholders

Templates oficiais podem conter connector IDs placeholder em .app.json. Substitua antes de instalar:

{
  "app_id": "figma-placeholder"
}

Verifique todos os placeholder IDs em .app.json e troque por IDs reais disponíveis no seu workspace. Não copie connector IDs de outro workspace: eles podem ser inválidos ou sem permissão no seu ambiente. Tokens OAuth/Bearer em MCP server configuration devem ser configurados para o seu ambiente, não copiados de exemplos. Depois, valide o connector em um ambiente de teste.

O README oficial de role-specific-plugins explica que esses templates devem ser personalizados antes do uso. Connector-backed plugins podem conter app IDs ou connector IDs que precisam ser substituídos.

6. Segurança e manutenção: Plugin não é passe de permissão

Limites de permissão de Connector / MCP

Instalar um Plugin não ignora approval settings do Codex. Apps externos e MCP servers continuam exigindo autorização, e compartilhamento de dados segue as políticas de cada serviço. Placeholder IDs em .app.json precisam ser substituídos, mas não copie connector IDs de outro workspace. Apps externas como Figma ou GitHub exigem autorização separada. O Plugin empacota configuração; não concede autorização por si só. MCP servers continuam controláveis por enabled e tool policy em config.toml. Approval mode também vale: se estiver em “suggest-only”, scripts dentro do Plugin não rodam automaticamente.

Não trate Plugin como passe de permissão. Ele empacota workflow, configuração e assets, mas o limite de permissões continua existindo.

Revisão de origem dos scripts

A pasta scripts/ em um Skill ou Plugin pode conter executáveis. Plugins de terceiros e marketplaces comunitários exigem revisão: inspecione todos os executáveis em scripts, confirme a origem, evite rodar scripts de repositórios não verificados, teste primeiro em ambiente de teste e fixe versões por tag ou commit hash em vez de puxar sempre de main.

O mesmo princípio usado para Skills de terceiros com risco vale para qualquer script executável e Plugin externo: revisar origem, minimizar permissões e validar em ambiente de teste.

Versão e changelog

Colaboração em equipe precisa de versionamento. Declare version em plugin.json, incremente a cada atualização e mantenha changelog no README explicando Skills novos, alterados e removidos. Antes de atualizar, teste em ambiente de teste, execute todos os Skills, verifique scripts e confirme que connectors seguem disponíveis. Em marketplace entries, fixe ref em tag ou commit, não no main mais recente.

Impacto da quantidade de Skills e Plugins

A lista inicial de Skills tem orçamento de contexto. A documentação oficial descreve que a initial skills list ocupa cerca de 2% do contexto, ou 8.000 characters quando o tamanho do contexto é desconhecido.

Na prática, uma description longa demais pode ser truncada; por isso, os termos de gatilho devem vir no começo. Muitos Skills carregados também podem dificultar a escolha correta pelo Codex. Skills frequentes e bem delimitados cabem bem no diretório repo ou user. Skills raros ficam melhores em um Plugin instalado só quando necessário, em vez de tudo ficar sempre ativo.

Se o Codex dispara o Skill errado ou não dispara o correto, revise primeiro a description. Adicionar mais Skills raramente resolve.

7. Comparação com tecnologias relacionadas

Comparação com Claude Code Skills

BetterLink já cobriu o mecanismo de Claude Code Skills. O modelo mental é parecido, mas os produtos são diferentes: ambos usam o formato aberto Agent Skills e um arquivo SKILL.md; ambos usam name, description e opcionais scripts/, references/, assets/; ambos usam progressive disclosure: metadata → instructions → resources.

As diferenças importam. Codex usa .agents/skills/; Claude Code usa .claude/skills/. Codex invoca com $skill-name ou /skills; Claude Code usa o comando /skill. Na distribuição, Codex Plugin tem marketplace, comandos CLI e workspace sharing; Claude Code não tem hoje um Plugin marketplace oficial. Ferramentas integradas também mudam: Codex tem $skill-creator, $skill-installer e @plugin-creator; Claude Code tem comandos próprios.

Se você já escreveu Claude Code Skills, pode reutilizar o modelo mental. Não copie caminhos nem sintaxe de invocação; siga a documentação oficial de cada produto.

Divisão com MCP

MCP, Model Context Protocol, conecta ferramentas externas e contexto. Não substitui Skills nem Plugins. Um Skill define o workflow. MCP conecta a ferramenta externa, como Figma, GitHub ou um sistema CI/CD. Um Plugin pode empacotar configuração de MCP server, mas o MCP server continua controlado por config.toml.

Exemplo: um Skill de revisão frontend define o processo “verificar se o componente segue o design system”; um Figma MCP server fornece acesso ao arquivo de design; um Plugin frontend empacota o Skill de revisão e a configuração Figma MCP, mas Figma OAuth ainda precisa de autorização separada.

Aqui a ideia é só deixar a fronteira clara. Um guia prático de Codex MCP tools pode detalhar a implementação.

Conclusão

Codex Skills e Plugins ajudam porque tiram workflows repetidos de equipe de prompts copiados e de um AGENTS.md sobrecarregado. A regra é simples: AGENTS.md para regras permanentes, Skill para workflows de várias etapas, Plugin para empacotar e distribuir, MCP para sistemas externos. Escreva condições claras na description, valide primeiro um local skill e transforme em Plugin só quando a distribuição for real. Scripts, connector IDs e configurações MCP de Plugins de terceiros ainda precisam de revisão.

Comece com um Skill mínimo. Transforme o processo de revisão de código ou testes da sua equipe em SKILL.md, rode algumas vezes e veja se o gatilho é confiável. Se a equipe tem papéis de frontend, QA, segurança ou documentação, use o padrão do OpenAI role-specific-plugins: 3 a 5 pequenos Skills por papel e depois um Plugin de papel.

Leituras relacionadas no BetterLink:

• Guia completo para começar com Codex
• Regras de projeto AGENTS.md
• Limites de segurança e gerenciamento de permissões no Codex
• Codex MCP tools na prática
• Comparação com Claude Code Skill
• Fundamentos do protocolo MCP