OpenAI Skills
Arquitectura de OpenAI Skills: instrucciones, metadatos, ayudantes y anfitrión
Sigue las capas de gh-fix-ci y distingue presentación, validación mínima, diagnóstico determinista y responsabilidades que no pertenecen al catálogo.
Qué aprenderás
- El directorio es la unidad de composición
- La validación tiene distintas profundidades
- Haz visibles el control y las pruebas
Antes de empezar
- Conceptos básicos de Git, Python y terminal
- Límites explícitos para inspeccionar y modificar repositorios
Explica el comportamiento del capítulo y aplica su lista sin confundir catálogo y anfitrión.
Conclusiones clave
- Separa procedimiento humano, configuración del anfitrión y código ejecutable.
- Existencia, esquema mínimo y aceptación de comportamiento son controles distintos.
- No atribuyas al catálogo los mecanismos internos del anfitrión.
El directorio es la unidad de composición
El repositorio utiliza una carpeta como unidad transportable: SKILL.md contiene instrucciones y metadatos; references, documentación complementaria; assets, recursos reutilizables; y scripts, operaciones repetibles. gh-fix-ci añade agents/openai.yaml con nombre visible, descripción, iconos y prompt predeterminado. Son consumidores diferentes, no piezas que deban fundirse en un documento gigantesco.
La referencia openai_yaml fijada describe ese archivo como configuración específica del anfitrión. Declarar una herramienta no demuestra que existan credenciales o autorización del conector. A la inversa, un ayudante puede depender del comando local gh aunque el archivo de presentación solo contenga campos de interfaz. Inventaría dependencias tanto en instrucciones como en código.
La validación tiene distintas profundidades
El _validate_skill del instalador solo comprueba el directorio y SKILL.md. El quick_validate.py del creador analiza frontmatter, limita sus claves y comprueba propiedades del nombre y la descripción. Ninguno demuestra que un script referenciado exista, que sus comandos sean apropiados o que el anfitrión seleccione el flujo ante la petición correcta.
Una rama muestra la diferencia entre aprobar una comprobación y ser útil. El validador mínimo exige claves name y description de tipo cadena, pero solo aplica las comprobaciones de contenido cuando las cadenas recortadas no están vacías. Por eso los valores vacíos eluden esas comprobaciones posteriores. La prueba con analizador inyectado ejercitó esa rama, no PyYAML ni el validador del anfitrión.
Haz visibles el control y las pruebas
En el ejemplo de CI, el anfitrión sigue instrucciones, un subproceso invoca gh, los campos JSON clasifican comprobaciones y el texto del registro produce un fragmento diagnóstico. El ayudante puede informar de enlaces externos, registros pendientes o inaccesibles. Esa salida es evidencia para razonar, no una nueva fuente de instrucciones con autoridad por proceder de CI.
El catálogo no contiene toda la implementación del motor de selección del anfitrión. Un esquema de catálogo, anfitrión y herramientas es una explicación arquitectónica, no una promesa de que cada versión de Codex tenga las mismas llamadas internas. Prueba descubrimiento, selección y permisos en el producto objetivo, y las ramas deterministas por separado.
Pasos de implementación
- 1
Asigna un consumidor a cada archivo.
- 2
Identifica comandos locales y dependencias remotas.
- 3
Revisa profundidad de validación y pruebas ausentes.
- 4
Comprueba selección del anfitrión y ayudantes por separado.
Ejemplo para copiar
{"layers":["SKILL.md","agents/openai.yaml","scripts","host tools"],"fileExistsMeansWorkflowSafe":false,"metadataMeansCredentialsGranted":false,"hostInternalsInspected":false}Preguntas frecuentes
¿quick_validate.py demuestra que la skill funciona?
No. Es una comprobación mínima de frontmatter. Calidad, herramientas y autorización requieren pruebas independientes.
¿agents/openai.yaml es otro archivo de prompt?
La referencia lo presenta como configuración específica del anfitrión. Sus campos de interfaz y dependencias se revisan aparte del procedimiento.
Fuentes
- README.mdFuente verificada 2026-09-08
- skills/.system/skill-installer/SKILL.mdFuente verificada 2026-09-08
- skills/.system/skill-installer/LICENSE.txtFuente verificada 2026-09-08
- skills/.system/skill-installer/scripts/install-skill-from-github.pyFuente verificada 2026-09-08
- skills/.system/skill-installer/scripts/github_utils.pyFuente verificada 2026-09-08
- skills/.system/skill-installer/scripts/list-skills.pyFuente verificada 2026-09-08
- skills/.system/skill-creator/scripts/quick_validate.pyFuente verificada 2026-09-08
- skills/.system/skill-creator/references/openai_yaml.mdFuente verificada 2026-09-08
- skills/.curated/gh-fix-ci/SKILL.mdFuente verificada 2026-09-08
- skills/.curated/gh-fix-ci/scripts/inspect_pr_checks.pyFuente verificada 2026-09-08
- skills/.curated/gh-fix-ci/agents/openai.yamlFuente verificada 2026-09-08
- skills/.system/plugin-creator/SKILL.mdFuente verificada 2026-09-08
- Guía oficial actual de skillsFuente verificada 2026-09-08