@saulwade/swl-ses 2.6.0 → 2.8.0

package/comandos/swl/evaluar-skill.md

@@ -1,520 +1,520 @@
----
-name: swl:evaluar-skill
-description: Evalúa la calidad de un agente o skill SWL con 10 dimensiones, detecta anti-patrones y asigna badge de calidad (Platino/Oro/Plata/Bronce). Ejecutar antes de hacer merge de agentes o skills nuevas.
-argument-hint: <nombre-skill-o-agente> [--agente]
-allowed_tools: ["Read", "Bash", "Glob", "Grep"]
----
-
-# /swl:evaluar-skill — Evaluación de calidad de skills y agentes SWL
-
-Evalúa la calidad de una skill o agente SWL con un framework de 2 capas. La
-**Capa 1** usa verificaciones deterministas (análisis estático con herramientas
-del sistema). La **Capa 2** es evaluación semántica profunda realizada por el
-propio modelo al leer el contenido completo.
-
-Al finalizar, emite un reporte con score por dimensión, badge asignado y
-recomendaciones priorizadas de mejora.
-
-## Uso
-
-```
-/swl:evaluar-skill django-experto           — Evalúa la skill habilidades/django-experto/SKILL.md
-/swl:evaluar-skill backend-python-swl --agente  — Evalúa el agente agentes/backend-python-swl.md
-/swl:evaluar-skill                          — Lista skills disponibles y pide que se especifique
-```
-
-## Paso 0 — Resolver argumento
-
-Si no se pasa argumento, listar las opciones disponibles y detenerse:
-
-```bash
-echo "=== SKILLS DISPONIBLES ===" && ls -d habilidades/*/ 2>/dev/null | xargs -I{} basename {} | sort
-echo "=== AGENTES DISPONIBLES ===" && ls agentes/*.md 2>/dev/null | xargs -I{} basename {} .md | sort
-```
-
-Informar al usuario que especifique el nombre y si es agente agregar `--agente`.
-
-Si se pasa argumento sin `--agente`, buscar en `habilidades/<nombre>/SKILL.md`.
-Si el argumento incluye `--agente`, buscar en `agentes/<nombre>.md` (quitar el flag del nombre).
-
-Si el archivo no existe, informar y terminar:
-
-```
-No se encontró: habilidades/<nombre>/SKILL.md
-Verifica el nombre con /swl:evaluar-skill (sin argumentos) para ver las opciones.
-```
-
-## Paso 1 — Capa 1: Análisis estático
-
-Ejecutar todas las verificaciones deterministas. Registrar cada error (E0XX) y
-advertencia (W0XX) encontrado. No usar juicio subjetivo en esta capa.
-
-### 1.1 Verificaciones de frontmatter
-
-```bash
-SKILL_FILE="habilidades/<nombre>/SKILL.md"  # o agentes/<nombre>.md
-
-# Extraer frontmatter
-head -30 "$SKILL_FILE"
-
-# Verificar YAML válido del frontmatter (entre los ---) usando Python
-python3 -c "
-import sys, re
-content = open('$SKILL_FILE').read()
-match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
-if not match:
-    print('E001 YAML_INVALIDO: no se encontró bloque frontmatter')
-    sys.exit(1)
-import yaml
-try:
-    data = yaml.safe_load(match.group(1))
-    print('YAML OK:', list(data.keys()) if data else 'vacío')
-except Exception as e:
-    print('E001 YAML_INVALIDO:', e)
-" 2>/dev/null || echo "E001 YAML_INVALIDO"
-```
-
-Verificar campo `name`:
-```bash
-grep -m1 "^name:" "$SKILL_FILE" || echo "E002 NAME_AUSENTE"
-```
-
-Verificar campo `description`:
-```bash
-desc=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//')
-[ -z "$desc" ] && echo "E003 DESCRIPTION_AUSENTE" || echo "description OK: ${#desc} chars"
-```
-
-Verificar formato kebab-case de `name`:
-```bash
-name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
-echo "$name_val" | grep -qE '^[a-z0-9][a-z0-9-]*$' || echo "E004 NAME_FORMATO: '$name_val' no es kebab-case"
-```
-
-Verificar longitud de `name` (máx 64 caracteres):
-```bash
-name_len=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//' | wc -c)
-[ "$name_len" -gt 64 ] && echo "E005 NAME_LONGITUD: $name_len chars" || echo "name length OK"
-```
-
-Verificar que `name` no use términos reservados:
-```bash
-name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
-echo "$name_val" | grep -qiE '(anthropic|claude|swl|^tests?$|testing)' && echo "E006 NAME_RESERVADO: '$name_val'" || echo "name reservado OK"
-```
-
-Verificar coincidencia entre `name` y nombre del directorio (solo para skills):
-```bash
-dir_name="<nombre>"
-name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
-[ "$name_val" != "$dir_name" ] && echo "E007 NAME_DIRECTORIO: name='$name_val' != dir='$dir_name'" || echo "name/dir OK"
-```
-
-Verificar longitud de `description` (máx 1,024 caracteres):
-```bash
-desc_len=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//' | wc -c)
-[ "$desc_len" -gt 1024 ] && echo "E008 DESCRIPTION_LONGITUD: $desc_len chars" || echo "description length OK"
-```
-
-### 1.2 Verificaciones de contenido
-
-Verificar presencia de trigger "Cargar cuando" o "Invocar cuando":
-```bash
-grep -qi "Cargar cuando\|Invocar cuando" "$SKILL_FILE" || echo "E009 MISSING_TRIGGER"
-```
-
-Verificar referencias a recursos internos:
-```bash
-# Encontrar referencias a recursos/X.md dentro del SKILL.md
-grep -oE 'recursos/[^)"\s]+\.md' "$SKILL_FILE" | while read ref; do
-  dir=$(dirname "$SKILL_FILE")
-  [ ! -f "$dir/$ref" ] && echo "E010 REFERENCIA_ROTA: $ref"
-done
-echo "referencias OK"
-```
-
-### 1.3 Verificaciones de advertencias
-
-Verificar si la skill supera 300 líneas:
-```bash
-lines=$(wc -l < "$SKILL_FILE")
-[ "$lines" -gt 300 ] && echo "W001 BLOATED_SKILL: $lines líneas (máx 300)" || echo "W001 OK: $lines líneas"
-```
-
-Verificar uso excesivo de directivas absolutas:
-```bash
-count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
-[ "$count" -gt 15 ] && echo "W002 OVER_CONSTRAINED: $count ocurrencias" || echo "W002 OK: $count ocurrencias"
-```
-
-Verificar archivos huérfanos en recursos/:
-```bash
-skill_dir=$(dirname "$SKILL_FILE")
-if [ -d "$skill_dir/recursos" ]; then
-  for rec in "$skill_dir/recursos/"*.md; do
-    base=$(basename "$rec")
-    grep -q "$base" "$SKILL_FILE" || echo "W003 HUERFANO: recursos/$base no referenciado"
-  done
-fi
-```
-
-Verificar presencia de ejemplos de código si la skill cubre implementación:
-```bash
-code_blocks=$(grep -c '```' "$SKILL_FILE" || echo 0)
-[ "$code_blocks" -eq 0 ] && echo "W004 SIN_EJEMPLO_CODIGO: cero bloques de código" || echo "W004 OK: $code_blocks delimitadores de bloque"
-```
-
-Verificar sección de "cuándo NO usar":
-```bash
-grep -qi "cuándo no\|cuando no\|no usar\|no cargar\|no invocar" "$SKILL_FILE" || echo "W005 SIN_CUANDO_NO_USAR"
-```
-
-Verificar presencia de sección Gotchas o equivalente:
-```bash
-# W008: skills sin sección Gotchas
-# Penalización inicial suave (-5) durante período de migración de Fase 3.
-# Tras la migración se promoverá a -12 para hacer la sección obligatoria.
-grep -qi "Gotcha\|Errores comunes\|trampas\|Errores no obvios\|Fallas conocidas" "$SKILL_FILE" || \
-  echo "W008 SIN_GOTCHAS: skill sin seccion Gotchas (penalizacion -5 en robustness)"
-```
-
-Verificar uso de campos legacy en inglés (sin alias en español):
-```bash
-# W010: uso de campos legacy (inglés) sin alias en español (penalización -6 en robustness)
-# Promovido 2026-04-24 tras v5.11.2 (2 releases desde introducción) — período de gracia concluido.
-node -e "
-const fs = require('fs');
-const norm = require('./scripts/lib/skill-normalizer.js');
-const raw = fs.readFileSync(process.argv[1], 'utf8');
-const match = raw.match(/^---\n([\s\S]*?)\n---/);
-if (!match) process.exit(0);
-const fm = {};
-for (const linea of match[1].split(/\r?\n/)) {
-  const m = linea.match(/^(\w[\w_-]*):\s*(.+)\$/);
-  if (m) fm[m[1]] = m[2];
-}
-const legacy = norm.detectarUsoLegacy(fm);
-const divergente = norm.detectarDivergencias(fm);
-[...legacy, ...divergente].forEach(w => process.stderr.write(w.mensaje + '\n'));
-" "\$SKILL_FILE" 2>&1 | grep W010 || echo "W010 OK: sin campos legacy"
-```
-
-Verificar justificación en directivas absolutas:
-```bash
-# W009: directivas absolutas sin justificación
-# Si hay más de 3 directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE y ninguna está
-# acompañada de palabras justificativas en la misma línea o la siguiente,
-# el modelo obedece pero no puede generalizar a casos edge.
-directive_count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
-if [ "$directive_count" -gt 3 ]; then
-  justified=$(grep -E '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" | \
-    grep -ciE 'porque|ya que|para evitar|si no|since|because|para que' || echo 0)
-  [ "$justified" -eq 0 ] && echo "W009 DIRECTIVAS_SIN_JUSTIFICACION: $directive_count directivas absolutas sin palabras justificativas (penalizacion -8 en output_quality)" || echo "W009 OK: $justified/$directive_count directivas con justificacion"
-fi
-```
-
-### 1.4 Resumen de Capa 1
-
-Tabular todos los errores y advertencias encontrados. Aplicar penalizaciones:
-
-| Código | Tipo | Penalización |
-|--------|------|-------------|
-| E001–E010 | ERROR | Dimensión relacionada → 0 |
-| W001 | ADVERTENCIA | -8 en `progressive_disclosure` |
-| W002 | ADVERTENCIA | -5 en `scope_calibration` |
-| W003 | ADVERTENCIA | -3 en `structural_completeness` |
-| W004 | ADVERTENCIA | -10 en `code_template_quality` |
-| W005 | ADVERTENCIA | -5 en `scope_calibration` |
-| W008 | ADVERTENCIA | -5 en `robustness` (período de migración; se promoverá a -12 tras Fase 3) |
-| W009 | ADVERTENCIA | -8 en `output_quality` |
-| W010 | ADVERTENCIA | -6 en `robustness` (promovido 2026-04-24 tras v5.11.2; período de migración concluido — campos en español SWL son ahora esperados) |
-
-Mapeo de errores a dimensiones afectadas:
-- E001, E002, E003, E008 → `structural_completeness`
-- E004, E005, E006, E007 → `ecosystem_coherence`
-- E009 → `triggering_accuracy`
-- E010 → `structural_completeness`
-
-### 1.5 Métricas cuantitativas de calidad
-
-Calcular métricas de eficiencia de tokens y duplicación:
-
-```bash
-SKILL_FILE="habilidades/<nombre>/SKILL.md"
-
-# Estimar tokens del skill
-node -e "
-const { estimateTokens } = require('./hooks/lib/token-budget');
-const fs = require('fs');
-const content = fs.readFileSync('$SKILL_FILE', 'utf8');
-const tokens = estimateTokens(content, 'mixed');
-const lines = content.split('\n').length;
-const ratio = (tokens / lines).toFixed(1);
-console.log('TOKENS: ' + tokens);
-console.log('LINEAS: ' + lines);
-console.log('DENSIDAD: ' + ratio + ' tokens/línea');
-console.log(tokens > 5000 ? 'W006 TOKEN_EXCESIVO: ' + tokens + ' tokens (máx 5000)' : 'tokens OK');
-"
-```
-
-Detección de duplicación con otros skills del sistema:
-
-```bash
-# Comparar contenido con skills del mismo dominio
-node -e "
-const { jaccardSimilarity } = require('./hooks/lib/fingerprint-id');
-const fs = require('fs');
-const path = require('path');
-const target = fs.readFileSync('$SKILL_FILE', 'utf8');
-const skillsDir = 'habilidades';
-const dirs = fs.readdirSync(skillsDir, {withFileTypes:true}).filter(d=>d.isDirectory());
-const results = [];
-for (const d of dirs) {
-  const p = path.join(skillsDir, d.name, 'SKILL.md');
-  if (p === '$SKILL_FILE' || !fs.existsSync(p)) continue;
-  const content = fs.readFileSync(p, 'utf8');
-  const sim = jaccardSimilarity(target, content);
-  if (sim > 0.3) results.push({name: d.name, similarity: (sim*100).toFixed(1)});
-}
-results.sort((a,b) => b.similarity - a.similarity);
-if (results.length > 0) {
-  console.log('SIMILITUD con otros skills:');
-  results.slice(0,5).forEach(r => {
-    const flag = r.similarity > 50 ? ' W007 DUPLICADO_POTENCIAL' : '';
-    console.log('  ' + r.name + ': ' + r.similarity + '%' + flag);
-  });
-} else {
-  console.log('Sin duplicación detectada con otros skills.');
-}
-"
-```
-
-Mapeo de advertencias nuevas:
-
-| Código | Tipo | Penalización |
-|--------|------|-------------|
-| W006 | ADVERTENCIA | -8 en `token_efficiency` |
-| W007 | ADVERTENCIA | -10 en `orchestration_fitness` (posible duplicación) |
-
-## Paso 2 — Capa 2: Evaluación semántica
-
-Leer el archivo completo con `Read`. Evaluar cada dimensión de 0 a 100 con
-criterio honesto: si la skill tiene problemas reales, el score debe reflejarlos.
-
-### Tabla de dimensiones
-
-| Dimensión | Peso | Qué medir |
-|-----------|------|-----------|
-| `triggering_accuracy` | 25% | ¿La `description` activa la skill en los momentos correctos? ¿El trigger es ni muy amplio ni muy estrecho? ¿Evita activaciones falsas? |
-| `orchestration_fitness` | 20% | ¿Coordina bien con otras skills del sistema? ¿Invoca correctamente otras skills con `Skill("nombre")`? ¿Evita duplicar contenido de otras skills? |
-| `output_quality` | 15% | ¿Los ejemplos de código son reales y funcionales? ¿Las reglas son específicas, no genéricas? ¿El contenido refleja patrones idiomáticos del framework? ¿Las directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación de por qué la regla existe? Una directiva sin justificación no permite al modelo generalizar a casos edge (ver W009). |
-| `scope_calibration` | 12% | ¿El scope es coherente? ¿No cubre demasiado? ¿Hay sección de "cuándo NO usar"? ¿El contenido es específico del dominio declarado? |
-| `progressive_disclosure` | 10% | ¿El SKILL.md principal es conciso (< 300 líneas)? ¿El contenido extenso está en `recursos/`? ¿Las referencias a recursos son claras y útiles? |
-| `token_efficiency` | 6% | ¿Hay contenido redundante o repetitivo? ¿Los ejemplos son concisos pero completos? ¿Se evita documentación genérica que no agrega valor? |
-| `robustness` | 5% | ¿Documenta casos edge y anti-patrones? ¿Cubre los errores más comunes del dominio? |
-| `structural_completeness` | 3% | ¿Tiene todas las secciones mínimas requeridas? ¿El frontmatter tiene todos los campos obligatorios? |
-| `code_template_quality` | 2% | ¿Los ejemplos de código compilan/ejecutan? ¿Usan sintaxis actual del lenguaje o framework? |
-| `ecosystem_coherence` | 2% | ¿El naming sigue las convenciones del sistema SWL (kebab-case)? ¿Los patrones son consistentes con las otras skills? |
-
-**Guía de calibración de scores:**
-- 90-100: Excelente — referente del sistema
-- 80-89: Sólido — listo para uso en producción
-- 70-79: Funcional — mejoras menores posibles
-- 60-69: Aceptable — requiere revisión antes de merge
-- 40-59: Deficiente — problemas claros que afectan efectividad
-- 0-39: Insuficiente — necesita reescritura
-
-## Paso 3 — Cálculo del score final
-
-Calcular score ponderado:
-
-```
-score_final = Σ(score_dimensión × peso_dimensión)
-
-Ejemplo:
-  triggering_accuracy    = 85 × 0.25 = 21.25
-  orchestration_fitness  = 78 × 0.20 = 15.60
-  output_quality         = 90 × 0.15 = 13.50
-  scope_calibration      = 72 × 0.12 =  8.64
-  progressive_disclosure = 80 × 0.10 =  8.00
-  token_efficiency       = 70 × 0.06 =  4.20
-  robustness             = 65 × 0.05 =  3.25
-  structural_completeness= 95 × 0.03 =  2.85
-  code_template_quality  = 85 × 0.02 =  1.70
-  ecosystem_coherence    = 90 × 0.02 =  1.80
-  ─────────────────────────────────────────────
-  score_final = 80.79
-```
-
-Asignar badge:
-
-```
-≥ 90  → Platino  — production-ready, puede usarse como referencia
-≥ 80  → Oro      — listo para merge
-≥ 70  → Plata    — necesita mejoras menores antes del merge
-≥ 60  → Bronce   — requiere revisión antes de merge
-< 60  → Sin badge — no hacer merge hasta corregir
-```
-
-### Gate de promoción para auto-evolucion-swl (G8)
-
-Este comando es el **gate obligatorio** del flujo de promoción de skills
-auto-generados desde `_userland/plugins/` a `habilidades/`. El agente
-`auto-evolucion-swl` invoca este comando antes de mover un skill al core
-(ver `agentes/auto-evolucion-swl.md` sección "Gate G8").
-
-Umbral de promoción:
-
-| Badge | Acción de auto-evolucion |
-|-------|-------------------------|
-| Platino, Oro, Plata | Promover a `habilidades/`, registrar en manifiestos |
-| Bronce | NO promover, devolver a `_userland/` con feedback |
-| Sin badge | NO promover, registrar rechazo en `.planning/evolution/promociones-rechazadas.jsonl` |
-
-Si un skill es rechazado ≥3 veces consecutivas, el agente escala al usuario
-con análisis de qué dimensiones bajan el score. Origen: ADR 0013 sección 3C.
-
-## Paso 4 — Emitir reporte y artefacto de procedencia
-
-Tras calcular el score final y el badge, persiste el **artefacto de
-evaluación con procedencia** (única fuente que `run-skill-evals.js
---record-after` acepta para aprobar una evolución — anti-gaming,
-DT-AGP-SCORE-AUTODECLARADO):
-
-```bash
-swl-ses run-skill-evals <nombre> --emitir-evaluacion \
-  --score=<score-final> --badge=<badge> --producido-por=evaluar-skill
-# → escribe .planning/evolution/evaluaciones/<nombre>.json (fechado)
-#   y registra el evento tipo:evaluacion en evoluciones.jsonl
-```
-
-Es el ÚNICO archivo que este comando crea. Luego generar el siguiente
-reporte directamente en la conversación:
-
-```markdown
-## Evaluación de skill: [nombre]
-**Archivo**: habilidades/[nombre]/SKILL.md  (o agentes/[nombre].md)
-**Fecha**: [fecha actual]
-
-### Capa 1 — Análisis estático
-
-[PASS si no hay errores ni advertencias]
-[O listar cada E0XX / W0XX con descripción breve]
-
-### Capa 2 — Evaluación semántica
-
-| Dimensión | Peso | Score | Contribución |
-|-----------|------|-------|-------------|
-| Triggering accuracy | 25% | XX/100 | XX.XX |
-| Orchestration fitness | 20% | XX/100 | XX.XX |
-| Output quality | 15% | XX/100 | XX.XX |
-| Scope calibration | 12% | XX/100 | XX.XX |
-| Progressive disclosure | 10% | XX/100 | XX.XX |
-| Token efficiency | 6% | XX/100 | XX.XX |
-| Robustness | 5% | XX/100 | XX.XX |
-| Structural completeness | 3% | XX/100 | XX.XX |
-| Code template quality | 2% | XX/100 | XX.XX |
-| Ecosystem coherence | 2% | XX/100 | XX.XX |
-
-**Score final: XX.XX/100 — Badge: [🏆/🥇/🥈/🥉/❌] [Platino/Oro/Plata/Bronce/Sin badge]**
-
-### Hallazgos principales
-
-**Fortalezas:**
-- [2-3 aspectos bien ejecutados con evidencia específica del contenido]
-
-**Áreas de mejora:**
-- [hallazgos específicos con sugerencia concreta y línea o sección afectada]
-
-### Recomendaciones para subir el score
-
-[Lista priorizada de cambios concretos que mejorarían el score,
-ordenados de mayor a menor impacto. Incluir la dimensión afectada.]
-```
-
-## Paso 3 — Capa 3 opcional: Evals estructurados
-
-Si el artefacto tiene un archivo de evals en formato `skill-evals.schema.json`:
-
-```bash
-EVALS_PATH="habilidades/<nombre>/evals/evals.json"
-[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || EVALS_PATH="agentes/evals/<nombre>.evals.json"
-[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || echo "SIN_EVALS"
-```
-
-Si existen, ejecutar la Capa 3:
-
-### 3.1 — Validar el artefacto contra el schema
-
-```bash
-# Validación mínima de estructura (zero-deps): comprobar que es JSON válido y
-# que tiene los campos obligatorios. Validación completa del schema queda para
-# consumidores externos (ajv, etc.) — SWL no arrastra deps.
-node -e "
-  const ev = require('./$EVALS_PATH');
-  const req = ['skill_name','schema_version','evals'];
-  const missing = req.filter(k => !(k in ev));
-  if (missing.length) { console.error('FALTAN:', missing.join(',')); process.exit(1); }
-  if (!Array.isArray(ev.evals) || ev.evals.length === 0) { console.error('evals vacío'); process.exit(1); }
-  console.log('OK', ev.evals.length, 'evals');
-"
-```
-
-Si falla la validación, reportar y continuar solo con Capa 1+2 (no bloquear).
-
-### 3.2 — Ejecutar cada eval contra el skill cargado
-
-Para cada `eval` del artefacto:
-
-1. Cargar el skill con `Skill("<nombre>")`.
-2. Enviar el `prompt` exacto al modelo en una respuesta aislada (sin historial).
-3. Capturar la respuesta.
-4. Para cada entrada de `expectations[]`, verificar si la respuesta la cumple
-   (match semántico honesto, no literal).
-5. Computar `pass = true` solo si TODAS las expectations se cumplen.
-6. Aplicar `weight` (default 1.0) al score.
-
-### 3.3 — Score de Capa 3
-
-```
-score_evals = sum(pass_i * weight_i) / sum(weight_i) * 100
-```
-
-### 3.4 — Integración con score final
-
-El score final combinado es:
-
-- Sin evals: `score_final = score_capa_1_2`
-- Con evals: `score_final = score_capa_1_2 * 0.7 + score_evals * 0.3`
-
-Reportar ambos separadamente para trazabilidad. Si `score_evals < 60`, marcar
-alerta: la skill puede ser declarativa pero falla en evaluación ejecutable.
-
-### 3.5 — Reporte por eval
-
-```
-| ID | Tags | Peso | Resultado | Expectations fallidas |
-|----|------|------|-----------|----------------------|
-| 0  | primary-flow | 1.0 | ✓ pass | — |
-| 1  | edge-case | 1.0 | ✗ fail | "La respuesta distingue X de Y" |
-| anti-pattern-substitution | anti-pattern,regression | 1.5 | ✓ pass | — |
-
-Score evals: 82.4/100 (peso 30% del final)
-```
-
-## Reglas de comportamiento
-
-- La Capa 1 es **determinista**: ejecutar los scripts Bash y registrar resultados exactos. No inferir ni interpretar.
-- La Capa 2 es **semántica honesta**: si la skill tiene problemas reales el score debe reflejarlos. No inflar scores por cortesía.
-- La Capa 3 es **opcional**: si no existe `evals/evals.json`, omitirla sin penalizar. Si existe, es autoridad primaria sobre Capa 2 en caso de discrepancia (los evals son reproducibles; la evaluación semántica no).
-- Un skill con Capa 3 activa y `score_evals ≥ 90` es candidato a badge **Platino** aunque Capa 2 sea 85.
-- Los evals NUNCA se inventan en este comando — solo se ejecutan los declarados por el autor del skill. Crear evals nuevos es tarea de `/swl:aprender` o del autor del skill directamente, siguiendo `plantillas/skill-evals-template.json`.
-- Si el archivo no existe, informar al usuario con el path exacto y terminar.
-- Si `--agente` se pasa sin nombre, listar los agentes disponibles y terminar.
-- El reporte siempre se emite en la conversación. El único archivo que se
-  crea es el artefacto de procedencia del Paso 4 (`.planning/evolution/
-  evaluaciones/<nombre>.json`) — nunca reportes sueltos.
-- Las "Fortalezas" deben ser específicas del contenido leído, no genéricas.
-- Las "Áreas de mejora" deben incluir la sección o línea aproximada donde se detectó el problema.
-- Si la Capa 1 genera errores E001–E010, reflejar el impacto en el score de la dimensión afectada antes de sumar las contribuciones ponderadas.
-- Score mínimo aprobado para merge: **80/100** (badge Oro). Por debajo de ese umbral, indicar claramente que **no está listo para merge**.
+---
+name: swl:evaluar-skill
+description: Evalúa la calidad de un agente o skill SWL con 10 dimensiones, detecta anti-patrones y asigna badge de calidad (Platino/Oro/Plata/Bronce). Ejecutar antes de hacer merge de agentes o skills nuevas.
+argument-hint: <nombre-skill-o-agente> [--agente]
+allowed_tools: ["Read", "Bash", "Glob", "Grep"]
+---
+
+# /swl:evaluar-skill — Evaluación de calidad de skills y agentes SWL
+
+Evalúa la calidad de una skill o agente SWL con un framework de 2 capas. La
+**Capa 1** usa verificaciones deterministas (análisis estático con herramientas
+del sistema). La **Capa 2** es evaluación semántica profunda realizada por el
+propio modelo al leer el contenido completo.
+
+Al finalizar, emite un reporte con score por dimensión, badge asignado y
+recomendaciones priorizadas de mejora.
+
+## Uso
+
+```
+/swl:evaluar-skill django-experto           — Evalúa la skill habilidades/django-experto/SKILL.md
+/swl:evaluar-skill backend-python-swl --agente  — Evalúa el agente agentes/backend-python-swl.md
+/swl:evaluar-skill                          — Lista skills disponibles y pide que se especifique
+```
+
+## Paso 0 — Resolver argumento
+
+Si no se pasa argumento, listar las opciones disponibles y detenerse:
+
+```bash
+echo "=== SKILLS DISPONIBLES ===" && ls -d habilidades/*/ 2>/dev/null | xargs -I{} basename {} | sort
+echo "=== AGENTES DISPONIBLES ===" && ls agentes/*.md 2>/dev/null | xargs -I{} basename {} .md | sort
+```
+
+Informar al usuario que especifique el nombre y si es agente agregar `--agente`.
+
+Si se pasa argumento sin `--agente`, buscar en `habilidades/<nombre>/SKILL.md`.
+Si el argumento incluye `--agente`, buscar en `agentes/<nombre>.md` (quitar el flag del nombre).
+
+Si el archivo no existe, informar y terminar:
+
+```
+No se encontró: habilidades/<nombre>/SKILL.md
+Verifica el nombre con /swl:evaluar-skill (sin argumentos) para ver las opciones.
+```
+
+## Paso 1 — Capa 1: Análisis estático
+
+Ejecutar todas las verificaciones deterministas. Registrar cada error (E0XX) y
+advertencia (W0XX) encontrado. No usar juicio subjetivo en esta capa.
+
+### 1.1 Verificaciones de frontmatter
+
+```bash
+SKILL_FILE="habilidades/<nombre>/SKILL.md"  # o agentes/<nombre>.md
+
+# Extraer frontmatter
+head -30 "$SKILL_FILE"
+
+# Verificar YAML válido del frontmatter (entre los ---) usando Python
+python3 -c "
+import sys, re
+content = open('$SKILL_FILE').read()
+match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+if not match:
+    print('E001 YAML_INVALIDO: no se encontró bloque frontmatter')
+    sys.exit(1)
+import yaml
+try:
+    data = yaml.safe_load(match.group(1))
+    print('YAML OK:', list(data.keys()) if data else 'vacío')
+except Exception as e:
+    print('E001 YAML_INVALIDO:', e)
+" 2>/dev/null || echo "E001 YAML_INVALIDO"
+```
+
+Verificar campo `name`:
+```bash
+grep -m1 "^name:" "$SKILL_FILE" || echo "E002 NAME_AUSENTE"
+```
+
+Verificar campo `description`:
+```bash
+desc=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//')
+[ -z "$desc" ] && echo "E003 DESCRIPTION_AUSENTE" || echo "description OK: ${#desc} chars"
+```
+
+Verificar formato kebab-case de `name`:
+```bash
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+echo "$name_val" | grep -qE '^[a-z0-9][a-z0-9-]*$' || echo "E004 NAME_FORMATO: '$name_val' no es kebab-case"
+```
+
+Verificar longitud de `name` (máx 64 caracteres):
+```bash
+name_len=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//' | wc -c)
+[ "$name_len" -gt 64 ] && echo "E005 NAME_LONGITUD: $name_len chars" || echo "name length OK"
+```
+
+Verificar que `name` no use términos reservados:
+```bash
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+echo "$name_val" | grep -qiE '(anthropic|claude|swl|^tests?$|testing)' && echo "E006 NAME_RESERVADO: '$name_val'" || echo "name reservado OK"
+```
+
+Verificar coincidencia entre `name` y nombre del directorio (solo para skills):
+```bash
+dir_name="<nombre>"
+name_val=$(grep -m1 "^name:" "$SKILL_FILE" | sed 's/^name:[[:space:]]*//')
+[ "$name_val" != "$dir_name" ] && echo "E007 NAME_DIRECTORIO: name='$name_val' != dir='$dir_name'" || echo "name/dir OK"
+```
+
+Verificar longitud de `description` (máx 1,024 caracteres):
+```bash
+desc_len=$(grep -m1 "^description:" "$SKILL_FILE" | sed 's/^description:[[:space:]]*//' | wc -c)
+[ "$desc_len" -gt 1024 ] && echo "E008 DESCRIPTION_LONGITUD: $desc_len chars" || echo "description length OK"
+```
+
+### 1.2 Verificaciones de contenido
+
+Verificar presencia de trigger "Cargar cuando" o "Invocar cuando":
+```bash
+grep -qi "Cargar cuando\|Invocar cuando" "$SKILL_FILE" || echo "E009 MISSING_TRIGGER"
+```
+
+Verificar referencias a recursos internos:
+```bash
+# Encontrar referencias a recursos/X.md dentro del SKILL.md
+grep -oE 'recursos/[^)"\s]+\.md' "$SKILL_FILE" | while read ref; do
+  dir=$(dirname "$SKILL_FILE")
+  [ ! -f "$dir/$ref" ] && echo "E010 REFERENCIA_ROTA: $ref"
+done
+echo "referencias OK"
+```
+
+### 1.3 Verificaciones de advertencias
+
+Verificar si la skill supera 300 líneas:
+```bash
+lines=$(wc -l < "$SKILL_FILE")
+[ "$lines" -gt 300 ] && echo "W001 BLOATED_SKILL: $lines líneas (máx 300)" || echo "W001 OK: $lines líneas"
+```
+
+Verificar uso excesivo de directivas absolutas:
+```bash
+count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
+[ "$count" -gt 15 ] && echo "W002 OVER_CONSTRAINED: $count ocurrencias" || echo "W002 OK: $count ocurrencias"
+```
+
+Verificar archivos huérfanos en recursos/:
+```bash
+skill_dir=$(dirname "$SKILL_FILE")
+if [ -d "$skill_dir/recursos" ]; then
+  for rec in "$skill_dir/recursos/"*.md; do
+    base=$(basename "$rec")
+    grep -q "$base" "$SKILL_FILE" || echo "W003 HUERFANO: recursos/$base no referenciado"
+  done
+fi
+```
+
+Verificar presencia de ejemplos de código si la skill cubre implementación:
+```bash
+code_blocks=$(grep -c '```' "$SKILL_FILE" || echo 0)
+[ "$code_blocks" -eq 0 ] && echo "W004 SIN_EJEMPLO_CODIGO: cero bloques de código" || echo "W004 OK: $code_blocks delimitadores de bloque"
+```
+
+Verificar sección de "cuándo NO usar":
+```bash
+grep -qi "cuándo no\|cuando no\|no usar\|no cargar\|no invocar" "$SKILL_FILE" || echo "W005 SIN_CUANDO_NO_USAR"
+```
+
+Verificar presencia de sección Gotchas o equivalente:
+```bash
+# W008: skills sin sección Gotchas
+# Penalización inicial suave (-5) durante período de migración de Fase 3.
+# Tras la migración se promoverá a -12 para hacer la sección obligatoria.
+grep -qi "Gotcha\|Errores comunes\|trampas\|Errores no obvios\|Fallas conocidas" "$SKILL_FILE" || \
+  echo "W008 SIN_GOTCHAS: skill sin seccion Gotchas (penalizacion -5 en robustness)"
+```
+
+Verificar uso de campos legacy en inglés (sin alias en español):
+```bash
+# W010: uso de campos legacy (inglés) sin alias en español (penalización -6 en robustness)
+# Promovido 2026-04-24 tras v5.11.2 (2 releases desde introducción) — período de gracia concluido.
+node -e "
+const fs = require('fs');
+const norm = require('./scripts/lib/skill-normalizer.js');
+const raw = fs.readFileSync(process.argv[1], 'utf8');
+const match = raw.match(/^---\n([\s\S]*?)\n---/);
+if (!match) process.exit(0);
+const fm = {};
+for (const linea of match[1].split(/\r?\n/)) {
+  const m = linea.match(/^(\w[\w_-]*):\s*(.+)\$/);
+  if (m) fm[m[1]] = m[2];
+}
+const legacy = norm.detectarUsoLegacy(fm);
+const divergente = norm.detectarDivergencias(fm);
+[...legacy, ...divergente].forEach(w => process.stderr.write(w.mensaje + '\n'));
+" "\$SKILL_FILE" 2>&1 | grep W010 || echo "W010 OK: sin campos legacy"
+```
+
+Verificar justificación en directivas absolutas:
+```bash
+# W009: directivas absolutas sin justificación
+# Si hay más de 3 directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE y ninguna está
+# acompañada de palabras justificativas en la misma línea o la siguiente,
+# el modelo obedece pero no puede generalizar a casos edge.
+directive_count=$(grep -cE '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" || echo 0)
+if [ "$directive_count" -gt 3 ]; then
+  justified=$(grep -E '\bMUST\b|\bALWAYS\b|\bNEVER\b|\bNUNCA\b|\bSIEMPRE\b' "$SKILL_FILE" | \
+    grep -ciE 'porque|ya que|para evitar|si no|since|because|para que' || echo 0)
+  [ "$justified" -eq 0 ] && echo "W009 DIRECTIVAS_SIN_JUSTIFICACION: $directive_count directivas absolutas sin palabras justificativas (penalizacion -8 en output_quality)" || echo "W009 OK: $justified/$directive_count directivas con justificacion"
+fi
+```
+
+### 1.4 Resumen de Capa 1
+
+Tabular todos los errores y advertencias encontrados. Aplicar penalizaciones:
+
+| Código | Tipo | Penalización |
+|--------|------|-------------|
+| E001–E010 | ERROR | Dimensión relacionada → 0 |
+| W001 | ADVERTENCIA | -8 en `progressive_disclosure` |
+| W002 | ADVERTENCIA | -5 en `scope_calibration` |
+| W003 | ADVERTENCIA | -3 en `structural_completeness` |
+| W004 | ADVERTENCIA | -10 en `code_template_quality` |
+| W005 | ADVERTENCIA | -5 en `scope_calibration` |
+| W008 | ADVERTENCIA | -5 en `robustness` (período de migración; se promoverá a -12 tras Fase 3) |
+| W009 | ADVERTENCIA | -8 en `output_quality` |
+| W010 | ADVERTENCIA | -6 en `robustness` (promovido 2026-04-24 tras v5.11.2; período de migración concluido — campos en español SWL son ahora esperados) |
+
+Mapeo de errores a dimensiones afectadas:
+- E001, E002, E003, E008 → `structural_completeness`
+- E004, E005, E006, E007 → `ecosystem_coherence`
+- E009 → `triggering_accuracy`
+- E010 → `structural_completeness`
+
+### 1.5 Métricas cuantitativas de calidad
+
+Calcular métricas de eficiencia de tokens y duplicación:
+
+```bash
+SKILL_FILE="habilidades/<nombre>/SKILL.md"
+
+# Estimar tokens del skill
+node -e "
+const { estimateTokens } = require('./hooks/lib/token-budget');
+const fs = require('fs');
+const content = fs.readFileSync('$SKILL_FILE', 'utf8');
+const tokens = estimateTokens(content, 'mixed');
+const lines = content.split('\n').length;
+const ratio = (tokens / lines).toFixed(1);
+console.log('TOKENS: ' + tokens);
+console.log('LINEAS: ' + lines);
+console.log('DENSIDAD: ' + ratio + ' tokens/línea');
+console.log(tokens > 5000 ? 'W006 TOKEN_EXCESIVO: ' + tokens + ' tokens (máx 5000)' : 'tokens OK');
+"
+```
+
+Detección de duplicación con otros skills del sistema:
+
+```bash
+# Comparar contenido con skills del mismo dominio
+node -e "
+const { jaccardSimilarity } = require('./hooks/lib/fingerprint-id');
+const fs = require('fs');
+const path = require('path');
+const target = fs.readFileSync('$SKILL_FILE', 'utf8');
+const skillsDir = 'habilidades';
+const dirs = fs.readdirSync(skillsDir, {withFileTypes:true}).filter(d=>d.isDirectory());
+const results = [];
+for (const d of dirs) {
+  const p = path.join(skillsDir, d.name, 'SKILL.md');
+  if (p === '$SKILL_FILE' || !fs.existsSync(p)) continue;
+  const content = fs.readFileSync(p, 'utf8');
+  const sim = jaccardSimilarity(target, content);
+  if (sim > 0.3) results.push({name: d.name, similarity: (sim*100).toFixed(1)});
+}
+results.sort((a,b) => b.similarity - a.similarity);
+if (results.length > 0) {
+  console.log('SIMILITUD con otros skills:');
+  results.slice(0,5).forEach(r => {
+    const flag = r.similarity > 50 ? ' W007 DUPLICADO_POTENCIAL' : '';
+    console.log('  ' + r.name + ': ' + r.similarity + '%' + flag);
+  });
+} else {
+  console.log('Sin duplicación detectada con otros skills.');
+}
+"
+```
+
+Mapeo de advertencias nuevas:
+
+| Código | Tipo | Penalización |
+|--------|------|-------------|
+| W006 | ADVERTENCIA | -8 en `token_efficiency` |
+| W007 | ADVERTENCIA | -10 en `orchestration_fitness` (posible duplicación) |
+
+## Paso 2 — Capa 2: Evaluación semántica
+
+Leer el archivo completo con `Read`. Evaluar cada dimensión de 0 a 100 con
+criterio honesto: si la skill tiene problemas reales, el score debe reflejarlos.
+
+### Tabla de dimensiones
+
+| Dimensión | Peso | Qué medir |
+|-----------|------|-----------|
+| `triggering_accuracy` | 25% | ¿La `description` activa la skill en los momentos correctos? ¿El trigger es ni muy amplio ni muy estrecho? ¿Evita activaciones falsas? |
+| `orchestration_fitness` | 20% | ¿Coordina bien con otras skills del sistema? ¿Invoca correctamente otras skills con `Skill("nombre")`? ¿Evita duplicar contenido de otras skills? |
+| `output_quality` | 15% | ¿Los ejemplos de código son reales y funcionales? ¿Las reglas son específicas, no genéricas? ¿El contenido refleja patrones idiomáticos del framework? ¿Las directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación de por qué la regla existe? Una directiva sin justificación no permite al modelo generalizar a casos edge (ver W009). |
+| `scope_calibration` | 12% | ¿El scope es coherente? ¿No cubre demasiado? ¿Hay sección de "cuándo NO usar"? ¿El contenido es específico del dominio declarado? |
+| `progressive_disclosure` | 10% | ¿El SKILL.md principal es conciso (< 300 líneas)? ¿El contenido extenso está en `recursos/`? ¿Las referencias a recursos son claras y útiles? |
+| `token_efficiency` | 6% | ¿Hay contenido redundante o repetitivo? ¿Los ejemplos son concisos pero completos? ¿Se evita documentación genérica que no agrega valor? |
+| `robustness` | 5% | ¿Documenta casos edge y anti-patrones? ¿Cubre los errores más comunes del dominio? |
+| `structural_completeness` | 3% | ¿Tiene todas las secciones mínimas requeridas? ¿El frontmatter tiene todos los campos obligatorios? |
+| `code_template_quality` | 2% | ¿Los ejemplos de código compilan/ejecutan? ¿Usan sintaxis actual del lenguaje o framework? |
+| `ecosystem_coherence` | 2% | ¿El naming sigue las convenciones del sistema SWL (kebab-case)? ¿Los patrones son consistentes con las otras skills? |
+
+**Guía de calibración de scores:**
+- 90-100: Excelente — referente del sistema
+- 80-89: Sólido — listo para uso en producción
+- 70-79: Funcional — mejoras menores posibles
+- 60-69: Aceptable — requiere revisión antes de merge
+- 40-59: Deficiente — problemas claros que afectan efectividad
+- 0-39: Insuficiente — necesita reescritura
+
+## Paso 3 — Cálculo del score final
+
+Calcular score ponderado:
+
+```
+score_final = Σ(score_dimensión × peso_dimensión)
+
+Ejemplo:
+  triggering_accuracy    = 85 × 0.25 = 21.25
+  orchestration_fitness  = 78 × 0.20 = 15.60
+  output_quality         = 90 × 0.15 = 13.50
+  scope_calibration      = 72 × 0.12 =  8.64
+  progressive_disclosure = 80 × 0.10 =  8.00
+  token_efficiency       = 70 × 0.06 =  4.20
+  robustness             = 65 × 0.05 =  3.25
+  structural_completeness= 95 × 0.03 =  2.85
+  code_template_quality  = 85 × 0.02 =  1.70
+  ecosystem_coherence    = 90 × 0.02 =  1.80
+  ─────────────────────────────────────────────
+  score_final = 80.79
+```
+
+Asignar badge:
+
+```
+≥ 90  → Platino  — production-ready, puede usarse como referencia
+≥ 80  → Oro      — listo para merge
+≥ 70  → Plata    — necesita mejoras menores antes del merge
+≥ 60  → Bronce   — requiere revisión antes de merge
+< 60  → Sin badge — no hacer merge hasta corregir
+```
+
+### Gate de promoción para auto-evolucion-swl (G8)
+
+Este comando es el **gate obligatorio** del flujo de promoción de skills
+auto-generados desde `_userland/plugins/` a `habilidades/`. El agente
+`auto-evolucion-swl` invoca este comando antes de mover un skill al core
+(ver `agentes/auto-evolucion-swl.md` sección "Gate G8").
+
+Umbral de promoción:
+
+| Badge | Acción de auto-evolucion |
+|-------|-------------------------|
+| Platino, Oro, Plata | Promover a `habilidades/`, registrar en manifiestos |
+| Bronce | NO promover, devolver a `_userland/` con feedback |
+| Sin badge | NO promover, registrar rechazo en `.planning/evolution/promociones-rechazadas.jsonl` |
+
+Si un skill es rechazado ≥3 veces consecutivas, el agente escala al usuario
+con análisis de qué dimensiones bajan el score. Origen: ADR 0013 sección 3C.
+
+## Paso 4 — Emitir reporte y artefacto de procedencia
+
+Tras calcular el score final y el badge, persiste el **artefacto de
+evaluación con procedencia** (única fuente que `run-skill-evals.js
+--record-after` acepta para aprobar una evolución — anti-gaming,
+DT-AGP-SCORE-AUTODECLARADO):
+
+```bash
+swl-ses run-skill-evals <nombre> --emitir-evaluacion \
+  --score=<score-final> --badge=<badge> --producido-por=evaluar-skill
+# → escribe .planning/evolution/evaluaciones/<nombre>.json (fechado)
+#   y registra el evento tipo:evaluacion en evoluciones.jsonl
+```
+
+Es el ÚNICO archivo que este comando crea. Luego generar el siguiente
+reporte directamente en la conversación:
+
+```markdown
+## Evaluación de skill: [nombre]
+**Archivo**: habilidades/[nombre]/SKILL.md  (o agentes/[nombre].md)
+**Fecha**: [fecha actual]
+
+### Capa 1 — Análisis estático
+
+[PASS si no hay errores ni advertencias]
+[O listar cada E0XX / W0XX con descripción breve]
+
+### Capa 2 — Evaluación semántica
+
+| Dimensión | Peso | Score | Contribución |
+|-----------|------|-------|-------------|
+| Triggering accuracy | 25% | XX/100 | XX.XX |
+| Orchestration fitness | 20% | XX/100 | XX.XX |
+| Output quality | 15% | XX/100 | XX.XX |
+| Scope calibration | 12% | XX/100 | XX.XX |
+| Progressive disclosure | 10% | XX/100 | XX.XX |
+| Token efficiency | 6% | XX/100 | XX.XX |
+| Robustness | 5% | XX/100 | XX.XX |
+| Structural completeness | 3% | XX/100 | XX.XX |
+| Code template quality | 2% | XX/100 | XX.XX |
+| Ecosystem coherence | 2% | XX/100 | XX.XX |
+
+**Score final: XX.XX/100 — Badge: [🏆/🥇/🥈/🥉/❌] [Platino/Oro/Plata/Bronce/Sin badge]**
+
+### Hallazgos principales
+
+**Fortalezas:**
+- [2-3 aspectos bien ejecutados con evidencia específica del contenido]
+
+**Áreas de mejora:**
+- [hallazgos específicos con sugerencia concreta y línea o sección afectada]
+
+### Recomendaciones para subir el score
+
+[Lista priorizada de cambios concretos que mejorarían el score,
+ordenados de mayor a menor impacto. Incluir la dimensión afectada.]
+```
+
+## Paso 3 — Capa 3 opcional: Evals estructurados
+
+Si el artefacto tiene un archivo de evals en formato `skill-evals.schema.json`:
+
+```bash
+EVALS_PATH="habilidades/<nombre>/evals/evals.json"
+[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || EVALS_PATH="agentes/evals/<nombre>.evals.json"
+[ -f "$EVALS_PATH" ] && echo "EVALS_DISPONIBLES" || echo "SIN_EVALS"
+```
+
+Si existen, ejecutar la Capa 3:
+
+### 3.1 — Validar el artefacto contra el schema
+
+```bash
+# Validación mínima de estructura (zero-deps): comprobar que es JSON válido y
+# que tiene los campos obligatorios. Validación completa del schema queda para
+# consumidores externos (ajv, etc.) — SWL no arrastra deps.
+node -e "
+  const ev = require('./$EVALS_PATH');
+  const req = ['skill_name','schema_version','evals'];
+  const missing = req.filter(k => !(k in ev));
+  if (missing.length) { console.error('FALTAN:', missing.join(',')); process.exit(1); }
+  if (!Array.isArray(ev.evals) || ev.evals.length === 0) { console.error('evals vacío'); process.exit(1); }
+  console.log('OK', ev.evals.length, 'evals');
+"
+```
+
+Si falla la validación, reportar y continuar solo con Capa 1+2 (no bloquear).
+
+### 3.2 — Ejecutar cada eval contra el skill cargado
+
+Para cada `eval` del artefacto:
+
+1. Cargar el skill con `Skill("<nombre>")`.
+2. Enviar el `prompt` exacto al modelo en una respuesta aislada (sin historial).
+3. Capturar la respuesta.
+4. Para cada entrada de `expectations[]`, verificar si la respuesta la cumple
+   (match semántico honesto, no literal).
+5. Computar `pass = true` solo si TODAS las expectations se cumplen.
+6. Aplicar `weight` (default 1.0) al score.
+
+### 3.3 — Score de Capa 3
+
+```
+score_evals = sum(pass_i * weight_i) / sum(weight_i) * 100
+```
+
+### 3.4 — Integración con score final
+
+El score final combinado es:
+
+- Sin evals: `score_final = score_capa_1_2`
+- Con evals: `score_final = score_capa_1_2 * 0.7 + score_evals * 0.3`
+
+Reportar ambos separadamente para trazabilidad. Si `score_evals < 60`, marcar
+alerta: la skill puede ser declarativa pero falla en evaluación ejecutable.
+
+### 3.5 — Reporte por eval
+
+```
+| ID | Tags | Peso | Resultado | Expectations fallidas |
+|----|------|------|-----------|----------------------|
+| 0  | primary-flow | 1.0 | ✓ pass | — |
+| 1  | edge-case | 1.0 | ✗ fail | "La respuesta distingue X de Y" |
+| anti-pattern-substitution | anti-pattern,regression | 1.5 | ✓ pass | — |
+
+Score evals: 82.4/100 (peso 30% del final)
+```
+
+## Reglas de comportamiento
+
+- La Capa 1 es **determinista**: ejecutar los scripts Bash y registrar resultados exactos. No inferir ni interpretar.
+- La Capa 2 es **semántica honesta**: si la skill tiene problemas reales el score debe reflejarlos. No inflar scores por cortesía.
+- La Capa 3 es **opcional**: si no existe `evals/evals.json`, omitirla sin penalizar. Si existe, es autoridad primaria sobre Capa 2 en caso de discrepancia (los evals son reproducibles; la evaluación semántica no).
+- Un skill con Capa 3 activa y `score_evals ≥ 90` es candidato a badge **Platino** aunque Capa 2 sea 85.
+- Los evals NUNCA se inventan en este comando — solo se ejecutan los declarados por el autor del skill. Crear evals nuevos es tarea de `/swl:aprender` o del autor del skill directamente, siguiendo `plantillas/skill-evals-template.json`.
+- Si el archivo no existe, informar al usuario con el path exacto y terminar.
+- Si `--agente` se pasa sin nombre, listar los agentes disponibles y terminar.
+- El reporte siempre se emite en la conversación. El único archivo que se
+  crea es el artefacto de procedencia del Paso 4 (`.planning/evolution/
+  evaluaciones/<nombre>.json`) — nunca reportes sueltos.
+- Las "Fortalezas" deben ser específicas del contenido leído, no genéricas.
+- Las "Áreas de mejora" deben incluir la sección o línea aproximada donde se detectó el problema.
+- Si la Capa 1 genera errores E001–E010, reflejar el impacto en el score de la dimensión afectada antes de sumar las contribuciones ponderadas.
+- Score mínimo aprobado para merge: **80/100** (badge Oro). Por debajo de ese umbral, indicar claramente que **no está listo para merge**.