# Cómo escribir y probar patrones para SKILL.md: guía de ingeniería completa
> Guía técnica para el desarrollo de skills en agentes de IA: 4 secciones obligatorias de SKILL.md, sincronización entre Codex y Claude Code, patrones de composición, 5 pruebas esenciales y prevención de regresiones.
## 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.
```mermaid
flowchart TD
subgraph Structure ["Cuatro componentes obligatorios de una SKILL.md en producción"]
F["1. Descripción en Frontmatter
(Formulada estrictamente como CONDICIÓN, no como tema)"]
T["2. Cuándo activar (Trigger)
(Límites contextuales explícitos y criterios de activación)"]
P["3. Procedimiento (Procedure)
(Pasos numerados con comandos validados y rutas reales)"]
Pit["4. Errores comunes (Pitfalls)
(Acción concreta + Consecuencia técnica + Corrección exacta)"]
end
F --> T --> P --> Pit
```
### 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*.
> [!NOTE]
> Si el procedimiento finaliza con una operación de despliegue o publicación, no reproduzcas el pipeline dentro de la skill. En su lugar, finaliza con una referencia: «Invoca la skill ship-pipeline».
---
## 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.
### Matriz de almacenamiento según el entorno
| Entorno de ejecución | Ruta de destino para SKILL.md | Comportamiento de descubrimiento |
| :--- | :--- | :--- |
| **OpenAI Codex** | `.agents/skills//SKILL.md` | Escaneado por Codex al indexar el espacio de trabajo local |
| **Anthropic Claude Code** | `.claude/skills//SKILL.md` | Cargado por Claude Code al inicializar la sesión |
> [!IMPORTANT]
> **Requisito de sincronización dual:** Una skill ubicada únicamente en `.claude/skills/` es completamente invisible para los agentes de Codex, y viceversa. Mantén siempre las skills sincronizadas en ambas rutas o configura enlaces simbólicos (symlinks) en el sistema de archivos.
---
## 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`.
```mermaid
flowchart LR
Draft["Borrador inicial
(Disparador temático, reglas duplicadas, pasos vagos)"] --> Review{"Revisión técnica"}
Review -->|Deficiencias detectadas| Fix["Ajustar disparadores y validar comandos"]
Fix --> Review
Review -->|Todos los criterios cumplidos| Prod["Skill lista para producción"]
```
---
## 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:
```text
Prompt: "Optimizar el rendimiento de las consultas en la base de datos"
└── db-router (Enrutador de entrada)
├── Delega en: neon-migrations (si se requieren cambios de esquema)
└── Delega en: drizzle-index-optimizer (si se requiere optimizar índices)
```
### 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/`:
```text
.claude/skills/fleet-coordinator/
├── SKILL.md # Flujo central de orquestación
└── references/
├── agent-roles.md # Matriz de roles y límites operativos
└── file-ownership.md # Reglas de concurrencia y escritura
```
### 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:
```markdown
> Tras completar la validación del esquema con éxito, invoca de inmediato la skill drizzle-migration-runner.
```
---
## 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.
:::tabs
@tab Descomponer (Dividir)
- **Disparadores divergentes:** Los escenarios demandan configuraciones incompatibles (por ejemplo, revisión de código de solo lectura vs. migraciones de esquema en vivo).
- **Superficies arquitectónicas dispares:** La skill intenta abarcar la interfaz pública (Tailwind) y la capa de datos o servidores (NestJS, SQL).
- **Saturación de contexto:** El archivo supera las 500 líneas y el agente omite pasos intermedios.
@tab Consolidar (Fusionar)
- **Ejecución fuertemente acoplada:** Dos micro-skills siempre se ejecutan una tras otra y ninguna tiene utilidad aislada.
- **Duplicación de código:** Mantenerlas separadas obliga a copiar comandos de validación idénticos en dos ubicaciones.
:::
> [!TIP]
> En el 90 % de los dilemas arquitectónicos, la decisión correcta es **dividir**. Crear una «macro-skill integral para backend» produce inevitablemente un monolito inestable propenso a alucinaciones.
---
## 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:
| Nivel de skill | Ubicación del código fuente | Proceso de compilación | Ámbito de aplicación |
| :--- | :--- | :--- | :--- |
| **Skill de repositorio privado** | `.agents/skills//SKILL.md` + `.claude/skills//SKILL.md` | **Ninguno** (lectura directa) | Reglas internas del equipo para el repositorio actual |
| **Insignia pública modular** | `skills-source//` + metadatos del generador | `node scripts/build-flagship-skills.mjs skills-source/` | Paquetes modulares complejos con referencias para registros públicos |
| **Skill pública de archivo único** | `baseSkills` en `lib/library/skills.ts` | **Ninguno** | Skills ligeras de catálogo base de la plataforma |
> [!WARNING]
> **Nunca modifiques artefactos compilados directamente:** Evita editar los archivos resultantes de la compilación. Aplica los cambios en el código fuente dentro de `skills-source//` y vuelve a ejecutar el script de generación.
---
## 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:
```mermaid
flowchart TD
T1["1. Prueba de disparadores
(3 prompts positivos + 2 prompts negativos)"] --> T2["2. Ejecución procedimental
(Recorrido manual en el repositorio activo)"]
T2 --> T3["3. Auditoría de fallos
(Validar fórmula Acción + Consecuencia + Corrección)"]
T3 --> T4["4. Prueba de alcance
(Definición de responsabilidad única en 1 frase)"]
T4 --> T5["5. Verificación de obsolescencia
(Comprobar rutas y comandos en el repo)"]
T5 --> Ready["Aprobada para producción"]
```
### 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:
| Dimensión | Borrador inacabado | Skill lista para producción |
| :--- | :--- | :--- |
| **Redacción del disparador** | Tema genérico: *«Para tareas de bases de datos»* | Condición precisa: *«Usar al aplicar migraciones de base de datos con Drizzle»* |
| **Claridad procedimental** | Instrucción ambigua: *«ejecutar linter si hace falta»* | Comando determinista: *«ejecutar npm run lint:fix»* |
| **Definición de riesgos** | Aviso abstracto: *«cuidado con los archivos»* | Fallo concreto: *«incluir archivos inexistentes interrumpe git add»* |
| **Genealogía de reglas** | Copia fragmentos literales de `AGENTS.md` | Enlaza directamente a las secciones de `AGENTS.md` |
| **Disponibilidad de runtime** | Presente solo en `.claude/skills/` | Sincronizada en `.agents/` y `.claude/` |
---
## 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`.
```text
El ciclo degenerativo de duplicar invariantes:
1. El desarrollador copia una regla de AGENTS.md dentro de SKILL.md.
2. Semanas después, el equipo actualiza la convención en AGENTS.md.
3. El archivo SKILL.md local conserva la versión obsoleta de la regla.
4. El agente de IA recibe directrices contradictorias y alucina.
```
### 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:
```bash
# Inseguro (si falta un solo archivo, todo el comando se interrumpe sin aviso):
git add src/generated/schema.ts src/types/db.ts
# Defensivo (comprueba la existencia de cada ruta antes de añadirla):
[ -e src/generated/schema.ts ] && git add src/generated/schema.ts
[ -e src/types/db.ts ] && git add src/types/db.ts
```
---
## 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//SKILL.md` y `.claude/skills//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.