¿Por qué existe una habilidad del Codex en el directorio pero aún no aparece?

Wed, 29 Apr 2026 11:18:00 +0800

Este problema era fácil de pasar por alto: varias habilidades ya estaban ubicadas en ~/.codex/skills, pero después de abrir un nuevo hilo del Codex, la barra lateral todavía mostraba solo un pequeño subconjunto de ellas.

Al principio, parecía un problema de caché o de indexación. La causa real fue más específica: varios archivos SKILL.md comenzaron con una lista de materiales UTF-8. El cargador de habilidades de Codex 0.111.0 no omitió esa secuencia de bytes, por lo que calculó erróneamente que los archivos no tenían contenido YAML válido.

Síntoma

El directorio local contenía estas habilidades:

~/.codex/skills/git-commit-push/SKILL.md
~/.codex/skills/hugo-rsync-deploy/SKILL.md
~/.codex/skills/bilibili-speech-transcriber/SKILL.md
~/.codex/skills/product-cutout-normalize/SKILL.md

Pero después de abrir un hilo nuevo, las habilidades realmente expuestas fueron solo:

1
2

bilibili-speech-transcriber
product-cutout-normalize

En otras palabras, un archivo existente en el disco no significa que la sesión actual pueda cargarlo correctamente. Codex analiza primero la portada de cada SKILL.md. Si el análisis falla, esa habilidad se excluye directamente.

Investigación

Iniciar una nueva sesión con codex exec mostró un error más directo. En VS Code u otros IDE, es posible que estos registros no sean visibles:

1
2

failed to load skill C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md: missing YAML frontmatter delimited by ---
failed to load skill C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md: missing YAML frontmatter delimited by ---

Visualmente, estos archivos parecían tener un encabezado normal:

---
name: post-rewrite
description: ...
---

El verdadero problema estaba en el nivel de bytes.

El comienzo de un archivo fallido fue:

`1`	`EF-BB-BF-2D-2D-2D`

El comienzo de un archivo que se cargó correctamente fue:

`1`	`2D-2D-2D`

2D-2D-2D es ---. El EF-BB-BF anterior es la lista de materiales UTF-8.

Causa

En Codex 0.111.0, el cargador de habilidades espera que el primer byte de SKILL.md sea el primer - en ---.

Si el archivo comienza con una lista de materiales UTF-8, el comienzo real será:

`1`	`BOM + ---`

Entonces, el cargador piensa que el archivo no comienza con el delimitador inicial e informa:

`1`	`missing YAML frontmatter delimited by ---`

El contenido de la habilidad no era incorrecto y el directorio tampoco era incorrecto. Un pequeño detalle de codificación impidió que el analizador reconociera el archivo.

Arreglar

Convierta los archivos SKILL.md afectados a UTF-8 sin BOM.

En PowerShell, esto se puede hacer así:

$paths = @(
  'C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md',
  'C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md',
)

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)

foreach ($p in $paths) {
  $text = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
  [IO.File]::WriteAllText($p, $text, $utf8NoBom)
}

Después del procesamiento, el encabezado del archivo debería cambiar de:

`1`	`EF-BB-BF-2D-2D-2D`

`1`	`2D-2D-2D`

Verificación

Después de reiniciar una sesión del Codex, las habilidades visibles se restauraron en:

git-commit-push-zh
hugo-rsync-deploy
bilibili-speech-transcriber
product-cutout-normalize

Si la barra lateral todavía muestra la lista anterior, cierre la barra lateral o ventana actual del Codex y vuelva a abrir el proyecto. La lista de habilidades generalmente se carga cuando comienza la sesión, por lo que es posible que los cambios realizados en mitad de una sesión no se actualicen inmediatamente.

Una última línea

Este tipo de problema es fácil de confundir con “El Codex no se volvió a indexar” o “la habilidad no se instaló correctamente”.

Al solucionar problemas, verifique primero estas tres cosas:

si SKILL.md está realmente en el directorio correcto
si el archivo tiene un texto inicial --- válido en la parte superior
si el archivo es UTF-8 sin BOM

La clave en este caso fue el tercer punto: el archivo se veía bien, pero su primer byte no era “-”, por lo que Codex no lo trató como una habilidad válida.