Skill Doctor —— Herramienta de Diagnóstico de Salud para Skills
Flujo de Trabajo
- Leer el directorio del Skill especificado
- Verificar la existencia de archivos principales (SKILL.md, gotchas.md, etc.)
- Ejecutar script para obtener informe estructurado:
python scripts/analyze_skill.py <ruta_del_skill> --output json, obteniendo la puntuación, problemas y sugerencias de cada ítem de revisión - Para cada ítem con baja puntuación (<70), complementar el informe del script con sugerencias de optimización específicas + puntuación esperada tras mejora + estimación de esfuerzo
- Listar todos los ítems optimizables y solicitar al usuario que seleccione cuáles aceptar
- Optimizar cada ítem aceptado por el usuario (modificar archivos directamente)
- Una vez completada la optimización, volver a ejecutar el script para un nuevo diagnóstico y generar un informe comparativo antes/después
El Agente se encarga de la capa inteligente (sugerencias de optimización, interacción con el usuario, ejecución de modificaciones), mientras que el script maneja la capa estable (cálculo de puntuaciones, salida estructurada). Consulte scripts/analyze_skill.py para más detalles sobre el script.
Las Nueve Dimensiones de Revisión
| Ítem de revisión | ¿Qué revisa? | Criterio de aprobación |
|---|---|---|
| Revisión de description | Si está redactada como condición de activación, no como descripción funcional | Contiene palabras clave de activación, longitud < 100 caracteres |
| Revisión de gotchas | Si hay registro de puntos problemáticos | gotchas.md existe y no está vacío |
| Revisión de organización de archivos | Si está organizado según el estándar de tres categorías | El directorio raíz solo contiene SKILL.md + gotchas.md + examples.md, los materiales de referencia en reference/, los scripts en scripts/, la configuración en config/ |
| Revisión de restricciones excesivas | Si hay restricciones excesivas en la ruta de ejecución | Sin flujos rígidos como "primer paso, segundo paso" |
| Revisión de conocimiento conocido | Si repite contenido ya conocido por el Agente | Sin tutoriales como "¿Qué es X?", "Cómo usar Y" |
| Revisión de configuración de memoria | Si existe config.json | config.json existe y tiene una configuración razonable |
| Revisión de scripts | Si necesita scripts pero faltan | Si requiere capacidades estables, existe el directorio scripts/ |
| Revisión de hooks | Si la configuración de hooks es correcta | PreToolUse/PostToolUse con el formato correcto |
| Revisión de formato markdown | Si el formato es correcto | YAML, tablas, bloques de código con formato correcto |
Formato del Informe de Diagnóstico
{
"skill_name": "xxx",
"overall_score": 55,
"grade": "D",
"check_results": {
"description": {"score": 50, "issues": ["Redactado como descripción funcional"], "suggestions": ["Cambiar a formato de condición de activación"], "expected_gain": 40},
"gotchas": {"score": 40, "issues": ["gotchas.md está vacío"], "suggestions": ["Agregar al menos 3 puntos problemáticos reales"], "expected_gain": 50}
},
"optimization_options": [
{"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
"effort": "bajo", "action": "Reescribir description como condición de activación",
"token_saved_per_call": 50, "time_saved_per_call_sec": 0},
{"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
"effort": "medio", "action": "Agregar puntos problemáticos reales",
"token_saved_per_call": 0, "time_saved_per_call_sec": 180}
],
"overall_after_accept_all": 85,
"total_benefits": {
"token_saved_per_call": 200,
"time_saved_per_call_sec": 300
}
}
Reglas de Estimación de Beneficios
| Tipo de optimización | Ahorro de tokens (por llamada) | Ahorro de tiempo (por llamada) | Descripción |
|---|---|---|---|
| Acortar description | Cada carácter extra × 1 token | — | Reduce la carga del contexto |
| Complementar gotchas | — | 2-5 minutos por punto problemático | Evita depuración repetitiva en problemas conocidos |
| Dividir archivos | (líneas originales - líneas nuevas) × 3 tokens | — | Mover materiales de referencia a reference/; no cargan en el contexto a menos que sea necesario |
| Restricciones excesivas → marcos de decisión | Cada paso rígido × 20 tokens | 10-30 segundos por paso | Reduce la ejecución de pasos inútiles |
| Eliminar conocimiento conocido | Longitud del párrafo tutorial en tokens | — | No repetir contenido que el Agente ya conoce |
| Encapsular en script | — | 1-3 minutos por cada vez | Evita que el Agente reescriba el mismo código cada vez |
Los beneficios son estimaciones por llamada individual; los valores reales pueden variar según el contenido del Skill y su uso.
Sobre la "duración": La "duración" en el informe se refiere al desperdicio adicional causado por defectos de diseño, no al tiempo total de ejecución del Skill. Incluye:
- Falta de gotchas → El Agente depura repetidamente problemas conocidos (2-5 minutos cada vez)
- Restricciones excesivas → El Agente ejecuta pasos rígidos sin sentido (10-30 segundos por paso)
- Falta de script → El Agente reescribe el mismo código cada vez (1-3 minutos cada vez)
Lógica de comparación: Valor antes de la optimización = suma de estos desperdicios; después de la optimización, el desperdicio se reduce a ~0; "ahorro" = cantidad de desperdicio eliminado. La ejecución del Skill después de la optimización sigue requiriendo tiempo, pero ya no tiene estas pérdidas adicionales.
Presentación de Sugerencias de Optimización
Después de generar el informe, mostrar los ítems optimizables como una lista al usuario, cada uno incluyendo:
### 🔧 Ítems Optimizables
| # | Ítem | Punt. Actual | Punt. Esperada | Mejora | Esfuerzo | Tokens/llamada | Tiempo/llamada | Acción |
|---|------|-------------|----------------|--------|----------|---------------|----------------|--------|
| 1 | description | 50 | 90 | +40 | bajo | ~50 | — | Reescribir como condición de activación |
| 2 | gotchas | 40 | 90 | +50 | medio | — | ~3min | Agregar puntos problemáticos reales |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
**Después de aceptar todas las optimizaciones**: 55 pts (D) → 85 pts (B), mejora de 30 pts
### 📈 Beneficios Totales (por llamada)
- Ahorro de tokens: ~200/llamada
- Ahorro de tiempo: ~5 minutos/llamada
- Prevención de errores: Con gotchas complementados, se evitan errores comunes
> **Nota sobre la métrica de tiempo**: El "ahorro de tiempo" aquí se refiere al **desperdicio adicional causado por defectos de diseño**, no al tiempo total de ejecución del Skill:
> - Falta de gotchas → El Agente depura repetidamente (2-5 min cada vez)
> - Restricciones excesivas → El Agente ejecuta pasos inútiles (10-30 seg por paso)
> - Falta de script → El Agente reescribe el mismo código (1-3 min cada vez)
> - Valor antes de optimización = suma de desperdicios, después de optimización el desperdicio se elimina, "ahorro" = cantidad de desperdicio eliminado
Seleccione:
- **"Aceptar todo"** — Optimizar todos los ítems de una vez
- **"Aceptar 1,3"** — Optimizar solo los ítems especificados
- **"Saltar"** — Solo ver el informe sin realizar optimizaciones
Ejecución Después de la Confirmación del Usuario
- Una vez que el usuario selecciona, modificar los archivos correspondientes uno por uno
- Marcar el estado al completar cada ítem
- Una vez finalizado todo, volver a ejecutar el diagnóstico para generar un informe comparativo
Formato del Informe Comparativo Antes/Después
## 📊 Comparación Antes/Después
| Ítem de revisión | Antes de optimizar | Después de optimizar | Cambio |
|-----------------|--------------------|----------------------|--------|
| description | 50 (descripción funcional) | 90 (condición de activación) | +40 ⬆️ |
| gotchas | 40 (vacío) | 90 (completo) | +50 ⬆️ |
| ... | ... | ... | ... |
| **Puntuación total** | **55 (D)** | **85 (B)** | **+30 ⬆️** |
### 📈 Beneficios Totales (por llamada)
| Dimensión | Antes de optimizar | Después de optimizar | Ahorro |
|-----------|--------------------|----------------------|---------|
| Tokens | ~800/llamada | ~600/llamada | ~200/llamada |
| Desperdicio de tiempo | ~5min | ~0 | ~5min |
| Archivo principal | 466 líneas | 75 líneas | -84% |
> El desperdicio de tiempo son los costos adicionales causados por defectos de diseño (depuración en problemas conocidos, pasos redundantes, etc.), no el tiempo total de ejecución del Skill. Consulte [Reglas de estimación de beneficios](#reglas-de-estimación-de-beneficios).
### Archivos Modificados
- `SKILL.md` — Reescribir description
- `gotchas.md` — Agregar 5 puntos problemáticos reales
Ejemplo de Interacción Completa
Consulte el ejemplo 9 en examples.md
Niveles de Puntuación
- A (90-100 pts): Excelente, sigue todas las mejores prácticas
- B (75-89 pts): Bueno, con poco margen de mejora
- C (60-74 pts): Aceptable, con puntos de mejora evidentes
- D (<60 pts): No apto, necesita reestructuración
Lista de Verificación Detallada
Consulte checklists.md
Puntos Problemáticos Comunes
Consulte gotchas.md
Ejemplos de Optimización
Consulte examples.md
Scripts
La lógica central del diagnóstico está encapsulada en scripts/analyze_skill.py. El Agente lo invoca para obtener puntuaciones estructuradas:
python scripts/analyze_skill.py <ruta_del_skill> --output json # Paso 3: Obtener informe de puntuación
python scripts/analyze_skill.py <ruta_del_skill> --output markdown # Opcional: Generar informe legible por humanos
El script se encarga de: cálculo de puntuación, detección de problemas, determinación del nivel (capa estable) El Agente se encarga de: generación de sugerencias de optimización, interacción con el usuario, ejecución de modificaciones de archivos (capa inteligente)