Dónde se guardan los Codex Skills: usuario, repositorio y fallos de carga

Codex utiliza .agents/skills como ubicación compartida estándar. Las guías antiguas que trataban ~/.codex/skills y project/.codex/skills como rutas predeterminadas pueden colocar un Skill en el lugar equivocado y confundir la configuración personal con los Skills compartidos.

La regla breve: usa $HOME/.agents/skills para Skills personales reutilizables y .agents/skills dentro del repositorio para sus reglas. Cada Skill necesita un directorio propio y un SKILL.md.

Cuatro scopes de carga

Codex explora desde el directorio de trabajo hacia arriba hasta la raíz del repositorio, por lo que un monorepo puede tener .agents/skills más específicos en subdirectorios. Los Skills del repositorio pueden revisarse con Git. Los de usuario no deberían asumir rutas que solo existen en un proyecto.

Versiones antiguas o plugins todavía pueden mostrar .codex/skills, pero no debe ser la ruta predeterminada para nuevos Skills compartidos. Sigue la documentación actual y la lista que expone la sesión.

Skill mínimo cargable

1
2
3
4

.agents/
└── skills/
    └── verify-build/
        └── SKILL.md

SKILL.md debe comenzar con YAML front matter válido:

1
2
3
4
5
6
7
8

---
name: verify-build
description: Run the repository build and report reproducible failures.
---

# Verify build

Run the documented build command, preserve logs, and do not publish artifacts.

Mantén name estable y distintivo. description explica cuándo se aplica; el cuerpo define pasos, límites y validación.

El archivo existe pero no carga

1. Comprueba la ruta real

Evita una carpeta adicional y confirma que no se llame SKILL.md.txt:

1
2

Get-ChildItem -Force -Recurse .agents\skills
Get-ChildItem -Force -Recurse (Join-Path $env:USERPROFILE '.agents\skills')

2. Comprueba los primeros bytes

Un UTF-8 BOM (EF BB BF) antes de --- puede hacer que un parser estricto muestre missing YAML frontmatter delimited by ---.

1
2
3

$path = '.agents\skills\verify-build\SKILL.md'
$bytes = [IO.File]::ReadAllBytes((Resolve-Path $path))
($bytes[0..([Math]::Min(5, $bytes.Length - 1))] | ForEach-Object { $_.ToString('X2') }) -join '-'

El prefijo correcto es 2D-2D-2D. Si aparece EF-BB-BF-2D-2D-2D, haz una copia y guarda UTF-8 sin BOM:

1
2
3
4

$resolved = (Resolve-Path $path).Path
$content = [IO.File]::ReadAllText($resolved, [Text.Encoding]::UTF8)
$utf8NoBom = [Text.UTF8Encoding]::new($false)
[IO.File]::WriteAllText($resolved, $content, $utf8NoBom)

3. Revisa YAML y nombres duplicados

El front matter debe cerrarse correctamente y los valores complejos con dos puntos pueden necesitar comillas. No supongas que Skills con el mismo nombre en scopes distintos se combinan: renómbralos o conserva solo la copia deseada.

4. Abre una sesión nueva

El descubrimiento suele ocurrir al iniciar la sesión. Después de un cambio abre una sesión nueva y comprueba la lista. No elimines toda la configuración antes de verificar ruta, codificación y YAML.

Lista de aceptación

1. La ruta es .agents/skills/<name>/SKILL.md.
2. El primer byte inicia ---, sin UTF-8 BOM.
3. YAML es válido y contiene nombre estable y descripción clara.
4. No existe otro Skill no deseado con el mismo nombre.
5. Una sesión nueva lo muestra y lo activa según su descripción.

Referencias

• Codex Skills: https://developers.openai.com/codex/skills
• Especificación Agent Skills: https://agentskills.io/