Skills de Codex: dónde residen, cómo funciona la invocación con $ y cómo escribir una

Un skill es un directorio. El único archivo obligatorio es SKILL.md: frontmatter YAML con un name y una description, seguido de instrucciones en Markdown. A su alrededor, tres carpetas opcionales aportan el peso en el que las instrucciones pueden apoyarse: scripts/ para código ejecutable que el skill indica a Codex que ejecute, references/ para documentación demasiado extensa para incluirla en línea, y assets/ para plantillas. Un archivo opcional agents/openai.yaml añade metadatos de UI y dependencias para su distribución.

---
name: apply-design-system
description: Apply the project design system when building or editing UI. Use for any component, page, or styling task; reads DESIGN.md and forbids colors, fonts, or spacing outside its tokens.
---

# Apply the design system

1. Read DESIGN.md at the repo root before writing any UI code.
2. Use only its semantic tokens for color, its type scale for text,
   and its spacing scale for layout.
3. If a needed value has no token, stop and say so instead of
   inventing one.

• .agents/skills/ en el repositorio: skills del proyecto, compartidos con todos los que lo clonen.
• ~/.agents/skills/: sus skills personales, presentes en cada proyecto.
• /etc/codex/skills: skills gestionados por el administrador en máquinas compartidas.
• Bundles del sistema que se distribuyen con el producto.
• Skills instalados: $skill-installer descarga los seleccionados; los plugins se distribuyen más allá de eso.

La ubicación del repositorio es la que cambia el comportamiento del equipo. Un skill en .agents/skills/ viaja junto con el código fuente: cada colaborador, cada ejecución de CI y cada clonación nueva recibe los mismos procedimientos sin configuración previa. Los contratos del proyecto, cómo se aplica el estilo a la UI y cómo se realizan los lanzamientos pertenecen allí, en lugar del directorio personal de alguien.

La invocación explícita es el caso sencillo: escriba $ en la CLI de Codex y seleccione el skill, y este se cargará independientemente de lo que diga su descripción. El caso interesante es el implícito: Codex mantiene disponibles el nombre y la descripción de cada skill, y carga el cuerpo completo cuando juzga que su solicitud coincide. Ese juicio solo puede ser tan bueno como la descripción, lo que convierte a la descripción en la interfaz real. "Use para cualquier componente, página o tarea de estilizado" ofrece al buscador verbos y situaciones a las que vincularse; "ayudante de diseño" no le ofrece nada.

Codex lee AGENTS.md en cada ejecución: son las órdenes permanentes del proyecto, comandos de compilación, convenciones, restricciones, y cada línea de este se procesa en cada solicitud. Los skills son el contrato opuesto: coste casi nulo mientras están inactivos, procedimientos completos cuando son relevantes. La división que funciona es: reglas cortas en AGENTS.md, procedimientos largos en skills y artefactos duraderos (archivos de tokens, DESIGN.md, esquemas) en el repositorio donde ambos puedan hacer referencia a ellos. La taxonomía completa de archivos, incluyendo dónde se ubican CLAUDE.md y DESIGN.md, se encuentra en CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

El ejemplo de skill anterior tiene nueve líneas de instrucción, y esa es su fuerza. Todo lo que impone reside en un único artefacto: un DESIGN.md en la raíz del repositorio que contiene el sistema real, design tokens semánticos para modo claro y oscuro, la escala tipográfica, el espaciado, los motivos y las reglas de prohibición. Codex es un implementador fuerte pero sin memoria visual entre sesiones; el archivo es la memoria. Los skills llenos de adjetivos ("limpio, moderno, consistente") no sirven de nada, porque no hay nada contra lo que contrastar el trabajo. Un skill que apunta a un archivo con valores exactos convierte cada decisión de estilo en una consulta.

npx --yes identityforge@latest apply ambient-sage

The SKILL.md convention grew into an open agent-skills standard: Claude Code discovers the same shape under .claude/skills/, and Cursor's Agent Skills load the same way next to its Rules. Discovery paths and invocation syntax differ per tool; the anatomy and the description-driven trigger do not. Write skills that reference artifacts in your repository rather than one tool's internals and they transfer almost verbatim; the Claude Code side of the same story is in Claude Code skills, explained.