Codex Skills: criação, execução e verificação em uma tarefa de code review

O mecanismo de Skills no Codex

O mecanismo de habilidades (skills), descrito na documentação oficial, conecta instruções e modelos para tarefas especializadas ao agente sem sobrecarregar o contexto do sistema.

Uma skill consiste em um diretório contendo o arquivo obrigatório SKILL.md. No seu frontmatter YAML, os campos name e description são obrigatórios, enquanto o corpo contém as regras para o modelo:

.agents/skills/boundary-review/
└── SKILL.md

O Codex utiliza progressive disclosure: na inicialização, é gerado um índice compacto das skills disponíveis. O texto completo do SKILL.md só é lido pelo agente no momento em que ele decide aplicar uma habilidade específica.

A descoberta de skills opera em quatro níveis:

1. Repositório (REPO): .agents/skills no diretório atual e acima até a raiz do Git.
2. Usuário (USER): $HOME/.agents/skills.
3. Administrador (ADMIN): /etc/codex/skills.
4. Sistema (SYSTEM): diretórios de sistema do ambiente (bundled).

A invocação é realizada de forma explícita (por meio do prefixo $nome) ou implícita (com base na correspondência semântica entre a solicitação e o campo description). A disponibilidade e os conflitos são gerenciados no arquivo config.toml.

Pré-requisitos e isolamento

Para reproduzir o cenário, são necessários:

• Python 3;
• Interface de linha de comando Codex CLI instalada e autenticada.

Os dados de teste foram registrados em 2026-09-16 na versão 0.153.3 da Codex CLI.

Todos os comandos são executados em um diretório local preparado fora de um repositório Git. Como as instruções em texto no SKILL.md orientam o comportamento do modelo, mas não garantem isolamento no nível do sistema operacional, a execução é realizada com as seguintes flags:

• --ephemeral: evita a persistência do estado da sessão;
• --skip-git-repo-check: permite a execução em uma pasta isolada sem Git;
• --sandbox read-only: restringe o acesso de escrita do processo no nível do ambiente de execução.

A CLI pode herdar configurações globais e emitir avisos de serviço sobre hooks de terceiros; portanto, a verificação factual baseia-se exclusivamente em eventos de leitura da skill alvo.

Criação da skill boundary-review

Crie o diretório da skill no diretório atual:

mkdir -p .agents/skills/boundary-review

Salve o seguinte conteúdo em .agents/skills/boundary-review/SKILL.md:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

A instrução em texto proíbe o modelo de modificar arquivos e exige iniciar a resposta com o marcador de sinalização BOUNDARY_REVIEW, indicando obrigatoriamente um valor de entrada que cause falha.

Arquivo de teste com defeito

Crie um arquivo pages.py com um erro típico de deslocamento de um (off-by-one) no cálculo do número de páginas:

def page_count(total, size):
    return total // size + 1

Sob as condições size > 0 e total >= 0, a função falha em um valor de borda: para total = 1 e size = 1, ela retorna 2 em vez de 1. Além disso, para uma lista vazia onde total = 0, a função retornará 1.

Execução e verificação de invocações

As consultas são passadas entre aspas simples para evitar que o interpretador de comandos trate o caractere $ como uma variável de ambiente.

1. Invocação explícita por nome

Execute uma verificação explícita especificando diretamente a skill:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

O modelo retorna o seguinte resultado:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

A presença do marcador BOUNDARY_REVIEW por si só não comprova que o SKILL.md foi carregado, pois o texto do marcador poderia ser gerado a partir do contexto da solicitação. Na execução real de 2026-09-16, o log do sistema registrou um evento de comando para leitura do arquivo .agents/skills/boundary-review/SKILL.md. É exatamente a combinação do evento de leitura do arquivo no log, do prefixo BOUNDARY_REVIEW e do contraexemplo page_count(1, 1) que confirma a execução da instrução pretendida.

2. Invocação implícita por descrição

Formule a tarefa em linguagem natural sem mencionar o identificador $boundary-review:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

No log dessa execução, também foi registrada a leitura de .agents/skills/boundary-review/SKILL.md, graças à correspondência da frase da consulta com o campo description. O agente gerou uma resposta estruturada semelhante, contendo o marcador BOUNDARY_REVIEW e a análise da falha na entrada (1, 1).

Verificação da lógica e etapas para o leitor

Vamos verificar o comportamento original da função com o interpretador local do Python:

python3 -c "from pages import page_count; print(page_count(1, 1))"

O comando exibe 2, confirmando a presença do defeito.

Durante a execução de controle em 2026-09-16, o arquivo original pages.py permaneceu inalterado; não foi realizada uma nova execução da CLI no arquivo modificado. A exatidão matemática da fórmula proposta (total + size - 1) // size para total >= 0 e size > 0 foi verificada nos conjuntos de borda:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

Para a correção manual, o leitor pode ajustar o pages.py para:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

Após salvar as alterações, o leitor pode executar a verificação de asserções:

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

O resultado esperado do comando após a edição manual do arquivo é OK.

Solução de problemas

Se uma skill não for descoberta ou não for invocada automaticamente:

1. Caminho do arquivo: certifique-se de que o caminho relativo ao diretório de trabalho seja exatamente .agents/skills/<skill-name>/SKILL.md.
2. Atualização do registro: se os arquivos foram adicionados durante uma sessão ativa, reinicie o processo da CLI para reler os diretórios.
3. Bloqueio na configuração: verifique ~/.codex/config.toml. Se a skill tiver sido desativada, uma entrada como:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   bloqueará seu carregamento. Remova o bloco ou defina enabled = true.
4. Conflitos de nomes: se existirem valores idênticos de name nos níveis de repositório e de usuário, as regras de precedência podem gerar ambiguidade.
5. Precisão da description: para a invocação implícita, gatilhos essenciais (“pagination boundaries”, “boundary errors”) devem estar posicionados no início da descrição.
6. Skills de terceiros: caso seja necessário carregar pacotes externos, o ponto de entrada é a ferramenta utilitária $skill-installer. Qualquer skill de terceiros exige auditoria manual obrigatória dos arquivos SKILL.md e do diretório scripts/ antes da execução. No cenário descrito, nenhum componente de terceiros foi instalado.