Personalização

Com a personalização, você adapta o Codex à forma como sua equipe trabalha.

No Codex, você pode combinar várias camadas de personalização:

• Orientações do projeto (AGENTS.md) para definir instruções persistentes
• Memórias para aproveitar o contexto adquirido em trabalhos anteriores
• Habilidades para reutilizar fluxos de trabalho e aplicar conhecimentos especializados
• MCP para acessar ferramentas externas e sistemas compartilhados
• Subagentes para delegar tarefas a subagentes especializados

Essas camadas se complementam. O AGENTS.md orienta o comportamento do agente, as memórias preservam o contexto local para trabalhos futuros, as habilidades reúnem procedimentos que você pode repetir, e o MCP conecta o Codex a sistemas fora do espaço de trabalho local.

Orientações no AGENTS.md

O AGENTS.md contém orientações permanentes do projeto. O arquivo acompanha o repositório, e as instruções já se aplicam antes de o agente começar a trabalhar. Mantenha o arquivo curto.

Use esse arquivo para registrar as regras que o Codex deve seguir sempre que trabalhar no repositório, como:

• Comandos de build e teste
• O que se espera de uma revisão de código
• Convenções específicas do repositório
• Instruções específicas de cada diretório

Quando o agente fizer suposições incorretas sobre sua base de código, esclareça esses pontos no AGENTS.md. Peça ao agente que atualize o AGENTS.md para registrar a correção. Repita esse processo a cada novo ajuste.

Quando atualizar o AGENTS.md

• Erros repetidos: se o agente cometer o mesmo erro várias vezes, adicione uma regra.
• Leitura excessiva: se o agente encontrar os arquivos certos, mas ler documentos demais, indique quais diretórios ou arquivos ele deve priorizar.
• Comentários recorrentes em pull requests: se você fizer a mesma observação mais de uma vez, transforme-a em regra.
• Verificações automáticas das orientações: use tarefas agendadas para verificar periodicamente (por exemplo, todos os dias) se há lacunas nas orientações e obter sugestões sobre o que acrescentar ao AGENTS.md.

Combine o AGENTS.md com ferramentas que apliquem essas regras. Hooks de pré-commit, linters e verificadores de tipos detectam problemas antes que você os perceba e ajudam o sistema a prevenir erros recorrentes com mais eficácia.

O Codex pode carregar orientações de vários locais. No diretório pessoal do Codex, você pode manter um arquivo global para seu trabalho de desenvolvimento. A equipe pode versionar arquivos específicos de cada repositório. Os arquivos mais próximos do diretório de trabalho têm precedência. Use o arquivo global para definir como o Codex se comunica com você (por exemplo, o estilo das revisões, o nível de detalhe e as preferências padrão). Reserve os arquivos do repositório para as regras da equipe e da base de código.

Instruções personalizadas com AGENTS.md

Habilidades

As habilidades dão ao Codex recursos que ele pode reutilizar em fluxos de trabalho recorrentes. Elas costumam ser a melhor opção para esses fluxos porque comportam instruções detalhadas, scripts e referências e podem ser usadas em várias tarefas. O agente tem acesso às habilidades carregadas (ou pelo menos aos seus metadados), o que permite ao Codex identificá-las e escolhê-las sem um pedido explícito. Assim, fluxos detalhados ficam disponíveis sem sobrecarregar o contexto inicial.

Use pastas de habilidades para criar e aprimorar fluxos de trabalho localmente. Se já houver um plugin para o fluxo, instale-o primeiro para aproveitar uma configuração que já foi testada. Quando quiser distribuir seu próprio fluxo para outras equipes ou incluí-lo em um pacote com conectores, crie um plugin. Você cria os fluxos como habilidades e os distribui como plugins instaláveis.

Uma habilidade geralmente consiste em um arquivo SKILL.md e pode incluir scripts, referências e outros recursos.

O diretório da habilidade pode incluir uma pasta scripts/ com scripts de CLI que o Codex executa durante o fluxo de trabalho, por exemplo, para carregar dados iniciais ou executar validações. Quando o fluxo precisar de sistemas externos, como gerenciadores de issues, ferramentas de design ou servidores de documentação, combine a habilidade com o MCP.

Exemplo de SKILL.md:

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Não execute `git add .`. Adicione os arquivos à área de preparação em grupos lógicos, de acordo com a finalidade de cada alteração.
2. Organize as alterações em commits separados, nesta ordem: feat → test → docs → refactor → chore.
3. Escreva mensagens de commit concisas que reflitam o escopo de cada alteração.
4. Mantenha cada commit focado em uma única finalidade e fácil de revisar.

Use habilidades para:

• Fluxos de trabalho recorrentes (etapas de lançamento, rotinas de revisão, atualizações da documentação)
• Conhecimentos específicos da equipe
• Procedimentos que exigem exemplos, referências ou scripts auxiliares

As habilidades podem ser globais (no seu diretório de usuário, para seu trabalho de desenvolvimento) ou específicas do repositório (versionadas em .agents/skills, para sua equipe). Coloque as habilidades do repositório em .agents/skills quando o fluxo se aplicar àquele projeto. Use seu diretório de usuário para as habilidades que quiser usar em todos os repositórios.

O Codex carrega as informações de cada habilidade por etapas:

• Começa pelos metadados (name, description) para identificar as habilidades disponíveis
• Carrega o SKILL.md somente quando uma habilidade é selecionada
• Lê referências ou executa scripts apenas quando necessário

Você pode solicitar uma habilidade explicitamente. O Codex também pode escolhê-la por conta própria quando a tarefa corresponder à descrição da habilidade. Descrições claras ajudam o Codex a acionar a habilidade certa de forma consistente.

Criar habilidades

MCP

O MCP (Model Context Protocol) é o protocolo padrão para conectar o Codex a ferramentas externas e provedores de contexto. Ele é especialmente útil para sistemas hospedados remotamente, como Figma, Linear, GitHub ou serviços internos de conhecimento dos quais sua equipe depende.

Use o MCP quando o Codex precisar de recursos externos ao repositório local, como gerenciadores de issues, ferramentas de design, navegadores ou sistemas de documentação compartilhada.

Você pode entender essa conexão pelos papéis de cada parte:

• Host: o Codex
• Cliente: a conexão MCP dentro do Codex
• Servidor: a ferramenta externa ou o provedor de contexto

Os servidores MCP podem disponibilizar:

• Ferramentas (ações)
• Recursos (dados para leitura)
• Prompts (modelos de prompt reutilizáveis)

Essa divisão ajuda a entender os limites de confiança e o que cada componente pode fazer. Alguns servidores fornecem principalmente contexto, enquanto outros permitem executar ações de grande alcance.

Na prática, o MCP costuma ser mais útil quando combinado com habilidades:

• A habilidade define o fluxo de trabalho e indica quais ferramentas MCP usar

Model Context Protocol

Subagentes

Você pode criar agentes com funções diferentes e orientar cada um a usar as ferramentas de uma forma específica. Por exemplo, um agente pode executar testes com comandos e configurações específicos, enquanto outro pode usar servidores MCP para buscar logs de produção durante a depuração. Cada subagente se concentra na própria tarefa e usa as ferramentas adequadas para realizá-la.

Subagentes

Como combinar habilidades e MCP

As habilidades definem fluxos de trabalho que você pode repetir, e o MCP conecta esses fluxos a ferramentas e sistemas externos. Se uma habilidade depender do MCP, declare essa dependência em agents/openai.yaml para que o Codex possa instalá-la e configurar a conexão automaticamente (consulte Criar habilidades).

Próximo passo

Personalize o Codex nesta ordem:

1. Defina instruções personalizadas com AGENTS.md para que o Codex siga as convenções do repositório. Adicione hooks de pré-commit e linters para aplicar essas regras.
2. Instale um plugin quando já houver um fluxo de trabalho reutilizável. Caso contrário, crie uma habilidade e, quando quiser compartilhá-la, distribua-a como plugin.
3. Use o MCP quando os fluxos de trabalho precisarem de sistemas externos (Linear, GitHub, servidores de documentação, ferramentas de design).
4. Use subagentes quando estiver pronto para delegar a eles tarefas que geram muitas mensagens ou exigem conhecimento especializado.