Cómo escribir y probar patrones para SKILL.md: guía de ingeniería completa

1. Arquitectura y secciones obligatorias de un archivo SKILL.md

Un archivo SKILL.md es un recurso de ingeniería que transforma un modelo de lenguaje de propósito general en un especialista operativo dedicado a resolver una tarea técnica bien delimitada. No reemplaza ni reproduce las reglas globales del proyecto, sino que inyecta conocimientos procedimentales tácticos de alta precisión.

Antes de crear una skill para tu repositorio, audita detenidamente los archivos de instrucciones base del proyecto (AGENTS.md o CLAUDE.md). Estos documentos constituyen la única fuente de verdad sobre protocolos de seguridad críticos, comandos del entorno y directrices de despliegue. El propósito de la skill es enseñar la estructura de ejecución y la maestría procedimental referenciando —nunca duplicando— las invariantes del sistema.

Desglose de las secciones obligatorias

1. Descripción en Frontmatter: El único fragmento que el agente evalúa antes de decidir si carga la skill en su ventana de contexto. Debe redactarse como una condición predictiva («Usar cuando...») y nunca como una etiqueta temática abstracta.
2. Cuándo activar (When to trigger): Explicación técnica detallada en lenguaje natural que enumera intenciones de usuario, errores de terminal u operaciones Git exactas que deben disparar la skill.
3. Procedimiento (Procedure): Secuencia determinista y numerada con comandos locales verificados y rutas de archivos comprobadas en el repositorio.
4. Errores comunes (Pitfalls): Inventario de fallos reales documentados. Cada elemento debe seguir rigurosamente la tríada: Acción incorrecta concreta → Consecuencia técnica directa → Solución exacta validada.

2. Estructura de almacenamiento: sincronización entre Codex y Claude Code

En los entornos de desarrollo modernos, los ingenieros alternan con frecuencia entre diferentes clientes de ejecución (por ejemplo, OpenAI Codex en terminal o IDE y Claude Code). Aunque ambos entornos respetan el estándar abierto de Agent Skills, descubren las skills en rutas de directorio distintas.

Rutas de almacenamiento de archivos de skills para Codex y Claude Code ЗбільшитиRutas de almacenamiento de archivos de skills para Codex y Claude Code

Matriz de almacenamiento según el entorno

3. Criterios de preparación y validación de borradores

Antes de integrar una skill en el repositorio del equipo, audítala con esta rúbrica de ingeniería:

• Disparador falsable: Puedes formular inmediatamente al menos dos consultas de usuario cercanas dentro del mismo dominio técnico que NO deben activar la skill.
• Comandos auditados: Cada comando de shell figura en la sección de Comandos Locales del archivo AGENTS.md.
• Errores basados en evidencia: Cada entrada en Pitfalls responde a un incidente técnico real vivido previamente, no a consejos vagos como «ten cuidado».
• Economía de contexto: Leer el archivo completo toma menos de 3 minutos (menos de 500 líneas).
• Cero duplicación de invariantes: Ningún párrafo copia directrices globales ya establecidas en AGENTS.md.

4. Patrones de composición: enrutadores, referencias y cadenas

Los flujos de trabajo de ingeniería rara vez caben en un único archivo estático. Concentrar todo un dominio en una macro-skill monolítica satura la ventana de contexto y provoca desviaciones en las instrucciones. Utiliza estos tres patrones probados de composición arquitectónica:

Patrón 1: Enrutador de entrada (Entry Router)

Una skill de enrutamiento de alto nivel mantiene el mapa arquitectónico y delega la ejecución en sub-skills especializadas sin ejecutar directamente los pasos:

Patrón 2: Archivos de referencia (Reference Files)

El archivo principal SKILL.md define el flujo operativo central, mientras que los esquemas exhaustivos, gramáticas y listas de comprobación se extraen a la carpeta references/:

Patrón 3: Cadenas de skills (Skill Chains)

Las skills se enlazan secuencialmente como hitos del ciclo de vida técnico mediante relatedPaths o indicaciones directas en markdown:

5. Estrategias de refactorización: cuándo dividir y cuándo fusionar skills

Saber cuándo descomponer o consolidar skills preserva la higiene y estabilidad del sistema a largo plazo.

6. Contrato de versionado y compilación de skills insignia

En repositorios empresariales, las skills se organizan en tres niveles según sus requisitos de distribución y compilación:

Matriz de compilación y almacenamiento para los diferentes niveles de skills ЗбільшитиMatriz de compilación y almacenamiento para los diferentes niveles de skills

7. Metodología de pruebas: cinco comprobaciones esenciales de calidad

Redactar las instrucciones es solo una parte del trabajo. Antes de poner una skill en producción, sométela a este protocolo de pruebas secuencial de cinco fases:

Detalle del protocolo de ejecución

1. Prueba de disparadores (Trigger Probe): Diseña 3 prompts que deban activar la skill y 2 prompts limítrofes que deban ignorarla. Verifica que la descripción en el frontmatter delimite con precisión ambos casos.
2. Ejecución procedimental (Procedure Walk-Through): Ejecuta cada comando manualmente en una terminal real. Si en algún paso te preguntas «¿cómo se configura esto?», falta un prerrequisito fundamental en la skill.
3. Auditoría de fallos (Pitfall Audit): Comprueba que cada modo de fallo documente una incidencia real previa, acompañada del comando exacto para resolverla.
4. Prueba de alcance (Scope Test): Sintetiza el objetivo de la skill en una única frase. Si necesitas usar la conjunción «y además», divide el procedimiento en dos skills separadas.
5. Verificación de obsolescencia (Staleness Check): Valida que cada comando CLI, dependencia de paquetes y ruta de archivos coincida exactamente con el estado actual del repositorio.

8. Anatomía de antipatrones: cómo distinguir una skill de producción de un borrador

Comparar las deficiencias comunes frente a los estándares de producción agiliza la auditoría previa:

9. Prevención de fallos críticos: evitar la duplicación de AGENTS.md

El error más destructivo al crear skills es duplicar normas globales del proyecto (como convenciones de formato, estilos de commit o estrategias de ramas) dentro de SKILL.md.

Preparación defensiva de cambios en Git

Al programar operaciones de staging en una skill, protégete contra rutas inexistentes que cancelen silenciosamente la operación en Git:

10. Lista de verificación de preparación para producción

Antes de confirmar cualquier skill personalizada en el control de versiones, valida cada elemento:

• Sincronizada simultáneamente en .agents/skills/<name>/SKILL.md y .claude/skills/<name>/SKILL.md.
• La description del frontmatter inicia con «Usar cuando...» y fija límites claros de activación.
• Superó con éxito las 5 fases de prueba (Disparadores, Procedimiento, Fallos, Alcance y Obsolescencia).
• Libre de términos ambiguos («según corresponda», «si es necesario»).
• Cada comando CLI ha sido probado en un shell de desarrollo real.
• Las normas globales referencian AGENTS.md sin duplicar texto.