No Codex, um skill não é um /command (e no Claude Code quase é)

TL;DR: Se você está no Codex, use um command para controlar a sessão ou a aplicação, e use um skill para ensinar ao agente uma maneira de trabalhar. No Claude Code, a documentação atual já trata as skills como algo invocável com /skill-name, então os dois conceitos se misturam muito mais. No Codex, não: types pode existir como skill e /types ainda assim pode não existir.

Existe uma confusão bastante comum quando você migra do Claude Code para o Codex. E isso é compreensível.

Você cria um skill chamado types, volta para o terminal, digita /types com toda boa intenção… e o Codex te olha como se você tivesse pedido um café num depósito de ferramentas.

O problema não é que o skill esteja quebrado. O problema é que no Codex um skill e um command não são a mesma coisa.

E atenção, porque essa diferença não é superficial. Ela muda como você desenha o seu fluxo de trabalho.

A analogia que deixa tudo mais claro

Pense no Codex como um avião com duas camadas.

A primeira camada é a cabine: botões, alavancas, indicadores. Aqui vivem os commands. Eles servem para alterar o estado da sessão, do cliente ou da ferramenta. São controles operativos.

A segunda camada é o manual do copiloto: procedimentos, critérios, listas de verificação, armadilhas a evitar. Aqui vivem os skills. Eles servem para mudar como o agente raciocina ao fazer uma tarefa.

Traduzido para humanos:

• Um command mexe na cabine.
• Um skill mexe na cabeça do copiloto.

Se você tentar usar o manual como se fosse um botão, isso não cola.

O que é um command no Codex

No Codex existem dois tipos de commands que é importante não misturar.

O primeiro são os comandos de CLI:

codex login
codex exec "run tests and fix failures"
codex resume --last
codex apply

Aqui não há mistério. São operações da aplicação. Autenticar-se, iniciar uma tarefa, retomar uma sessão, aplicar um diff. Se amanhã você remover o modelo, esses comandos ainda farão sentido.

O segundo são os slash commands dentro da sessão interativa:

/model
/permissions
/personality
/agent
/status

Esses também não são “prompts bonitos”. Eles são controles da sessão em tempo real. Mudam o modelo, as permissões, a personalidade, o agente ativo ou o estado visível. São botões do painel de controle.

A OpenAI, aliás, documenta isso de forma clara: de um lado há uma página específica sobre slash commands para “controlar o Codex durante sessões interativas”, e do outro uma página separada sobre skills, que define as skills como o formato de criação para reusable workflows.

É por isso que eles existem como commands e não como skills: porque requerem um comportamento previsível, imediato e com semântica estável. Você não quer que o modelo “interprete criativamente” o significado de /permissions. Você quer que ele altere as permissões. Ponto.

O que é uma skill no Codex

Um skill no Codex é outra coisa. É um fluxo reutilizável que ensina ao agente quando aplicar uma abordagem, como pensar em uma tarefa e quais passos deve seguir.

E aqui existe outro detalhe fino, mas importante: a OpenAI diz que o skill é o formato de criação, enquanto o plugin é a unidade instalável ou distribuível. Ou seja, primeiro você desenha o fluxo como um skill; se depois quiser compartilhá-lo ou empacotá-lo melhor, você o transforma em um plugin.

Exemplos claros:

$types
$improve
$owasp
$blog

Ou, se preferir linguagem natural:

use types para auditar este repositório
use improve para revisar este diff

Aqui você não está dizendo ao Codex “altere uma configuração”. Você está dizendo “quando fizer essa tarefa, siga este manual”.

Meu types, por exemplo, não deveria ser um botão. Ele precisa ler o projeto, detectar o idioma, inspecionar modelos, buscar stringly-typed code, decidir se um Optional está sendo usado corretamente ou se está modelando um estado do domínio. Isso exige contexto e discernimento. Este é exatamente o tipo de trabalho que um skill faz bem.

Pelo mesmo motivo, improve faz sentido como skill: não é uma ação determinística. É uma metodologia específica para fazer code review.

Por que no Claude Code parece “a mesma coisa”

Aqui está a armadilha mental.

A documentação atual do Claude Code já não esconde isso. Ela fala sobre skills e diz que você pode invocá-las diretamente com:

/skill-name

Ou seja: no Claude Code, uma parte importante do que você percebe como “fluxo reutilizável” entra pela sintaxe de slash command. A UX junta dois conceitos que no Codex estão separados:

• reutilizar um fluxo
• invocá-lo com /algo

Além disso, o Claude Code mantém seus built-in commands separados:

/help
/compact

E ainda separa outra peça: os subagents, que são assistentes especializados com seus próprios contextos, permissões e system prompts.

Em outras palavras:

• No Claude Code, skills, subagents e commands coexistem, mas as skills podem ser invocadas com /.
• No Codex, os fluxos reutilizáveis existem como skills, e os /commands são reservados para controle explícito da sessão.

É por isso que, vindo do Claude, sua mente rapidamente aprende uma equivalência prática: “se algo é reutilizável, provavelmente eu o lançarei com /algo”. No Codex, esse atalho mental não funciona.

Exemplos concretos: o que deve ser skill e o que não

Coisas que no Codex deveriam ser skill

types

Porque você não quer “executar uma ação”. Você quer aplicar design de tipos sobre uma base de código real.

improve

Porque revisar um diff não é uma operação mecânica. Existe julgamento, contexto e prioridades.

blog

Porque escrever um artigo com tom, estrutura e verificações contra ficções é um fluxo de raciocínio, não um botão.

owasp

Porque uma auditoria de segurança precisa adaptar heurísticas ao stack, ao repositório e aos riscos específicos.

Coisas que no Codex deveriam ser command

codex login

Não há nada para raciocinar. Ou você se autentica ou não.

/model

Alterar o modelo é uma operação do cliente. Não um critério de trabalho.

/permissions

Alterar permissões no meio da sessão é puro controle operacional.

codex resume --last

Retomar uma sessão não é um fluxo cognitivo. É uma ação da aplicação.

O caso mais confuso: coisas híbridas

Existem fluxos intermediários que confundem sua cabeça no início: workflows que você gostaria de lançar com uma sintaxe simples, mas cuja lógica ainda é de skill.

Por exemplo:

• você gostaria de escrever /types
• mas types ainda é conceitualmente um skill

A solução elegante aqui não é “converter o skill em outra coisa”. A solução é envolvê-lo.

Ou seja:

1. Você mantém a inteligência no skill.
2. Cria um plugin ou um command que o invoque com ergonomia de /slash-command.

Assim, você consegue o melhor dos dois mundos: UX de command, cérebro de skill.

A regra de ouro quando você está no Codex

Se você está na dúvida entre command e skill, faça este teste:

Você quer alterar o estado da sessão ou da aplicação?

Então você precisa de um command.

Você quer alterar a forma como o agente aborda uma tarefa?

Então você precisa de um skill.

Em formato de tabela, porque isso sempre ajuda:

E então, qual você deveria usar?

Resposta curta: no Codex você deveria usar skills para conhecimento reutilizável e commands para controle operacional.

Se você vem do Claude Code, seu primeiro instinto será transformar qualquer fluxo reutilizável em /algo. Isso é compreensível, já que o próprio Claude incentiva essa abordagem. Mas no Codex, esse reflexo logo vai te frustrar.

Primeiro desenhe o skill. Se depois você precisar de uma entrada mais prática, envolva-o em um plugin ou command. Nunca faça o contrário.

Porque, se você começar pelo botão antes de definir o procedimento, terminará com uma interface bonitinha que não faz nada útil. E disso, já temos o suficiente nesta indústria.

Fique com esta frase e eu vou: no Claude Code, uma skill pode ser invocada pela porta do /slash-command. No Codex, não. E até que é bom assim.

Quando você entende essa diferença, para de se frustrar com /types e começa a construir fluxos que realmente funcionam com a ferramenta. Já é alguma coisa.