¿Qué hace skill-doctor?
Diagnostica una biblioteca de skills. Encuentra skills cuyas descripciones compiten por los mismos prompts y luego arregla el enrutamiento.
Cuándo ejecutarlo
- Has instalado muchos skills y "se sigue activando el incorrecto"
- Antes de publicar un paquete de skills (detecta colisiones que encontrarán los revisores)
- Después de añadir un skill (¿colisiona con uno existente?)
- Revisión periódica de salud en una biblioteca en crecimiento
Entrada
Apunta el motor a UNA de las siguientes opciones:
- Un directorio de skills (
<raíz>/<nombre>/SKILL.md), o - Un manifest.json de Claude Code (
skills-plugin/.../manifest.json)
Cómo ejecutar
El motor se encuentra en scripts/ junto a este archivo. Cero dependencias (stdlib de Python 3.8+).
# Desde el directorio que contiene este SKILL.md:
python3 -m scripts <ruta-a-skills-o-manifest> # Informe Markdown
python3 -m scripts <ruta> --format json --out report.json # salida para máquinas
python3 -m scripts <ruta> --fail-on critical # Puerta CI (código de salida 1)
Opciones comunes:
--merge-at 0.55— puntuación de colisión que activa una recomendación de FUSIONAR--disambig-at 0.30— puntuación que activa una recomendación de DESAMBIGUAR--vague-threshold 0.5— marcar descripciones más vagas que este valor--top 12— cuántas colisiones principales listar--format md|json|both
Lo que detecta (códigos de problema)
| Código | Gravedad | Significado |
|---|---|---|
DUPLICATE_TRIGGER | 🔴 | La misma frase de activación es reclamada por 2+ skills (causa principal de enrutamiento incorrecto) |
DUPLICATE_NAME | 🔴 | Dos skills comparten el mismo nombre |
MISSING_DESCRIPTION | 🔴 | El skill nunca puede activarse de manera confiable |
HIGH_OVERLAP | 🔴/🟠 | Dos descripciones son semánticamente demasiado cercanas |
VAGUE_DESCRIPTION | 🟠 | Con muchos rellenos, sin "usar cuando", sin activadores |
NAME_DIR_MISMATCH | 🟠 | nombre ≠ directorio (incumple la especificación) |
BAD_NAME_FORMAT | 🟠 | nombre incumple las reglas de minúsculas/guiones |
DESC_TOO_SHORT / DESC_TOO_LONG | 🟠/🟡 | Fuera del rango de 40–1024 caracteres |
NO_BOUNDARY | 🟡 | Falta la referencia cruzada "Para X, ver " |
BODY_TOO_LONG | 🔵 | Cuerpo de SKILL.md > 500 líneas |
Cómo funciona la puntuación (en una línea)
colisión = 0.50·coseno(TF-IDF de descripciones)
+ 0.35·jaccard(frases de activación)
+ 0.15·jaccard(palabras clave del dominio)
Bandas: <0.22 BAJA · 0.22 MEDIA · 0.38 ALTA · 0.55 CRÍTICA.
Consulta references/scoring.md para conocer la justificación completa.
Flujo de trabajo para el agente
- Ejecuta el motor en la ruta de skills del usuario → lee el informe Markdown.
- Resume la puntuación de salud, los peores grupos y los activadores duplicados.
- Para cada recomendación principal, propón la edición concreta:
MERGE→ redacta una descripción combinada, sugiere el nombre que sobrevive.ABSORB→ nombra el skill a eliminar y hacia dónde se mueven sus activadores.DISAMBIGUATE→ escribe las dos líneas de frontera espejo ("Para X, ver Y.").
- Ofrece aplicar las reescrituras de descripción (edita el frontmatter de cada SKILL.md).
- Vuelve a ejecutar para confirmar que la puntuación de salud ha mejorado.
Salida
- Un informe Markdown: puntuación de salud, colisiones principales, grupos confundibles, tabla de activadores duplicados, recomendaciones, lista completa de problemas, mapa de calor ASCII.
- JSON opcional (
--format json) para puertas CI u otras herramientas.
Reglas
- El motor es de solo lectura — nunca edita skills. Las reescrituras son aplicadas por el agente (tú) solo después de la aprobación del usuario.
- Nunca elimines un skill sin confirmación explícita.
- Al reescribir descripciones, conserva cada frase de activación real de la que depende el usuario; solo muévelas o desambígalas — no las elimines.
Consulta references/methodology.md para el algoritmo y references/issue-catalog.md
para saber cómo arreglar cada tipo de problema.