Sistema de habilidades de Codex Agent Skills
Agent Skills (habilidades de agente) es el mecanismo de extensión de tareas de Codex. Al empaquetar instrucciones, recursos y scripts opcionales en paquetes de habilidades estandarizados, permite que Codex ejecute flujos de trabajo específicos de manera fiable.
Agent Skills (habilidades de agente) se basan en una carpeta que debe contener elSKILL.mdarchivo `SKILL.md`. Dicho archivo debe incluir como mínimo metadatos como nombre y descripción, así como instrucciones que indiquen al agente de IA cómo completar una tarea específica. El paquete de habilidades también puede integrar scripts, documentos de referencia, plantillas y otros recursos.
my-skill/ ├── SKILL.md # 必备文件：元数据 + 执行指引 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：模板、各类资源文件 └── ... # 其他额外文件与目录
Explicación de términos
- AI agents: Agente inteligente de IA (traducción común en la industria)
- Agent Skills: Habilidades de agente (concepto exclusivo, conservar la denominación fija)
- metadata: Metadatos
- workflows: Proceso de negocio / flujo de ejecución
¿Qué son las Agent Skills?
Skills son un formato de escritura para flujos de trabajo reutilizables.
Cada Skill es esencialmente un directorio que contiene unSKILL.mdarchivo `SKILL.md`. Codex lee las instrucciones en él y las ejecuta paso a paso.
Puedes entender Skill como un "procedimiento operativo estándar" escrito para Codex: define claramente qué hacer, cuándo hacerlo y cómo hacerlo, y Codex podrá activarlo automáticamente en el momento adecuado, o ejecutarlo cuando lo invoques explícitamente.
Skills son el "formato de escritura" y Plugins (complementos) son el "formato de distribución". Primero diseña el flujo de trabajo con Skills y, cuando necesites distribuirlo a otros desarrolladores, empaquétalo como Plugin.
Skills están disponibles en Codex CLI, la extensión de IDE y la aplicación Codex.
Puedes ver o crear Skills en el complemento:
Codex incluyeSkill Creator, al hacer clic en el icono de la figura anteriorCreat skillse abrirá la ventana de creación de Skill, donde podemos decirle directamente qué Skill crear.
Ver Skills instalados:
Cómo funcionan las habilidades
Codex utiliza elmecanismo de divulgación progresiva (Progressive Disclosure)para gestionar la ventana de contexto, evitando que la carga única de todo el contenido de las habilidades ocupe espacio en el prompt.
Proceso de carga progresiva
Al iniciarse, Codex solo carga el nombre, la descripción y la ruta de archivo de cada habilidad como lista inicial.
Solo cuando Codex decide usar una habilidad, carga elSKILL.mdcontenido completo de las instrucciones.
Para no ocupar espacio en el prompt, el número de caracteres de la lista inicial de habilidades se limita aaproximadamente el 2%de la ventana de contexto del modelo, u 8,000 caracteres cuando la ventana de contexto se desconoce.
Si hay demasiadas habilidades instaladas, Codex primero acorta las descripciones; si aún así se supera el límite, algunas habilidades pueden no aparecer en la lista inicial y Codex mostrará una advertencia.
Este límite de presupuesto se aplica solo a la lista inicial de habilidades. Una vez que Codex selecciona una habilidad, sigue leyendo el archivo SKILL.md completo de esa habilidad.
Dos formas de activación
Codex admite dos formas de activación de habilidades:
Invocación explícita
Referencia directa a la habilidad en el prompt. En CLI o IDE, usa el/skillscomando o introduce el$símbolo para especificar una habilidad.
En la invocación explícita, Codex no necesita hacer ninguna coincidencia; carga directamente el SKILL.md completo y lo ejecuta.
Coincidencia implícita
Cuando la descripción de la tarea que envías coincide con eldescriptioncampo `description` de una habilidad, Codex la selecciona automáticamente.
La precisión de la coincidencia implícita depende por completo de la calidad de redacción del campo description.
Al redactar description, coloca al principio los casos de uso principales y las palabras clave de activación; así, incluso si la descripción se acorta, Codex podrá coincidir correctamente.
Estructura del directorio de habilidades
Un Skill es un directorio que contiene unSKILL.mdarchivo `SKILL.md`. Puede incluir scripts opcionales, documentos de referencia, archivos de recursos y configuración de metadatos.
my-skill/
├── SKILL.md # 必备项：使用指引 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、各类资源
└── agents/
└── openai.yaml
Las responsabilidades de cada archivo/directorio son las siguientes:
| Archivo/Directorio | ¿Obligatorio? | Descripción |
|---|---|---|
| SKILL.md | Obligatorio | Archivo de instrucciones principal de la habilidad; debe contener el camponameydescription`description`. |
| scripts/ | Opcional | Contiene código ejecutable, para escenarios que requieren un comportamiento determinista o la invocación de herramientas externas. |
| references/ | Opcional | Contiene documentos de referencia adicionales, para que Codex los consulte al ejecutar la habilidad. |
| assets/ | Opcional | Contiene archivos de recursos estáticos como plantillas, imágenes, etc. |
| agents/openai.yaml | Opcional | Configura metadatos de interfaz de usuario, políticas de invocación y declaraciones de dependencias de herramientas. |
Inicio rápido: crea tu primera habilidad
Se recomienda usar el creador de habilidades integrado para generar rápidamente el esqueleto de una habilidad.
Crear con skill-creator
En Codex, introduce el siguiente comando para iniciar el proceso de creación interactivo:
Ejemplo
$skill-creator
El creador preguntará sucesivamente lo siguiente:
| Paso | Pregunta | Descripción |
|---|---|---|
| 1 | ¿Qué hace esta habilidad? | Define la tarea que debe completar la habilidad. |
| 2 | ¿Cuándo se activa? | Determina si se activa por invocación explícita o coincidencia implícita. |
| 3 | ¿Solo instrucciones o incluye scripts? | Por defecto se recomienda el modo solo instrucciones, que es conciso y fácil de mantener. |
Creación manual
También puedes crear manualmente el directorio de la habilidad y el archivo SKILL.md:
Ejemplo
name: my-skill
description: Explica cuándo debe activarse esta habilidad y cuándo no.
---
Codex llevará a cabo la tarea siguiendo las siguientes instrucciones de la habilidad.
Codex detecta automáticamente los cambios en los archivos de habilidades. Si la habilidad no surte efecto inmediatamente después de actualizarse, reinicia Codex.
Explicación de configuración
Ubicación de almacenamiento de habilidades
Codex lee las habilidades desde cuatro ámbitos: nivel de repositorio, nivel de usuario, nivel de administrador y nivel de sistema.
Para el nivel de repositorio, Codex escanea desde el directorio de trabajo actual hasta la raíz del repositorio, buscando el.agents/skillsdirectorio.
Si dos habilidades tienen el mismoname`name`, Codex no las fusiona; ambas aparecerán en el selector de habilidades.
| Alcance | Ruta de almacenamiento | Escenario de aplicación |
|---|---|---|
| REPO | $CWD/.agents/skills | Habilidades en el directorio de trabajo actual, adecuadas para habilidades compartidas por equipo en módulos o microservicios específicos. |
| REPO | $CWD/../.agents/skills | Habilidades en directorios superiores, adecuadas para áreas compartidas en estructuras de directorios anidados. |
| REPO | $REPO_ROOT/.agents/skills | Habilidades en la raíz del repositorio, adecuadas como habilidades base compartidas por todos los subdirectorios de todo el repositorio. |
| USER | $HOME/.agents/skills | Habilidades personales del usuario, adecuadas para habilidades que el usuario puede usar en cualquier repositorio. |
| ADMIN | /etc/codex/skills | Habilidades compartidas a nivel de máquina o contenedor, adecuadas para scripts de SDK, automatización y habilidades predeterminadas del administrador. |
| SYSTEM | Empaquetadas integradas por OpenAI | Habilidades integradas para un público amplio, como skill-creator y la habilidad plan; todos los usuarios pueden usarlas al iniciar Codex. |
Codex admite enlaces simbólicos en directorios de habilidades; al escanear, sigue el objetivo del enlace simbólico.
Las rutas anteriores son para desarrollo y descubrimiento locales. Si necesitas distribuir habilidades a usuarios fuera de un único repositorio, o empaquetarlas junto con la integración de una aplicación, usa el mecanismo de Plugins.
Habilitar y deshabilitar habilidades
En~/.codex/config.tomlEn el uso[[skills.config]]de las opciones de configuración, es posible deshabilitar una habilidad sin eliminar archivos:
Ejemplo
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
Después de modificar el archivo de configuración, es necesario reiniciar Codex para que surta efecto.
Configuración de metadatos opcional
Enagents/openai.yamlse puede configurar metadatos de interfaz de usuario, políticas de invocación y declaraciones de dependencias de herramientas para la habilidad:
Ejemplo
# Configuración de interfaz: controla cómo se muestra la habilidad en la aplicación Codex
interface:
display_name: "Nombre para mostrar orientado al usuario"
short_description: "Descripción breve orientada al usuario"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Indicación periférica opcional para usar con la habilidad"
# Configuración de políticas: controla el comportamiento de invocación de la habilidad
policy:
allow_implicit_invocation: false # Establecer en false para deshabilitar la coincidencia implícita
# Configuración de dependencias: declara las herramientas necesarias para la habilidad
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs" # Nombre del servidor MCP
description: "OpenAI Docs MCP server"
transport: "streamable_http" # Protocolo de transporte
url: "https://developers.openai.com/mcp" # Dirección del servicio MCP
allow_implicit_invocationel valor predeterminado estrue. Al establecerlo enfalse, Codex no invocará implícitamente la habilidad según las indicaciones del usuario, pero la invocación explícita$skillsigue siendo válida.
| Opción de configuración | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
| interface.display_name | Cadena | Vacío | Nombre mostrado en la aplicación Codex |
| interface.short_description | Cadena | Vacío | Descripción breve mostrada en la aplicación Codex |
| interface.icon_small | Ruta | Vacío | Ruta del icono pequeño (formato SVG) |
| interface.icon_large | Ruta | Vacío | Ruta del icono grande (formato PNG) |
| interface.brand_color | Valor de color | Vacío | Color de marca, utilizado para la visualización de la interfaz |
| interface.default_prompt | Cadena | Vacío | Indicación periférica predeterminada al usar la habilidad |
| policy.allow_implicit_invocation | Booleano | true | Si se permite que Codex coincida e invoque implícitamente la habilidad |
| dependencies.tools | Arreglo | Vacío | Declara las herramientas MCP de las que depende la habilidad; cada elemento debe especificar type, value, description, etc. |
Distribución e instalación de habilidades
Distribuir habilidades mediante Plugins
Las carpetas de habilidades directas son adecuadas para la escritura local y los flujos de trabajo a nivel de repositorio.
Si necesitas distribuir habilidades reutilizables, agrupar varias habilidades o publicar habilidades junto con integraciones de aplicaciones, debes empaquetarlas comoPlugin。
Un Plugin puede contener una o más habilidades, y también puede empaquetar opcionalmente asignaciones de aplicaciones, configuraciones de servidores MCP y recursos de presentación.
Instalar habilidades destacadas
Mediante$skill-installerse pueden instalar habilidades seleccionadas, además de las habilidades integradas, en el entorno local de Codex.
Por ejemplo, instala$linearla habilidad:
Ejemplo
$skill-installer linear
También puedes descargar habilidades desde otros repositorios mediante skill-installer.
Codex detecta automáticamente las habilidades recién instaladas; si no aparecen de inmediato, reinicia Codex.
skill-installer es adecuado para configuraciones locales y experimentos. Si deseas distribuir de forma reutilizable tus propias habilidades, prioriza el mecanismo de Plugins.
Mejores prácticas
| Principio | Descripción | Escenario aplicable |
|---|---|---|
| Una habilidad hace solo una cosa | Mantén cada habilidad con una única responsabilidad; evita que la habilidad asuma demasiadas tareas no relacionadas | Todas las habilidades deben seguir |
| Las instrucciones tienen prioridad sobre los scripts | Si un proceso puede describirse con instrucciones, no escribas scripts, a menos que se necesite un comportamiento determinista o invocar herramientas externas | Se recomienda el modo de solo instrucciones en la mayoría de los escenarios |
| Las instrucciones usan modo imperativo | Redacta los pasos en modo imperativo, especificando la entrada y la salida de cada paso | Al redactar las instrucciones de SKILL.md |
| Prueba el efecto de coincidencia de description | Prueba con indicaciones reales si la habilidad se activa correctamente, asegurando la precisión de description | Después de escribir la habilidad |
| Anteponer las palabras clave de activación principales | Coloca los escenarios de uso clave y las palabras de activación al inicio de description, asegurando que siga coincidiendo después de acortarse | Cuando description pueda truncarse |
Preguntas frecuentes
¿La actualización de la habilidad no se ha aplicado?
Codex detecta automáticamente los cambios en los archivos de habilidades.
Si la habilidad no aparece en la lista después de la actualización, reinicia Codex.
¿Qué pasa si dos habilidades tienen el mismo nombre?
Codex no fusiona habilidades con el mismo nombre; ambas aparecerán en el selector de habilidades.
Se recomienda evitar usar los mismos nombres de habilidades en diferentes ámbitos para evitar confusiones.
¿Qué hacer si la coincidencia implícita es incorrecta?
Primero verificadescriptionsi describe claramente los escenarios de uso y los límites de la habilidad.
Antepón las palabras de activación principales; evita que la información clave aparezca en la segunda mitad de la descripción.
Si no se necesita la coincidencia implícita, puedesagents/openai.yamlestablecerallow_implicit_invocationenfalse。
¿Cuándo usar Skills y cuándo usar Plugins?
Skills es un formato de escritura, adecuado para el desarrollo local y el intercambio en equipo dentro de un repositorio.
Cuando necesites distribuir habilidades a otros desarrolladores, empaquetar múltiples habilidades o publicarlas junto con integraciones de aplicaciones, usa el formato de Plugins.
¿Cómo manejar si la lista inicial de habilidades se trunca?
Simplifica la description de cada habilidad para que sea breve y precisa.
Asegúrate de que las palabras de activación más importantes aparezcan al inicio de description, para que pueda coincidir correctamente incluso si se acorta.
Para las habilidades que no se usan con frecuencia en la tarea actual, puedes considerar deshabilitarlas temporalmente.
Otras extensiones