Codex CLI Skills

Los Skills son el mecanismo de extensión de Codex CLI que te permite crear flujos de trabajo personalizados y tareas automatizadas. Mediante los skills, puedes definir cómo se comporta Codex en escenarios específicos.


¿Qué es un skill?

Un skill es un patrón de comportamiento configurable que le indica a Codex cómo manejar tipos específicos de tareas. Puedes crear tus propios skills para:

Codex 技能系统

  • Automatizar tareas comunes de desarrollo
  • Definir flujos de procesamiento para dominios específicos
  • Personalizar los estándares de revisión de código
  • Crear plantillas y reglas específicas de proyectos

El sistema de skills permite que Codex se adapte a las necesidades de diferentes proyectos y flujos de trabajo, como si hubieras asignado un asistente de desarrollo dedicado a tu equipo.


Directorio de skills

Codex carga los skills desde las siguientes ubicaciones:

UbicaciónDescripción
~/.codex/skills/Directorio global de skills, disponible para todos los proyectos
{项目目录}/.codex/skills/Directorio de skills a nivel de proyecto
Configurar el directorio especificadoEspecificado mediante skills.directory en config.toml

Configurar el directorio de skills

Personalizar el directorio de skills

[skills]
enabled = true
directory = "~/my-codex-skills"

Estructura de archivos de los skills

Cada skill es una carpeta independiente que contiene los siguientes archivos:

skill-name/
├── skill.md          # 技能定义文件(必需)
└── (可选的辅助文件)

Formato del archivo skill.md

Ejemplo de definición de skill

---
name: Revisión de código
description: Realizar una revisión de código exhaustiva y proporcionar sugerencias de mejora
trigger: /review
---

# Skill de revisión de código

Cuando el usuario solicite una revisión de código, ejecuta los siguientes pasos:

## Estándares de revisión

1. Legibilidad del código
2. Problemas de rendimiento
3. Riesgos de seguridad
4. Cumplimiento de mejores prácticas
5. Cobertura de pruebas

## Formato de salida

Proporciona el siguiente informe estructurado:
- Lista de problemas (ordenados por severidad)
- Sugerencias de mejora
- Puntuación del código (1-10)

Metadatos del skill

Cada archivo de skill debe incluir metadatos en formato YAML al principio:

CampoTipoDescripciónObligatorio
namestringNombre del skillSí
descriptionstringDescripción del skillSí
triggerstringPalabras clave de activaciónno

Cuando tu entrada coincide con el trigger del skill, Codex utiliza automáticamente ese skill para procesar la tarea.


Crear un skill personalizado

Creemos un skill sencillo como ejemplo:

Paso 1: Crear el directorio del skill

Crear la carpeta del skill

mkdir -p ~/.codex/skills/Generar pruebas

Paso 2: Escribir la definición del skill

Crear skill.md

---
name: Generar pruebas
description: Generar pruebas unitarias para el código
trigger: pruebas
---

# Skill de generación de pruebas

Cuando el usuario solicite generar pruebas, ejecuta los siguientes pasos:

## Pasos

1. Analizar la funcionalidad del código existente
2. Identificar los casos límite que necesitan pruebas
3. Elegir el marco de pruebas adecuado
4. Generar casos de prueba

## Estándares de prueba

- La cobertura debe incluir casos normales, casos límite y casos de error
- Cada caso de prueba debe ser independiente y no depender del orden de ejecución de otras pruebas
- Utilizar una nomenclatura clara para las funciones de prueba

## Formato de salida

Genera código de prueba ejecutable directamente e incluye los datos de prueba necesarios.

Paso 3: Usar el skill

Ahora, cuando ingreses contenido relacionado con 'pruebas', Codex utilizará automáticamente este skill:

Activar el skill

# Estas entradas activarán el skill 'Generar pruebas'
Ayúdame a generar pruebas para esta función
Por favor, prueba este módulo

Skills integrados

Codex incluye algunos skills de uso común:

Nombre del skillPalabras de activaciónDescripción
Revisión de códigoreview, revisiónRealizar una revisión de código y proporcionar sugerencias de mejora
Depuracióndebug, depurarAyuda a localizar y corregir problemas
Refactorizaciónrefactor, refactorizarOptimizar la estructura del código sin cambiar la funcionalidad
Documentacióndoc, documentaciónGenerar documentación de código

Puedes sobrescribir el comportamiento de los skills integrados y crear versiones que se ajusten a las necesidades del proyecto.


Prioridad de los skills

Cuando varios skills coinciden, Codex elige según la siguiente prioridad:

  1. Coincidencia exacta (palabras de activación idénticas)
  2. Coincidencia por inclusión (la entrada contiene la palabra de activación)
  3. Coincidencia semántica (la IA evalúa la relevancia)

Forzar el uso de un skill específico

Puedes forzar el uso de un skill mediante un comando de barra:

Forzar el uso de un skill

# Comando para usar un skill
@skill-name tu descripción de la tarea

Configuración avanzada de skills

Activación condicional

Puedes configurar que el skill se active bajo condiciones específicas:

Ejemplo de activación condicional

---
name: Skill de Python
description: Procesamiento específico para proyectos Python
trigger: python
when:
  file_pattern: "*.py"
  directory: "src/"
---

# Skill para proyectos Python

Este skill solo se aplica al manejar archivos Python.

Tareas de múltiples pasos

Los skills pueden definir flujos complejos de varios pasos:

Skill de múltiples pasos

---
name: Desarrollo completo de funcionalidad
description: Flujo completo desde los requisitos hasta la implementación
trigger: desarrollar funcionalidad
---

# Flujo de desarrollo completo de funcionalidad

## Fase 1: Análisis de requisitos
- Comprender los requisitos funcionales
- Identificar casos límite
- Diseñar las estructuras de datos

## Fase 2: Diseño
- Diseñar la estructura de funciones/clases
- Definir las interfaces
- Seleccionar los algoritmos

## Fase 3: Implementación
- Escribir el código
- Añadir comentarios
- Escribir la documentación

## Fase 4: Pruebas
- Escribir pruebas unitarias
- Verificar casos límite
- Comprobar la cobertura

## Fase 5: Commit
- Crear un commit de Git
- Escribir el mensaje de commit

Mejores prácticas para skills

Convenciones de nomenclatura

  • Utiliza nombres claros y descriptivos
  • El nombre debe expresar la función del skill
  • Evita usar nombres en chino (pueden causar problemas de codificación)

Selección de palabras de activación

  • Elige palabras clave de uso común
  • Evita palabras de activación demasiado amplias
  • Considera la forma natural de expresión del usuario

Granularidad de los skills

  • Mantén una única responsabilidad por habilidad
  • Una habilidad resuelve un tipo de problema
  • Los flujos complejos se pueden implementar mediante combinaciones de habilidades
Una buena habilidad debe hacer que el usuario sienta que "Codex entiende mis necesidades", en lugar de tener que aprender una sintaxis especial.

Gestionar skills

Listar los skills disponibles

Ver la lista de skills

# Ingresa en Codex
/skills

Deshabilitar un skill

Si no deseas usar una habilidad, puedes eliminar el archivo correspondiente o moverlo a otro directorio.

Actualizar un skill

Después de modificar el archivo de habilidad, debes reiniciar Codex para que surta efecto.


Biblioteca de ejemplos de skills

OpenAI ofrece oficialmente algunas habilidades predefinidas para que las consultes y uses:

Visita el repositorio de GitHub para ver más ejemplos:https://github.com/openai/codex/tree/main/skills


Preguntas frecuentes

Q: ¿El skill no se activa?

Verifica que el formato de metadatos del archivo de habilidad sea correcto, asegúrate de que el encabezado YAML tenga el formato correcto y que el archivo termine con.mdfinal.

Q: ¿Cómo depurar un skill?

Se puede usar en Codex/debugel comando para ver los detalles de coincidencia de habilidades.

Q: ¿Los skills afectan el comportamiento normal de Codex?

Las habilidades solo proporcionan pautas; Codex aún tomará decisiones de forma independiente. Si una habilidad no está configurada correctamente, Codex utilizará el comportamiento predeterminado.

Otras extensiones