# Convención `EXAMPLES.md` — recurso opcional para skills críticos

Convención **opcional** para skills cuyo valor depende de ejemplos concretos
con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:

- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
- Skills existentes que reciban actualización mayor y agreguen ejemplos.

---

## Cuándo aplicarla

Aplicar cuando:

- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
  decisiones arquitecturales).
- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
  correctamente vs el caso degenerado.
- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
  límite de 300 líneas.

NO aplicar cuando:

- El skill ya tiene `recursos/` con archivos temáticos específicos
  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
  temático es más informativo que `EXAMPLES.md`.
- El skill es un how-to procedural sin antipatrones contrastables.
- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.

---

## Estructura recomendada

```
habilidades/<skill-name>/
├── SKILL.md
└── recursos/
    └── EXAMPLES.md
```

`SKILL.md` enlaza al final con:

```markdown
Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
```

`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:

```markdown
## Ejemplo N — [título corto del escenario]

**Contexto**: [1-2 líneas]

### ❌ Sin <skill-name> (hipotético)
[código o descripción del enfoque incorrecto + consecuencia observable]

### ✓ Con <skill-name>
[código o descripción del enfoque correcto + por qué evita la consecuencia]
```

Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
clave que cambió (costo, tiempo, severidad de bug, etc.).

---

## Por qué OPCIONAL y no obligatoria

- 63 carpetas `recursos/` ya existen con nomenclatura temática
  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
  semántica del nombre.
- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
  con sufijo `.md` — esa regla cubre el 95% de los casos.
- Esta convención **complementa** la regla core para skills donde un nombre
  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
  y menos buscable).

---

## Origen

Patrón observado en repos externos analizados el 2026-05-09
(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
auto-cargable como referencia rápida del agente.

Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
primera aplicación. Casos futuros: skills de decisiones arquitecturales,
seguridad, debugging avanzado.
