AGENTS.md e skills no Codex
O AGENTS.md é o arquivo de instruções que o Codex consulta para trabalhar no repositório. As skills acrescentam procedimentos por tarefa, carregando orientações e recursos específicos para o agente alterar e conferir o código do seu app.
Ficha e sumário da página
- Referência técnica
- Codex CLI 0.169.0
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
As instruções acompanham os arquivos do projeto
O AGENTS.md permite registrar orientações que precisam reaparecer nas tarefas do repositório. O arquivo pode explicar o comando de testes, a organização das pastas e as restrições de alteração. Quando o Codex carrega essas instruções, você não precisa repetir cada convenção na descrição de uma correção. A tarefa continua indicando o resultado desejado, enquanto o arquivo apresenta as instruções do projeto.
Uma orientação útil aponta uma ação verificável. Num projeto com duas aplicações, por exemplo, o arquivo pode identificar o comando que testa cada uma. Isso ajuda o agente a relacionar a pasta alterada ao teste correspondente. Uma frase genérica sobre qualidade deixa essa escolha sem explicação. O arquivo funciona melhor quando descreve os caminhos e os comportamentos que realmente existem naquele repositório.
A pasta de trabalho muda as instruções carregadas
O Codex monta uma cadeia de instruções ao iniciar a execução. A leitura começa pelas orientações globais do diretório pessoal do Codex. Depois, o cliente percorre o caminho da raiz do projeto até a pasta de trabalho. As instruções mais próximas dessa pasta entram depois das orientações mais gerais, permitindo especializar as orientações de uma parte do repositório.
Em cada diretório, AGENTS.override.md tem precedência sobre AGENTS.md. A configuração pode acrescentar nomes alternativos para descoberta. O cliente inclui no máximo um arquivo de instruções por diretório nesse percurso. Assim, encontrar dois nomes na mesma pasta não significa que os dois textos foram combinados. A presença do override explica por que uma orientação do arquivo comum pode não aparecer na sessão.
Você confere essa relação pela pasta usada ao iniciar o Codex e pelos arquivos existentes no caminho. Se uma sessão começa na raiz e outra começa dentro de um serviço, a cadeia carregada pode diferir. O cliente ignora arquivos vazios e limita o tamanho combinado das instruções conforme a configuração. Separar instruções por diretório exige considerar onde o agente começa o trabalho.
RepositórioRaiz do projeto consultado.AGENTS.mdComandos e convenções gerais.servico/AGENTS.mdOrientações específicas do serviço..agents/skills/revisar/SKILL.mdProcedimento selecionado para revisão.
A skill descreve um trabalho específico
Uma skill reúne instruções em SKILL.md e pode incluir referências, scripts e ativos. O arquivo informa um nome e uma descrição nos metadados. Esses campos permitem que o agente reconheça quando aquele procedimento se aplica. O conteúdo completo desenvolve o trabalho que deve ser feito, com entradas, resultados esperados e formas de conferência.
O carregamento é progressivo. O Codex começa com os nomes e as descrições disponíveis e lê as instruções completas ao selecionar uma skill. Uma biblioteca extensa, portanto, não exige inserir o corpo de todos os procedimentos a cada tarefa. A descrição tem uma função concreta: ajudar a distinguir uma revisão de código de uma atualização de documentação, por exemplo, antes de carregar os detalhes.
Você pode mencionar uma skill explicitamente na CLI, ou o agente pode selecionar uma pela correspondência entre a tarefa e a descrição. A documentação apresenta /skills e a menção com $ como formas de acesso na CLI. A seleção implícita depende da configuração da skill. Um procedimento pode exigir chamada explícita, preservando o uso apenas quando você o solicita.
Referências e scripts têm funções diferentes
Uma referência fornece informação para leitura. Um script executa ações determinadas pelo código que contém. Essa diferença importa ao revisar uma skill recebida de outro repositório. O texto pode orientar uma conferência, enquanto o script pode escrever arquivos, chamar um serviço ou alterar uma configuração. Você precisa compreender esse efeito antes de incorporar o procedimento ao projeto.
As skills locais são encontradas em diretórios do repositório e da pasta pessoal, conforme a documentação do Codex. Para o repositório, a descoberta considera .agents/skills ao longo do caminho até a raiz. Se duas skills têm o mesmo nome, elas não são fundidas automaticamente. O caminho exibido para a skill identifica o arquivo de instruções selecionado para a tarefa.
O arquivo de instruções e a skill também não concedem, por si, permissão técnica para executar qualquer comando. A sandbox e as aprovações continuam aplicáveis. Uma instrução pode solicitar um teste que escreve fora do diretório permitido e receber uma recusa do ambiente. Nesse caso, o resultado precisa registrar que aquele teste não foi executado, sem apresentar a orientação escrita como comprovação de execução.
Manutenção junto do código
Quando um comando de teste muda, as instruções que apontam para ele precisam acompanhar a alteração. Um AGENTS.md desatualizado pode direcionar a sessão para um comando inexistente. Uma skill com referência removida pode deixar a tarefa sem o material necessário. A revisão desses arquivos faz parte da manutenção das convenções que o agente usa para trabalhar.
O cliente Codex CLI, mantido pela OpenAI sob Apache 2.0, é a referência técnica deste texto na versão 0.169.0. As instruções do seu projeto permanecem sob seu controle. Para organizar instruções, testes e arquitetura com acompanhamento recorrente, o Conselheiro de Tecnologia da Dev Side Studio atende esse trabalho junto do código.