skill-router

Visión general de la skill skill-router

Qué hace skill-router

La skill skill-router actúa como selector de entrada en una configuración de Claude Code con múltiples skills. En lugar de resolver la tarea por sí misma, analiza la solicitud, decide qué skill especializada encaja mejor y hace preguntas de aclaración cuando la petición es demasiado vaga como para enrutarla con confianza. Si estás explorando agent-playbook o quieres que un flujo basado en skills sea realmente usable para tu equipo, skill-router es la pieza que primero reduce la incertidumbre.

Quién debería instalar skill-router

skill-router encaja mejor con usuarios que tienen más de una skill disponible y se encuentran a menudo con prompts como “¿qué skill debería usar?”, “ayúdame con este proyecto” o “usa una skill para esto”. Resulta especialmente útil para:

• equipos que quieren estandarizar cómo los agentes eligen skills
• usuarios que se están iniciando en una biblioteca de skills
• flujos de trabajo donde una misma petición general puede referirse a revisión, debugging, documentación, testing o trabajo de diseño

Si solo usas una o dos skills y ya sabes exactamente cuál invocar, skill-router aporta bastante menos valor.

El trabajo real que resuelve

El trabajo real de skill-router no es solo recomendar. Ayuda a convertir una solicitud poco especificada en un siguiente paso concreto: elegir una skill, explicar por qué y recopilar el contexto justo para poder avanzar. Esto importa porque muchos sistemas de skills fallan en el primer punto de decisión, mucho antes de que la calidad de ejecución se convierta en el cuello de botella.

Diferenciadores clave de skill-router

Frente a un prompt genérico del tipo “¿qué herramienta debería usar?”, skill-router tiene varias ventajas prácticas:

• está diseñado explícitamente para activarse pronto, antes de que se elija la skill especializada equivocada
• funciona con mentalidad de catálogo, mapeando la intención del usuario a las skills disponibles
• admite aclaraciones cuando la intención es ambigua
• registra las decisiones de enrutamiento mediante un hook after_complete, lo que resulta útil si quieres visibilidad sobre cómo se seleccionan las skills con el tiempo

Qué importa más antes de instalar skill-router

Antes de adoptar skill-router, revisa dos cosas:

1. si tu entorno realmente tiene un conjunto relevante de skills posteriores a las que enrutar
2. si tus usuarios suelen llegar con objetivos vagos en lugar de tareas ya bien definidas

La skill da lo mejor de sí como despachador dentro de un ecosistema de skills bien curado. Como recurso independiente pierde fuerza si el catálogo es pequeño, está desactualizado o muy personalizado sin que la lógica del router se haya actualizado en paralelo.

Cómo usar la skill skill-router

Contexto de instalación de skill-router

En este repositorio, skill-router está en skills/skill-router. El README del repo muestra un patrón de instalación basado en symlink:

ln -s ~/Documents/code/GitHub/agent-playbook/skills/skill-router/SKILL.md ~/.claude/skills/skill-router.md

Si tu configuración admite un gestor de skills, adapta la ruta de instalación a tu directorio local de skills. Lo importante es que SKILL.md quede accesible para el cargador de skills de Claude Code con el nombre de skill esperado.

Lee primero estos archivos

Para una evaluación rápida, lee:

1. skills/skill-router/SKILL.md
2. skills/skill-router/README.md

SKILL.md te muestra la lógica real de activación, las herramientas permitidas, el comportamiento de enrutamiento y el catálogo de skills disponible. README.md sirve más para entender el flujo general y ver ejemplos, pero los detalles clave para decidir la instalación están principalmente en SKILL.md.

Cuándo activar el uso de skill-router

Usa skill-router primero cuando la solicitud no esté clara en el nivel de selección de skill, por ejemplo:

• “Ayúdame con este codebase”
• “Usa una skill para mejorar esto”
• “¿Qué skill debería usar para este PR?”
• “Necesito ayuda, pero no sé si esto es debugging o refactorización”

El repositorio sitúa explícitamente a skill-router como punto de entrada por defecto para solicitudes relacionadas con skills, sobre todo cuando el usuario menciona “skill”, “which” o “how to”, o deja ver incertidumbre.

Qué entrada necesita skill-router

skill-router funciona mejor cuando la entrada incluye:

• el objetivo de la tarea
• el tipo de artefacto: PR, bug, README, suite de tests, archivo de diseño, commit, etc.
• el resultado deseado
• cualquier duda sobre qué tipo de ayuda se necesita

Eso le da al router suficiente señal para mapear la intención a una skill en lugar de quedarse en una aclaración demasiado amplia.

Convierte una solicitud vaga en un prompt enrutable con skill-router

Entrada débil:

• “Usa una skill para mi proyecto”

Entrada más sólida:

• “Necesito ayuda para revisar un pull request de una API en Node.js. Quiero feedback sobre corrección, seguridad y mantenibilidad. ¿Qué skill debería usar?”

Por qué esto funciona mejor:

• nombra el objeto de trabajo
• indica las dimensiones de calidad que importan
• acota la categoría de skill más probable
• sigue dejando el enrutamiento en manos de skill-router

Ejemplos de uso de skill-router

Para enrutamiento directo:

• “¿Qué skill debería usar para escribir un buen commit message para estos cambios staged?”
• “Necesito diagnosticar una suite de tests que falla en un servicio Python. ¿Qué skill encaja mejor?”
• “Usa skill-router for Skill Discovery en tareas de documentación, testing y refactorización en este repo.”

Para enrutamiento ambiguo, donde se espera aclaración:

• “Ayúdame a mejorar este proyecto antes del release.”
• “Usa una skill para este handoff de diseño.”
• “Estoy atascado y no sé si necesito debugging, review o refactorización.”

Flujo recomendado después del enrutamiento

Un flujo práctico sería:

1. invocar skill-router con la tarea en bruto
2. responder a sus preguntas de aclaración de forma breve pero concreta
3. confirmar la skill recomendada
4. pasar a la skill especializada con la tarea ya refinada
5. conservar el contexto aclarado para que la skill posterior arranque con suficiente detalle

Aquí es donde skill-router aporta valor de verdad: comprime el paso de una intención vaga a una invocación especializada y accionable.

Categorías del catálogo que puedes esperar en skill-router

Los fragmentos del repositorio muestran que skill-router se apoya en un catálogo que incluye áreas como:

• desarrollo core
• diseño y UX
• documentación y testing

Entre los ejemplos citados en el catálogo aparecen commit-helper, code-reviewer, debugger, refactoring-specialist, figma-designer y skills orientadas a documentación. Eso significa que skill-router resulta más útil cuando tu solicitud encaja en uno de esos carriles ya catalogados.

Límites prácticos del uso de skill-router

skill-router no sustituye a las skills especializadas. Es un selector, no el ejecutor final. Si tu tarea ya es lo bastante precisa como para ir directamente a debugger o code-reviewer, pasar antes por el router puede ser una sobrecarga innecesaria.

También depende de la calidad del catálogo. Si las skills que realmente tienes instaladas no coinciden con el catálogo de SKILL.md, la recomendación puede quedarse obsoleta o resultar engañosa.

Herramientas y comportamiento que conviene tener en cuenta

La skill puede usar Read, AskUserQuestion, WebSearch y Grep. En la práctica, la capacidad más importante aquí es AskUserQuestion, porque la calidad del enrutamiento mejora mucho cuando la ambigüedad se resuelve antes de recomendar.

También define un hook after_complete para session-logger con la razón “Log skill routing decisions.” Es un detalle de implementación útil si te importa la auditabilidad o quieres analizar qué tipos de tarea les cuesta más clasificar a los usuarios.

Preguntas frecuentes sobre la skill skill-router

¿skill-router es buena para principiantes?

Sí, especialmente si quienes empiezan ven una lista larga de skills disponibles y no saben por dónde comenzar. skill-router reduce esa barrera de entrada al convertir “necesito ayuda con X” en “usa esta skill concreta a continuación”.

¿skill-router sirve solo para Skill Discovery?

No, aunque skill-router for Skill Discovery es uno de sus casos de uso más potentes. También funciona bien como capa de enrutamiento estándar en flujos de trabajo de equipo, donde importa más que el primer triaje sea consistente que la familiaridad individual con el catálogo.

¿En qué se diferencia skill-router de un prompt normal?

Un prompt normal puede pedirle al modelo que recomiende una skill, pero skill-router empaqueta ese comportamiento como una skill reutilizable y activable, con señales de activación explícitas, un catálogo conocido y lógica de aclaración. Eso hace que el paso de enrutamiento sea más consistente y más fácil de llevar a la práctica.

¿Cuándo debería omitir skill-router?

Omítelo cuando:

• ya sabes cuál es la skill especializada correcta
• tu entorno tiene muy pocas skills
• el catálogo de skill-router no refleja el conjunto real de skills instaladas
• quieres ejecución directa de inmediato y hay poca ambigüedad

¿skill-router funciona bien en un ecosistema de skills personalizado?

Puede funcionar, pero solo si mantienes el catálogo alineado con tus skills reales. El valor del router depende de que el mapeo sea preciso. En un entorno muy personalizado, el principal riesgo de adopción es tener entradas de catálogo desactualizadas.

¿Compensa el esfuerzo de instalar skill-router?

Por lo general sí, si varias personas usan la misma biblioteca de skills o si los usuarios suelen hacer preguntas amplias y poco especificadas. Si el uso de skills es personal, poco frecuente y ya está bien interiorizado, la instalación puede ser opcional en lugar de esencial.

Cómo mejorar la skill skill-router

Dale a skill-router mejores señales de enrutamiento

La forma más rápida de mejorar los resultados de skill-router es darle mejores entradas desde el primer intento. Incluye:

• tipo de tarea
• artefacto o destino
• resultado deseado
• restricciones como lenguaje, zona del repo o fecha límite

Por ejemplo, “Necesito ayuda con un test de CI que falla en packages/api y quiero aislar la causa raíz” se enruta mucho mejor que “algo está roto”.

Responde a las preguntas de aclaración con detalles que ayuden a decidir

Cuando skill-router haga preguntas de seguimiento, no respondas con frases genéricas como “simplemente mejóralo”. Es mejor indicar qué tipo de mejora buscas: corrección, legibilidad, calidad de documentación, fidelidad UX, cobertura de tests o preparación para release. Eso cambia qué skill debería seleccionarse.

Mantén actualizado el catálogo de skills

La mejora estructural más importante para skill-router es el mantenimiento del catálogo. Si el repositorio añade, elimina o renombra skills posteriores, actualiza el router cuanto antes. Un router solo es tan bueno como las opciones que conoce.

Añade reglas de desambiguación más sólidas

El modo de fallo más habitual es el solapamiento entre categorías de skills cercanas, como debugging frente a refactorización o documentación frente a review. Mejora skill-router afinando las señales que separan:

• diagnóstico de mejora de código
• review de generación
• interpretación de diseño de planificación de implementación

Mejora los ejemplos para solicitudes realmente ambiguas

La skill ya muestra ejemplos directos y ambiguos. Para facilitar la adopción, añade más ejemplos que reflejen solicitudes internas reales, como:

• preparación para release
• CI fallando con causa raíz desconocida
• “deja este PR listo”
• convertir archivos de diseño en tareas de implementación

Ejemplos así ayudan a que los usuarios formulen peticiones que produzcan un enrutamiento más limpio.

Usa los logs de enrutamiento para refinar la skill

Como skill-router registra decisiones de enrutamiento mediante session-logger, revisa esos logs si los tienes disponibles. Fíjate en:

• bucles repetidos de aclaración
• solicitudes que se enrutan mal de forma sistemática
• intenciones frecuentes sin una skill claramente adecuada

Ese bucle de feedback es una de las formas más prácticas de mejorar skill-router con el tiempo.

Itera después de la primera recomendación

Si la primera recomendación parece cercana pero no del todo correcta, no descartes la skill de inmediato. Replantea la tarea con el contexto que falta:

• ¿cuál es exactamente el artefacto?
• ¿necesitas diagnóstico, review, generación o reestructuración?
• ¿qué resultado definirá el éxito?

Muchas veces eso convierte una recomendación amplia en el handoff correcto a la skill especializada en el segundo intento.

Mejora la adopción en equipo con una regla simple

Una regla operativa útil es: usa skill-router primero siempre que la solicitud del usuario trate de encontrar el tipo de ayuda adecuado, y no de ejecutar un trabajo ya claramente definido. Así mantienes el router centrado en el triaje de más valor, en lugar de forzarlo dentro de todos los flujos de trabajo.