Al organizar las habilidades del Codex, la gente suele quedarse estancada en dos preguntas:

• ¿Cuál es la diferencia entre ~/.codex/skills y project/.codex/skills?
• ¿Por qué existe una habilidad en el directorio pero no aparece en la sesión actual?

Aquí está la versión corta.

La diferencia

La forma más sencilla de recordarlo:

• ~/.codex/skills es tu biblioteca de habilidades global
• project/.codex/skills es la biblioteca de habilidades local para ese repositorio

~/.codex/skills

Úselo para:

• Habilidades que reutilizas personalmente en todos los proyectos.
• flujos de trabajo generales que no están vinculados a un repositorio específico
• flujos de trabajo que claramente pertenecen a sus propios hábitos

Por ejemplo:

• post-reescritura
• post-traducir -git-commit-push -hugo-rsync-deploy
• bilibili-transcriptor-de-voz

El rasgo clave de este tipo de habilidad es: todavía tiene sentido fuera del proyecto actual.

proyecto/.codex/skills

Úselo para:

• flujos de trabajo que solo se aplican a este repositorio
• reglas estrechamente acopladas a la estructura, scripts o plantillas del proyecto actual
• Habilidades que deben ser compartidas por el equipo.

Por ejemplo:

• un flujo de trabajo de publicación específico para este repositorio
• una plantilla de generación que solo funciona en este proyecto
• pasos de automatización estrechamente vinculados a scripts de proyectos privados

El rasgo clave de este tipo de habilidad es: deja de ser significativo una vez que sale de este repositorio.

Cuándo utilizar habilidades globales y cuándo utilizar habilidades de proyecto

Esta regla general es suficiente:

• Si se trata de tus hábitos personales, ponlo en ~/.codex/skills
• Si se trata de reglas del repositorio, colóquelo en project/.codex/skills
• Si se puede reutilizar en todos los proyectos, prefiera global
• Si debe ser compartido por varias personas y evolucionar con el repositorio, prefiera el nivel de proyecto

El repositorio actual

Basado en el estado actual:

• su máquina tiene ~/.codex/skills
• este repositorio no tiene .codex/skills

Así que ahora mismo dependes principalmente de las habilidades globales.

Eso significa que flujos de trabajo como “post-reescritura”, “post-traducción” y “git-commit-push” son actualmente más bien parte de su flujo de trabajo personal, no algo incluido explícitamente con este repositorio.

Por qué existe una habilidad en el disco pero puede no aparecer en la sesión actual

Hay dos cosas diferentes aquí:

• Existente en el disco: el archivo de habilidad existe en un directorio local
• Expuesto a la sesión: la sesión actual lo registró en la lista de habilidades disponibles

Estos no son lo mismo.

Entonces esto puede suceder:

• ya existe una habilidad en ~/.codex/skills
• pero no aparece en la lista después de /

Por lo general, esto no significa que la habilidad esté rota. Más a menudo significa: la sesión actual no la ha vuelto a indexar.

Cómo hacer que una habilidad esté disponible en la sesión actual

La lista de verificación práctica es breve.

1. Colóquelo en el directorio correcto

Mundiales:

1

~/.codex/skills/<skill-name>/SKILL.md

Nivel de proyecto:

1

project/.codex/skills/<skill-name>/SKILL.md

2. Haga que el encabezado SKILL.md sea reconocible

Como mínimo, necesita:

1
2
3
4

---
name: your-skill-name
description: What this skill does
---

3. Abra una nueva sesión después de crearla o editarla

En muchos casos, una habilidad no aparece porque la sesión actual ya fijó su lista de habilidades disponibles cuando comenzó.

Entonces, si crea una habilidad en medio de una sesión, es posible que ya exista en el disco, pero es posible que esta sesión no la reconozca.

El flujo de trabajo más confiable es:

1. Ponga en práctica la habilidad
2. Finalizar la sesión actual
3. Vuelva a ingresar al proyecto.
4. Abre una nueva sesión
5. Compruebe si aparece debajo de /

4. Implemente las habilidades para el proyecto antes de comenzar

Si desea que project/.codex/skills se reconozca de manera más confiable, coloque esas habilidades en el proyecto antes de ingresar al repositorio e iniciar la sesión.

Una última línea

La conclusión más corta es:

• ~/.codex/skills es tu biblioteca de habilidades personales
• project/.codex/skills es la biblioteca de reglas local del repositorio
• una habilidad existente en el directorio no significa que la sesión actual siempre la mostrará
• la solución más común es colocarlo en el directorio correcto, escribir un SKILL.md válido y luego iniciar una nueva sesión