Skills do Codex: onde ficam, como funciona a invocação via $ e como escrever uma

Uma skill é um diretório. O único arquivo obrigatório é o SKILL.md: frontmatter YAML com um name e uma description, seguido por instruções em Markdown. Ao redor dele, três pastas opcionais trazem o peso no qual as instruções podem se apoiar: scripts/ para código executável que a skill orienta o Codex a rodar, references/ para documentação longa demais para estar no corpo do texto, e assets/ para templates. Um arquivo opcional agents/openai.yaml adiciona metadados de UI e dependências para distribuição.

---
name: apply-design-system
description: Apply the project design system when building or editing UI. Use for any component, page, or styling task; reads DESIGN.md and forbids colors, fonts, or spacing outside its tokens.
---

# Apply the design system

1. Read DESIGN.md at the repo root before writing any UI code.
2. Use only its semantic tokens for color, its type scale for text,
   and its spacing scale for layout.
3. If a needed value has no token, stop and say so instead of
   inventing one.

• .agents/skills/ no repositório: skills do projeto, compartilhadas com todos que clonam o repo.
• ~/.agents/skills/: suas skills pessoais, presentes em todos os projetos.
• /etc/codex/skills: skills gerenciadas por admin em máquinas compartilhadas.
• Bundles de sistema que acompanham o produto.
• Skills instaladas: o $skill-installer baixa skills curadas; plugins distribuem além disso.

O local do repositório é o que altera o comportamento da equipe. Uma skill em .agents/skills/ acompanha a base de código: cada colaborador, cada execução de CI, cada novo clone recebe os mesmos procedimentos sem configuração. Contratos de projeto, como a UI é estilizada e como os releases são feitos pertencem a esse local, e não ao diretório home de uma única pessoa.

A invocação explícita é o caso simples: digite $ na CLI do Codex e selecione a skill, e ela será carregada independentemente de como sua descrição esteja escrita. O caso interessante é o implícito: o Codex mantém o nome e a descrição de cada skill disponíveis e carrega o corpo completo quando julga que sua solicitação corresponde. Esse julgamento só será tão bom quanto a descrição, o que torna a descrição a verdadeira interface. "Use para qualquer componente, página ou tarefa de estilização" fornece verbos e situações para o matcher vincular; "ajudante de design" não fornece nada.

O Codex lê o AGENTS.md em cada execução: ele contém as ordens permanentes do projeto, comandos de build, convenções, restrições, e cada linha dele consome tokens em cada solicitação. As skills são o contrato oposto: custo quase zero enquanto inativas, procedimentos completos quando relevantes. A divisão que funciona é: regras curtas no AGENTS.md, procedimentos longos em skills e artefatos duráveis (arquivos de tokens, DESIGN.md, schemas) no repo, onde ambos podem apontar. A taxonomia completa de arquivos, incluindo onde ficam o CLAUDE.md e o DESIGN.md, está em CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

A skill de exemplo acima tem nove linhas de instrução, e essa é a sua força. Tudo o que ela impõe vive em um único artefato: um DESIGN.md na raiz do repo contendo o sistema real, design tokens semânticos para light e dark mode, a escala tipográfica, espaçamentos, motivos e regras de proibição. O Codex é um implementador forte, mas sem memória visual entre sessões; o arquivo é a memória. Skills cheias de adjetivos ("limpo, moderno, consistente") não fazem nada, porque não há nada contra o qual checar o trabalho. Uma skill que aponta para um arquivo com valores exatos transforma cada decisão de estilização em uma consulta.

npx --yes identityforge@latest apply ambient-sage

The SKILL.md convention grew into an open agent-skills standard: Claude Code discovers the same shape under .claude/skills/, and Cursor's Agent Skills load the same way next to its Rules. Discovery paths and invocation syntax differ per tool; the anatomy and the description-driven trigger do not. Write skills that reference artifacts in your repository rather than one tool's internals and they transfer almost verbatim; the Claude Code side of the same story is in Claude Code skills, explained.