Personalização

A personalização permite adaptar o Codex à forma de trabalhar da sua equipa.

No Codex, a personalização resulta de várias camadas que funcionam em conjunto:

• Orientações de projeto (AGENTS.md) para instruções persistentes
• Memórias para contexto útil obtido através de trabalhos anteriores
• Skills para fluxos de trabalho reutilizáveis e conhecimentos especializados num domínio
• MCP para acesso a ferramentas externas e sistemas partilhados
• Subagentes para delegar trabalho a subagentes especializados

Estas opções complementam-se, não competem entre si. AGENTS.md molda o comportamento, as memórias preservam o contexto local, as skills encapsulam processos repetíveis e o MCP liga o Codex a sistemas fora do espaço de trabalho local.

Orientações em AGENTS

AGENTS.md fornece ao Codex orientações de projeto duradouras, que acompanham o repositório e são aplicadas antes de o agente começar a trabalhar. Mantenha-o pequeno.

Utilize-o para as regras que pretende que o Codex siga sempre num repositório, como:

• Comandos de compilação e teste
• Expectativas de revisão
• Convenções específicas do repositório
• Instruções específicas de diretórios

Quando o agente fizer suposições incorretas sobre a sua base de código, corrija-as em AGENTS.md e peça ao agente para atualizar AGENTS.md, para que a correção seja preservada. Encare este processo como um ciclo de feedback.

Quando atualizar AGENTS.md

• Erros repetidos: se o agente cometer repetidamente o mesmo erro, adicione uma regra.
• Leitura excessiva: se encontrar os ficheiros certos, mas ler demasiados documentos, adicione orientações de encaminhamento (que diretórios/ficheiros deve priorizar).
• Feedback recorrente em PR: se deixar o mesmo feedback mais do que uma vez, formalize-o.
• No GitHub: num comentário de pull request, mencione @codex com um pedido (por exemplo, @codex add this to AGENTS.md) para delegar a atualização num chat na cloud.
• Automatizar verificações de divergências: utilize tarefas agendadas para executar verificações recorrentes (por exemplo, diariamente) que procurem lacunas nas orientações e sugiram o que adicionar a AGENTS.md.

Combine AGENTS.md com infraestrutura que imponha essas regras: hooks de pre-commit, linters e verificadores de tipos detetam problemas antes de os encontrar, tornando o sistema mais eficaz na prevenção de erros recorrentes.

O Codex pode carregar orientações a partir de várias localizações: um ficheiro global no diretório base do Codex (para si, enquanto programador) e ficheiros específicos do repositório que as equipas podem incluir no controlo de versões. Os ficheiros mais próximos do diretório de trabalho têm precedência. Utilize o ficheiro global para definir a forma como o Codex comunica consigo (por exemplo, o estilo de revisão, o nível de detalhe e as predefinições) e mantenha os ficheiros do repositório centrados nas regras da equipa e da base de código.

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "Global (para si, enquanto programador)" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "Específico do repositório (para a sua equipa)" }, ], }, ]} />

Instruções personalizadas com AGENTS.md

Skills

As skills conferem ao Codex capacidades reutilizáveis para fluxos de trabalho repetíveis. As skills são frequentemente a melhor opção para fluxos de trabalho reutilizáveis, pois suportam instruções, scripts e referências mais completos, mantendo-se reutilizáveis em diferentes tarefas. As skills são carregadas e ficam visíveis para o agente (pelo menos, os respetivos metadados), pelo que o Codex pode descobri-las e selecioná-las implicitamente. Isto mantém disponíveis fluxos de trabalho completos sem aumentar desnecessariamente o contexto inicial.

Utilize pastas de skills para criar e aperfeiçoar fluxos de trabalho localmente. Se já existir um plugin para o fluxo de trabalho, instale-o primeiro para reutilizar uma configuração comprovada. Quando pretender distribuir o seu próprio fluxo de trabalho entre equipas ou agrupá-lo com conectores, disponibilize-o como um plugin. As skills continuam a ser o formato de criação; os plugins são a unidade de distribuição instalável.

Normalmente, uma skill consiste num ficheiro SKILL.md, acompanhado opcionalmente de scripts, referências e recursos.

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "Obrigatório: instruções + metadados" }, { name: "scripts/", comment: "Opcional: código executável" }, { name: "references/", comment: "Opcional: documentação" }, { name: "assets/", comment: "Opcional: modelos, recursos" }, ], }, ]} />

O diretório da skill pode incluir uma pasta scripts/ com scripts de CLI que o Codex invoca como parte do fluxo de trabalho (por exemplo, para preencher dados iniciais ou executar validações). Quando o fluxo de trabalho necessitar de sistemas externos (sistemas de acompanhamento de problemas, ferramentas de design, servidores de documentação), combine a skill 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. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

Utilize skills para:

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

As skills podem ser globais (no seu diretório de utilizador, para si, enquanto programador) ou específicas do repositório (incluídas em .agents/skills, para a sua equipa). Coloque as skills do repositório em .agents/skills quando o fluxo de trabalho se aplicar a esse projeto; utilize o seu diretório de utilizador para as skills que pretende usar em todos os repositórios.

O Codex utiliza divulgação progressiva para as skills:

• Começa pelos metadados (name, description) para fins de descoberta
• Carrega SKILL.md apenas quando uma skill é selecionada
• Lê referências ou executa scripts apenas quando necessário

As skills podem ser invocadas explicitamente, e o Codex também pode selecioná-las implicitamente quando a tarefa corresponde à descrição da skill. Descrições claras das skills tornam a ativação mais fiável.

Criar skills

MCP

O MCP (Model Context Protocol) é a forma padrão de ligar o Codex a ferramentas externas e fornecedores de contexto. É especialmente útil para sistemas alojados remotamente, como Figma, Linear, GitHub ou serviços internos de conhecimento dos quais a sua equipa depende.

Utilize o MCP quando o Codex necessitar de capacidades que estejam fora do repositório local, como sistemas de acompanhamento de problemas, ferramentas de design, browsers ou sistemas de documentação partilhada.

Uma forma de o compreender:

• Anfitrião: Codex
• Cliente: a ligação MCP no Codex
• Servidor: a ferramenta externa ou o fornecedor de contexto

Os servidores MCP podem disponibilizar:

• Ferramentas (ações)
• Recursos (dados legíveis)
• Prompts (modelos de prompts reutilizáveis)

Esta separação facilita a compreensão dos limites de confiança e de capacidades. Alguns servidores fornecem sobretudo contexto, enquanto outros disponibilizam ações poderosas.

Na prática, o MCP é frequentemente mais útil quando combinado com skills:

• Uma skill define o fluxo de trabalho e identifica as ferramentas MCP a utilizar

Model Context Protocol

Subagentes

Pode criar diferentes agentes com funções distintas e instruí-los a utilizar ferramentas de formas diferentes. Por exemplo, um agente pode executar comandos e configurações de teste específicos, enquanto outro dispõe de servidores MCP que obtêm registos de produção para depuração. Cada subagente mantém-se concentrado e utiliza as ferramentas adequadas ao seu trabalho.

Subagentes

Skills + MCP em conjunto

É ao combinar skills e MCP que tudo se integra: as skills definem fluxos de trabalho repetíveis e o MCP liga-os a ferramentas e sistemas externos. Se uma skill depender do MCP, declare essa dependência em agents/openai.yaml para que o Codex possa instalá-la e configurá-la automaticamente (consulte Criar skills).

Próximo passo

Implemente pela seguinte ordem:

1. Instruções personalizadas com AGENTS.md, para que o Codex siga as convenções do seu repositório. Adicione hooks de pre-commit e linters para impor essas regras.
2. Instale um plugin quando já existir um fluxo de trabalho reutilizável. Caso contrário, crie uma skill e disponibilize-a como plugin quando pretender partilhá-la.
3. MCP quando os fluxos de trabalho necessitarem de sistemas externos (Linear, GitHub, servidores de documentação, ferramentas de design).
4. Subagentes quando estiver pronto para delegar tarefas ruidosas ou especializadas a subagentes.