Skill Doctor
Diagnostica y mejora cualquier SKILL.md. Una brújula, no un manual — los estándares concretos viven en references/, se leen bajo demanda.
Flujo de diagnóstico tras la activación (cada paso debe producir salida visible)
Un paso sin salida visible se salta silenciosamente (experimento Seleznov, 2026). Imprime una línea de confirmación por paso. Bandera de auto-revisión: si esta sesión ya ha Editado/Escrito el SKILL.md objetivo, prefija cada línea de salida del doctor con
[self-review], y añade una línea al final del Paso 3: "la conclusión es autoevaluada, se recomienda una nueva revisión con un sub-agente nuevo."
Paso 1: Leer el SKILL.md objetivo, anunciar el inicio del diagnóstico
Lee el texto completo del SKILL.md que se está editando, ejecuta python3 <directorio-de-esta-habilidad>/scripts/check_listing_budget.py "<raíz_del_proyecto>" (pon la ruta entre comillas — los espacios son comunes), imprime dos líneas:
[skill-doctor] Auditing: <ruta> body=<N> líneas description=<M> caracteres
[skill-doctor] Budget (<plataforma>): <K> habilidades, <T> caracteres vs ≈<B> → <fits | OVERFLOW ×N.N>
Detecta automáticamente la plataforma (CC / Codex / Hermes / OpenClaw). Salida: 0 = cabe; 1 = desbordamiento; 2 = no disponible (sin plataforma / contexto desconocido → pregunta al usuario la plataforma + ventana). El desbordamiento es un AVISO a nivel de población, no un hallazgo contra la habilidad auditada: imprime los números para que el usuario lo sepa, pero NO acortes la descripción de esta habilidad por razones de presupuesto — el adelgazamiento es un pase global, nunca una corrección de una sola habilidad.
Paso 2: Evaluar contra las dimensiones
Elige las dimensiones a cargar desde el índice de referencias (sección Dimensiones) — lee solo las entradas cuyo cuándo-leer se activa. Después de cargar, imprime una línea:
[skill-doctor] Loaded: <lista>; Skipped: <lista con razón de una palabra>
Paso 2.5: Walkthrough en seco (solo cuando el cuerpo contiene un flujo de trabajo)
Siguiendo references/effect-dry-run.md, toma el prompt más típico y recorre los pasos del cuerpo, comprobando si la entrada/instrucción/salida están conectadas.
Cualquier enlace roto o ambigüedad → marca P0 (problema de efecto) y colócalo en la sección ❌ del Paso 3.
Imprime una línea:
[skill-doctor] Dry-run prompt: "<prompt>" broken links=<N>
Si el cuerpo no tiene flujo de trabajo (habilidad puramente de regla / tipo referencia), imprime:
[skill-doctor] Dry-run: skipped (no workflow)
Paso 2.6: Verificación de inyección en vivo (solo cuando la habilidad objetivo está en el ámbito de la sesión actual)
Comprueba si la habilidad objetivo aparece en la lista de habilidades disponibles de esta sesión con su descripción (no solo el nombre). Los 3 casos (inyectada / caída de presupuesto solo-nombre / salto fuera de ámbito) y la regla de aviso de población están en references/live-injection-check.md. Imprime una línea:
[skill-doctor] Live-injection: <injected | DROPPED (name-only) | skipped (<razón>)>
Paso 3: Generar el informe de diagnóstico
Formato estricto a continuación, imprime en la conversación:
[skill-doctor] Diagnosis
❌ Must fix (sorted P0→P3, definitions in references/priority-tiers.md)
[P0 effect break] <problema>: <por qué> → <solución>
[P1 structure] <problema>: <por qué> → <solución>
[P2 specificity] <problema>: <por qué> → <solución>
[P3 affects execution] <problema>: <por qué> → <solución>
⚠️ Suggested improvements (including purely cosmetic / verbose P3)
- <problema>: <por qué> → <solución>
✅ Checks passed
- <lista>
Regla de colocación P3: pregúntate "si no se corrige, ¿el próximo LLM que ejecute esta habilidad hará algo mal?" — sí → ❌; meramente feo/verboso → ⚠️. Consulta references/priority-tiers.md.
Cada problema debe dar un número de línea o campo específico — nada de vaguedades. Cuando el mismo tipo de violación aparece en varios lugares, enuméralos por separado — por ejemplo, contenido mal categorizado en tres subdirectorios debe ser 3 problemas, no 1 entrada fusionada.
Nombra el modo de fallo cuando corresponda (consulta references/predictability-glossary.md): prefija el hallazgo con [no-op] / [sediment] / [premature-completion] / [weak-leading-word] / [duplication] / [sprawl]. El nombre dice de qué tipo; el nivel P aún dice qué tan grave — son ortogonales, por lo que el prefijo nunca reemplaza al nivel.
Paso 4: Aplicar con Editar tras confirmación del usuario
Nunca Edites sin confirmación. Espera a que el usuario diga "arréglalo" antes de actuar.
Antes de actuar, aplica el control de tamaño y la verificación previa a la eliminación; después cierra el ciclo — procedimiento completo en references/apply-safety.md.
Después de arreglar, imprime una línea:
[skill-doctor] Applied <N> fixes to <ruta> body: <viejo>→<nuevo> líneas (<+X%>)
Referencia rápida de reglas estrictas
Las reglas estrictas cuantificadas (una violación es un error, no una sugerencia) viven en references/hard-rules.md — consúltalas en cada auditoría.
Excepción de respaldo
Cuando falta una ruta, el YAML no se analiza, o un script empaquetado (scripts/check_listing_budget.py + scripts/detect_platform.py / scripts/check_routes.py / scripts/eval_retrieval.py / scripts/check_desc_slim.py) falta o sale con código 2 — maneja según references/exception-fallback.md. Anuncia la excepción al usuario primero; nunca la saltes silenciosamente.
Salida e idioma
El informe en prosa sigue references/output-style.md (claro, seguro para terminal, conclusión primero). El cuerpo/referencias por defecto en inglés; marca el no-inglés injustificado como ⚠️ — política + las dos excepciones justificadas en references/language-policy.md.
Fuera del alcance de esta habilidad
- Si la funcionalidad real es correcta (eso es un error de lógica, no un problema de formato de habilidad)
- Convenciones específicas del proyecto (esas van en CLAUDE.md, no en una habilidad)
- Scripts de corrección únicos (descartados tras ejecutarse una vez, no deberían ser una habilidad)
Por qué existe esta habilidad
Por qué los LLM escriben mal SKILL.md como un manual, y cómo esta habilidad separa las comprobaciones mecánicas del juicio: references/rationale.md.