A resposta curta
- 1Coloque a pasta da Skill em
~/.agents/skills/para usá-la em todos os repositórios, ou no.agents/skills/de um repositório para mantê-la ali. - 2O Codex exige
name(até 64 caracteres) edescription(até 1.024) noSKILL.md. - 3Digite
$mais o nome da Skill para rodá-la, ou/skillspara escolher em uma lista. - 4Quer Skills prontas? Explore Skills para Codex que você instala com um comando.
Antes de começar
As Skills funcionam em três lugares: na Codex CLI, na extensão do Codex para IDE e no Codex dentro do app desktop do ChatGPT. Para instalar da Skillry com a CLI, você também precisa de macOS ou Windows e Node.js 22 ou mais recente.
Como adicionar Skills ao Codex
O Codex e a Skillry CLI usam a mesma pasta padrão, ~/.agents/skills/, então você não precisa de nenhuma flag extra. Escolha o caminho que preferir.
- 1
Abra a Skill na Skillry, selecione Copiar prompt de instalação e depois Copiar na janela.
- 2
Cole no Codex e envie. O agente lê as instruções de instalação da Skillry e roda o comando certo por conta própria.
Prompt de instalação Read https://skillry.dev/skills/<slug>/install.md and follow the instructions to install the skill. - 3
Quando o navegador pedir que você aprove um código de dispositivo, aprove.
Você deve ver: o Codex informando a versão que instalou e a pasta que usou, em
~/.agents/skills/.
- 1
Faça login uma vez. Uma janela do navegador abre com um código de dispositivo para você aprovar.
Terminal npx --yes skillry-cli@latest login - 2
Instale. Não precisa de flag, porque a pasta padrão da CLI é a que o Codex lê.
Terminal npx --yes skillry-cli@latest install <slug>Você deve ver:
Installed <slug> <version> to ~/.agents/skills/<slug>
Selecione Baixar ZIP na página da Skill ou use uma pasta de Skill que você conseguiu em outro lugar. Leia o SKILL.md e o que houver em scripts/ antes de instalar, já que o agente segue essas instruções e pode rodar esses scripts. Depois mova a pasta inteira:
mkdir -p ~/.agents/skills
mv ~/Downloads/my-skill ~/.agents/skills/ZIPs costumam descompactar com um nível a mais, como my-skill/my-skill/SKILL.md. O SKILL.md precisa ficar diretamente dentro da pasta da Skill, senão o agente não o encontra.
O Codex também tem um instalador próprio para o catálogo da OpenAI, o $skill-installer. Ele coloca as Skills em ~/.codex/skills/, uma pasta antiga que o Codex ainda lê, então as Skills dos dois instaladores aparecem juntas.
Confira se o Codex a encontrou
Na CLI ou na extensão para IDE, digite /skills, ou digite $ e comece a escrever o nome. No app desktop do ChatGPT, abra Skills na barra lateral. O Codex percebe Skills novas sozinho; se uma não aparecer, reinicie o Codex.
Como rodar uma Skill no Codex
Digite $, o nome da Skill e depois o seu pedido:
$launch-page Parcelo, a parcel-tracking dashboard for small online shopsQuando você souber que funciona, pode pedir com palavras comuns, e o Codex escolhe a Skill cuja descrição combina. Com muitas Skills instaladas, o Codex encurta as descrições para que a lista inteira caiba em cerca de 2% da janela de contexto. Coloque o uso principal na primeira frase da descrição para que ele sobreviva ao corte.
Onde o Codex procura Skills
O Codex reúne Skills de cinco escopos. No dia a dia você vai usar dois: a sua pasta pessoal e a do repositório.
| Escopo | Local |
|---|---|
| Repositório | .agents/skills/ em cada pasta, de onde você inicia o Codex até a raiz do repositório |
| Pessoal | ~/.agents/skills/ |
| Pessoal, antiga | ~/.codex/skills/, ainda lida (não está na documentação, mas confirmada no código-fonte do Codex) |
| Admin | /etc/codex/skills/ |
| Sistema | Incluídas no Codex, como $skill-creator e plan |
O Codex não mescla duas Skills com o mesmo nome. As duas podem aparecer no seletor, então apague ou renomeie a cópia que você não quer.
Skills do Codex vs AGENTS.md
O Codex lê o AGENTS.md no início de cada execução, então ele serve para regras curtas que sempre valem. Uma Skill só carrega quando uma tarefa pede, então serve para procedimentos mais longos que você repete.
Carregada quando necessário
- Uma pasta em
.agents/skills/ - Carrega quando uma tarefa combina ou quando você digita
$name - Boa para trabalho repetível, com vários passos
Lido no início de cada execução
- Primeiro
~/.codex/AGENTS.md, depois um arquivo por pasta, da raiz do repositório até onde você começa - Arquivos mais próximos de você sobrescrevem os anteriores; 32 KiB no total por padrão
- Bom para regras curtas: comandos de teste, estilo de código, limites
Uma divisão que funciona bem: mantenha o AGENTS.md com mais ou menos uma tela de regras e leve tudo o que for passo a passo para Skills. Skills vs instruções se aprofunda no assunto.
Skill do Codex não aparece? Encontre o seu sintoma
Uma Skill que não aparece geralmente está na pasta errada ou foi descompactada um nível abaixo. Encontre na coluna da esquerda o que você está vendo.
| O que você vê | Solução |
|---|---|
Não aparece em /skills | Mova-a para ~/.agents/skills/<name>/ e verifique se há um nível a mais vindo do ZIP |
| Aparece sem descrição | Corrija o frontmatter. O Codex exige name e description |
| Skill de projeto não aparece | Inicie o Codex de dentro do repositório |
$ não encontra nada no app desktop do ChatGPT | Um bug relatado (openai/codex#28505). Verifique /skills, reinicie ou tente uma cópia em ~/.codex/skills/ (ainda não testamos isso) |
Perguntas frequentes
Onde ficam as Skills do Codex?
~/.agents/skills/ para as suas Skills, .agents/skills/ dentro de um repositório e /etc/codex/skills/ para admins. O Codex também lê a antiga ~/.codex/skills/, que é onde o $skill-installer coloca as Skills.
Qual é a diferença entre Skills do Codex e AGENTS.md?
O AGENTS.md é lido no início de cada execução. Uma Skill só carrega quando uma tarefa precisa dela.
Skills do Codex funcionam no ChatGPT?
Skills avulsas funcionam no app desktop do ChatGPT, na Codex CLI e na extensão para IDE. Para usar uma no ChatGPT na web ou no celular, distribua-a dentro de um plugin.
Como crio a minha própria Skill para o Codex?
Peça ao $skill-creator. Ele é uma das Skills de sistema que vêm com o Codex.
Fontes
Este guia ajudou?
