e9tgldr/skill-router

Skill Router (Enrutador de Skills)

Actualmente hay ~170 skills instaladas aquí y varían enormemente en calidad y alcance, varias de ellas casi duplicadas entre sí (tres skills de diseño distintas para "que no parezca genérico", dos copias de impeccable, xlsx junto a xlsx-dsh). Elegir mal es el error más costoso disponible: una skill incorrecta consume todo su cuerpo en el contexto y desvía la respuesta, mientras que ninguna skill suele ser mejor que la equivocada.

Por lo tanto: primero enruta, luego trabaja. Este archivo es el procedimiento de enrutamiento. Es económico — un solo escaneo de archivo, una o dos llamadas a herramientas — y reemplaza la adivinanza basada en la lista de habilidades. El procedimiento es independiente de la instalación: los recuentos, nombres y familias que aparecen a continuación describen el catálogo sobre el que fue escrito, y la búsqueda se normaliza al catálogo que encuentre.

1. Lee la tarea antes de tocar nada

Responde a estas preguntas en silencio, en una línea cada una. Deciden la ruta, no el entregable.

• ¿Qué se produce? Un archivo (docx/xlsx/pdf/pptx/png), código en ejecución, una decisión, un mensaje, un plan.
• ¿Qué dominio? Frontend web, backend, datos, documentación, diseño, video/animación, VR, operaciones.
• ¿Existe un artefacto existente? Proyecto nuevo vs. modificar código de alguien: esto cambia la ruta de skills de construcción a skills de auditoría/revisión y comprensión primero.
• ¿Quién lee el resultado? Inversor, profesor, compañero de equipo, compilador. La audiencia cambia la skill de escritura, no la técnica.

Si la solicitud es una frase de intención pura ("hazme algo genial"), eso también es una señal de enrutamiento: significa que aún no se puede elegir ninguna skill y las preguntas son lo primero (paso 6).

2. Ruta rápida — consulta la tabla de enrutamiento

Lee references/task-types.md (relativo al directorio de esta skill). La primera tabla asigna ~40 formas de tareas comunes a una cadena de skills verificada en una sola pantalla; la segunda enumera herramientas específicas con nombres difíciles de adivinar (animation-vocabulary, cdn-caching, vercel-connect) que nadie busca, así que revísala antes de concluir que nada encaja.

• Coincidencia encontrada → ve al paso 4 con esa cadena. No busques también; la tabla es la respuesta y buscar de nuevo solo quema tokens.
• Sin coincidencia, o la coincidencia es parcial → paso 3.
• La tabla menciona skills que no tienes (una instalación diferente, un entorno diferente, una máquina nueva) → omite la tabla por completo y ve al paso 3. La tabla es el mapeo de una instalación; la búsqueda funciona en cualquier catálogo. Verifica con --doctor.

3. Busca en el catálogo

Un comando, no se necesita modelo:

# la ruta es relativa al directorio de esta skill
node scripts/find_skills.mjs "la página de inicio se ve genérica" -n 8
node scripts/find_skills.mjs --doctor      # qué raíces se escanearon, qué se encontró

Puntúa todas las skills instaladas por nombre + descripción (ponderación IDF, por lo que las palabras raras ganan sobre usuario/código/cuando) más una capa de conceptos curada para frases que no comparten vocabulario con la skill que necesitan. Imprime las mejores coincidencias con sus rutas SKILL.md, o NO HAY BUENA COINCIDENCIA cuando nada encaja.

Cómo consultarlo bien:

• Usa los sustantivos de la tarea, no la frase del usuario: hojas de cálculo gráficos csv, no "¿puedes convertir esto en algo con un gráfico?".
• Ejecuta 2–3 enfoques diferentes en lugar de una consulta larga: el enfoque del artefacto (pitch deck), el enfoque del dominio (recaudación de fondos para inversores), el enfoque del problema (el texto parece plantilla). Agrúpalos en una sola llamada bash si lo deseas.
• --explain imprime por qué se clasificó cada resultado, token por token — úsalo cuando un resultado parezca incorrecto en lugar de adivinar la causa.
• Cada resultado está etiquetado como [fuerte], [probable] o [débil]. [débil] significa que el enrutador está adivinando a partir de una palabra incidental — trátalo como una sugerencia, no una respuesta, y prefiere tu propio juicio. Si todos los resultados son débiles, el script lo indica.
• --all muestra el catálogo completo, --name pdf resuelve un nombre a una ruta, --json da salida legible por máquina, -n 20 amplía la lista cuando quieres ver los subcampeones (a menudo la respuesta correcta es la #4 para una consulta mal redactada).
• Los resultados están clasificados, no son autoritativos. Tú aún eliges.
• El script vive en el directorio scripts/ de esta skill. Si el entorno expone una ruta absoluta, úsala; de lo contrario, haz cd primero al directorio de la skill.
• Indexa lo que exista, no una lista fija: escanea los directorios de skills habituales por usuario y por proyecto en todos los entornos (~/.pi, ~/.claude, ~/.codex, ~/.agents, ~/.cursor, más <cwd>/skills y node_modules de plugins. Apunta a cualquier otro lugar con SKILL_ROUTER_ROOTS=/a/skills:/b/skills o --root /a/skills. En una máquina desconocida, ejecuta --doctor primero: enumera cada raíz, si existe, cuántas skills aportó, nombres duplicados y archivos SKILL.md que no pudo analizar. No se necesitan conceptos ni compuertas para un catálogo nuevo — son mejoras opcionales sobre la clasificación léxica; con cero de ellas, la búsqueda aún clasifica por nombre y descripción.

Si el script en sí no está disponible o una búsqueda no devuelve nada plausible dos veces, recurre a leer las descripciones de ~/.pi/agent/skills/ desde la lista de mensajes del sistema. No te detengas y no abras cinco archivos SKILL.md esperando que uno funcione.

4. Elige — reglas que mantienen la cadena corta

1. Proceso antes que implementación. Las skills que establecen cómo se ejecuta el trabajo (lluvia de ideas, escritura de planes, depuración sistemática, desarrollo guiado por pruebas, escritura de skills) se cargan antes que las skills que establecen qué aspecto tiene el resultado (diseño, docx, nextjs). Las skills de proceso con frecuencia te indican que cargues una skill de implementación a continuación — déjalas.

2. Máximo tres skills. Una es normal, dos es común, tres es el límite. Una cuarta significa que estás recolectando en lugar de decidiendo.

3. Una por familia. Nunca cargues dos miembros de la misma familia — toma la primera columna:

   Familia	Elige una
   Gusto frontend / anti-genérico	design-taste-frontend, ui-craft, impeccable, frontend-design, craft
   Copias duplicadas	impeccable (agents/) sobre impeccable-dsh; xlsx sobre xlsx-dsh; kimi/* sobre dsh/* a menos que la de dsh sea claramente más específica
   Formato de documento	exactamente la que coincida con el archivo: docx, pdf, pptx, xlsx
   Movimiento	animate (web), animate-expo (React Native) — no ambas
   Backend	backend-patterns, create-a-backend, api-design — como máximo dos
   Quest / VR	familia hz-* + metavr-cli; siempre empezar con hz-quest-verify-first

4. Respeta las compuertas de plataforma. hz-*, portal, metavr-cli necesitan un contexto Quest/VR; cloudbase necesita CloudBase; kimi-webbridge / kimi-cu necesitan un navegador real o una GUI de escritorio. Si la tarea no nombra la plataforma, la skill no aplica, sin importar lo bien que coincidan las palabras.

5. Justifica o rechaza. Para cada candidato, una cláusula: por qué esta. Si la cláusula es "menciona las mismas palabras", recházala. Dos skills pueden compartir vocabulario y seguir siendo para máquinas diferentes.

6. Ninguna es una respuesta válida. Si nada supera el listón, dilo en pocas palabras y realiza la tarea con tu propio juicio. Una skill faltante no es motivo para iniciar una skill medio relevante.

7. Reenruta solo en pivotes. Una nueva subtarea dentro del mismo flujo de trabajo no desencadena una búsqueda nueva. Un cambio de dominio (el usuario dice "en realidad, hazlo una presentación") sí.

5. Anuncia en una línea, luego continúa

Antes de hacer el trabajo, indica la ruta una vez:

Usando design-taste-frontend (página de inicio antipatrón) → animate para el héroe. Ninguna skill encaja en la parte de redacción; lo escribiré yo mismo.

Reglas para esa línea: una o dos oraciones, solo nombres + razones. Sin ensayos sobre el inventario de skills, sin "He seleccionado las siguientes skills para esta tarea porque…". El usuario quiere ver la decisión, no la deliberación. Si la ruta es inusual o te estás desviando a sabiendas de la tabla, eso es lo único que vale una cláusula adicional.

6. Pregunta solo lo que bloquea el trabajo

Aquí es donde el enrutamiento da su fruto: una skill elegida te dice lo que necesita saber, así que haz esas preguntas — y solo esas.

Pregunta solo cuando:

• la tarea tiene dos o más entregables genuinamente diferentes ("un póster" podría ser PNG o una presentación de diapositivas, y los archivos difieren),
• la audiencia o el formato son desconocidos y no se pueden adivinar por el contexto,
• las instrucciones de la skill elegida requieren una decisión que el usuario debe tomar (marca, presupuesto, credenciales, datos reales vs. simulados),
• una ruta costaría dinero real o tocaría producción.

No preguntes:

• qué skill usar — ese es el trabajo de esta skill. Pregunta sobre el resultado, deja que el enrutamiento se derive de la respuesta,
• nada que la solicitud ya responda, nada que el código base o los archivos respondan,
• nada que cubra un valor predeterminado sensato. Elige el valor predeterminado, di qué valor predeterminado elegiste en la línea de anuncio y sigue adelante. Este usuario prefiere ejecuciones largas sin supervisión sobre la confirmación paso a paso.

Forma: una llamada ask_user_question, como máximo 3 preguntas, 2–4 opciones cada una, opción recomendada primero con "(Recomendado)" en la etiqueta, una oración corta por opción que indique a qué se compromete. Nunca apiles un segundo cuestionario justo después del primero; si una respuesta plantea una nueva pregunta, prefiere un valor predeterminado razonable a otra ronda.

Si la skill que cargaste tiene su propia fase de descubrimiento o preguntas (la mayoría de las skills de planificación y diseño la tienen), ejecuta esa en lugar de inventar la tuya propia. Dos rondas de preguntas consecutivas parecen una táctica dilatoria.

7. Carga y ejecuta

• Lee el SKILL.md con la herramienta read, completamente, en la ruta que devolvió la búsqueda. Las skills hojeadas producen resultados superficiales.

• Resuelve cualquier ruta de references/, scripts/, assets/ relativa al directorio de esa skill — la salida de búsqueda imprime el archivo, por lo que el directorio padre es la raíz de la skill.

• Ejecuta los scripts tal como están escritos. Si un script necesita un argumento que no documenta, dilo en lugar de sustituir tu propia implementación.

• La skill gana los empates. Una vez cargada, sus instrucciones anulan las opiniones de este archivo sobre cómo hacer el trabajo y anulan las buenas prácticas genéricas. Este archivo solo la eligió.

• Si una skill cargada comienza con "pregunta al usuario primero" o "planifica antes de escribir código", haz eso — enrutar a una skill de proceso y luego saltarse su proceso es peor que no enrutar en absoluto.

• Si a mitad del trabajo descubres que la skill era incorrecta, dilo claramente y reenruta (paso 4). Trabajar silenciosamente alrededor de una skill incorrecta es el modo de fallo.

• Registra la corrección para que el mismo error no se repita:

  node scripts/find_skills.mjs --learn "<la frase que falló>" <skill-correcta>
  node scripts/find_skills.mjs --wrong "<la frase que falló>" <skill-incorrecta>
  

  Haz esto siempre que el usuario rechace una ruta, una skill cargada resulte ser la herramienta incorrecta, o hayas tenido que enrutar manualmente porque la búsqueda falló. Las correcciones aprendidas superan la puntuación léxica en consultas futuras similares y viajan con la instalación: así es como este enrutador mejora en un entorno que nunca ha visto.

8. Cierre

Una línea al final: qué skills se usaron y dónde terminó el artefacto. Luego, detente — sin resumen del contenido de las skills, sin ofrecimiento para explicar el enrutamiento.

Mantenimiento — cambiar el enrutador sin romperlo

El enrutador se puntúa, no se improvisa. scripts/eval_routing.mjs contiene 80 consultas realistas, cada una con el conjunto de skills que son respuestas genuinamente aceptables, más una docena de casos de compuerta (una consulta genérica de React nunca debe mostrar una skill de Quest). Ejecútalo antes y después de cualquier cambio:

node scripts/eval_routing.mjs
# puntuación: 80/80 (100.0%)  fugas de compuerta: 0
node ... --verbose      # clasificación por caso
node ... quest          # solo casos coincidentes

node scripts/smoke_portable.mjs   # catálogo foráneo + aprendizaje + escala de 600 skills

smoke_portable.mjs es la prueba de portabilidad: inventa 16 skills en dominios que este enrutador nunca ha visto (Kubernetes, Rust, Salesforce, Terraform…), verifica la clasificación, la robustez de paráfrasis, la compuerta portátil, el aprendizaje, los nombres duplicados, los catálogos vacios, las rutas con espacios, SKILL_ROUTER_ROOTS y una ejecución a escala de 600 skills. Si cambias la puntuación, ambos conjuntos deben mantenerse en verde — la evaluación protege la calidad en un catálogo conocido, la prueba de humo protege el comportamiento en uno desconocido.

Un cambio que aumenta la puntuación es una mejora; un cambio que la reduce es una regresión, sin importar lo ordenado que se lea el código. Los casos cuyas skills esperadas no están instaladas se omiten, no fallan, por lo que el conjunto se ejecuta en cualquier máquina.

Cuando una tarea real se enruta mal, corríge en la capa más económica que lo explique:

1. Palabras incorrectas para la misma idea → agrega una regla CONCEPTS curada en find_skills.mjs (regex when → puntuación boost, veto opcional unless y demote). Esta es la capa para la intención que no comparte vocabulario con la skill: "idea vaga, sin especificaciones" → brainstorming. ¿Es algo puntual? No recurras a esto — regístralo (--learn). CONCEPTS es para comportamiento general; la memoria es para "esta frase, esta skill".
2. Una forma de tarea recurrente → agrega una fila a references/task-types.md. No cuesta nada en tiempo de consulta y la ruta rápida omite la búsqueda por completo.
3. Una skill que pierde constantemente frente a vecinos ruidosos → agrégala a DEMOTE, o dale al ruidoso un demote en un concepto (por ejemplo, dashboard solo no debe superar a ui-craft con ui-craft-dense-dashboard).
4. Una skill de plataforma que se filtra en consultas genéricas → extiende GATES con las palabras que deben estar presentes para que sea elegible.
5. Una ruta que el usuario corrigió → --learn / --wrong, luego continúa. Revisa --memory ocasionalmente: si la misma skill sigue siendo corregida por el mismo tipo de redacción, promueve el patrón a CONCEPTS y --forget las entradas.

Agrega la consulta fallida a CASES primero, mírala fallar, luego corríge. No ajustes la puntuación en consultas que no anotaste — así es como el enrutador termina siendo bueno en tus ejemplos y malo en los del usuario.

Señales de alerta — estás racionalizando, detente

Pensamiento	Realidad
"Esto es simple, no necesita enrutamiento"	Enruta rápido, implementa rápido. La ruta rápida

… [truncado para la traducción]

Señales de alerta — estás racionalizando, detente

Pensamiento	Realidad
"Esto es simple, no necesita enrutamiento"	Enruta rápido, implementa rápido. La ruta rápida cuesta unos pocos tokens; una skill incorrecta cuesta miles. La línea de anuncio de una oración es más barata que el tiempo de inactividad de una skill incorrecta.
"Conozco las skills lo suficientemente bien como para omitir la búsqueda"	No las conoces. Hay ~170 skills en este directorio; estás sobreestimando tu memoria. La búsqueda encuentra docx cuando piensas "documento de Word"; la memoria encuentra "lo que sea que haya usado la última vez".
"Encontraré la skill mientras hago la tarea"	No lo harás. Leerás la primera que parezca cercana y te quedarás con ella. La búsqueda fuerza una decisión antes del trabajo, no durante.
"Esta consulta es única; no necesito el procedimiento de corrección"	Cada corrección que registras hace que la siguiente consulta única sea un poco menos única. El procedimiento está ahí por el usuario, no por la tarea.
"El --doctor es solo para depuración"	--doctor muestra qué catálogo realmente tienes, no el que esperas. Ejecútalo en cualquier máquina que no sea la tuya.