code-tour

Panorama general de la skill code-tour

Qué hace la skill code-tour

La skill code-tour crea archivos reutilizables de CodeTour .tour que guían al lector por un repositorio usando rutas de archivo y rangos de líneas reales. En lugar de una explicación puntual en el chat, genera un artefacto en .tours/ que se abre como una secuencia guiada en herramientas compatibles con CodeTour.

Usuarios y trabajos ideales para code-tour

Esta skill encaja con mantenedores, revisores y redactores técnicos que necesitan un recorrido estructurado por el código: tours de incorporación, tours de arquitectura, walkthroughs de PR, rastreos de RCA o rutas de revisión de seguridad. El trabajo real no es “resumir el repo”, sino “guiar a un lector específico por los archivos adecuados, en el orden correcto”.

Por qué elegir code-tour frente a un prompt genérico

Un prompt genérico suele devolver prosa desconectada del código. code-tour es más acotada, pero mucho más útil cuando necesitas navegación duradera: cada paso apunta a un archivo real y a un tramo concreto de líneas, con contexto narrativo y un flujo claro hacia el siguiente paso. Eso la hace especialmente fuerte como code-tour para Technical Writing, onboarding y flujos de revisión repetibles.

Restricciones clave antes de instalarlo

La skill code-tour solo crea archivos .tour en JSON; no sirve para editar código fuente, reescribir documentación extensa ni responder preguntas sueltas. Da mejores resultados cuando el repositorio ya tiene una estructura de archivos clara y la solicitud se limita a un servicio, una funcionalidad, una ruta de incidente o un diff de PR, en vez de “explicarlo todo”.

Cómo usar la skill code-tour

Instalar el contexto y leer primero qué revisar

Instala el repositorio padre de skills en tu flujo habitual de trabajo con skills y luego invoca code-tour desde ese entorno. En esta carpeta de la skill, SKILL.md es el único archivo fuente, así que léelo primero. No hay scripts auxiliares ni referencias aquí, lo que simplifica la adopción, pero también significa que debes aportar buen contexto del repo por tu parte.

Qué entrada necesita la skill code-tour

Para usar code-tour con buenos resultados, proporciona:

• audiencia: “new backend engineer”, “security reviewer”, “technical writer”
• objetivo: onboarding, arquitectura, revisión de PR, RCA, revisión de límites de confianza
• alcance: paquete, servicio, funcionalidad o archivos cambiados
• destino de salida: .tours/<name>.tour
• anclas del repo: archivos clave, puntos de entrada, módulos o contexto de commit/PR

Una solicitud débil es: “Haz un tour de este repo”.
Una solicitud más sólida es: “Crea un code-tour para Technical Writing que explique cómo fluyen las peticiones de auth a través de src/server.ts, middleware, validación de tokens y almacenamiento de sesión. Mantén 8–10 paradas y optimízalo para una nueva redactora de documentación”.

Convertir un objetivo difuso en un prompt útil

Un buen prompt para code-tour debe especificar lector, recorrido y exclusiones. Ejemplo:

• “Crea un tour de onboarding de code-tour para nuevos mantenedores del servicio de billing.”
• “Ancla cada parada a archivos reales y rangos de líneas.”
• “Empieza por el punto de entrada de la petición, luego carga de configuración, lógica de dominio, persistencia y pruebas.”
• “Evita herramientas administrativas no relacionadas.”
• “Escribe texto breve en cada paso que explique por qué importa este archivo y dónde mirar después.”

Esto ayuda a la skill a priorizar la secuencia sobre el resumen. Sin ese encuadre, los tours suelen convertirse en inventarios planos de archivos.

Flujo de trabajo práctico y comprobaciones de salida

Flujo recomendado:

1. Identifica al lector y la pregunta exacta.
2. Revisa el repo para localizar puntos de entrada, módulos centrales y pruebas de apoyo.
3. Traza un orden de paradas que refleje cómo se entiende realmente el sistema.
4. Genera el archivo .tour en .tours/.
5. Valida cada ruta de archivo y cada ancla de línea.
6. Abre el tour y recorta las paradas débiles.

Comprobaciones de calidad importantes:

• cada parada tiene una razón clara para existir
• la secuencia cuenta una historia, no solo enumera elementos
• las anclas de línea apuntan a código útil, no a bloques de importación
• el tour termina con “qué revisar después” o con un paso de síntesis

Preguntas frecuentes de la skill code-tour

¿Code-tour es buena para principiantes?

Sí, si el alcance es estrecho. Los principiantes aprovechan más un tour de un solo flujo, servicio o PR. Un code-tour de todo el repo suele saturarlos. Si estás incorporando a alguien nuevo, pide un recorrido corto por la ruta principal de ejecución más 1–2 archivos de apoyo.

¿Cuándo debo usar code-tour en lugar de documentación normal?

Usa code-tour cuando el lector necesite navegación archivo por archivo vinculada al código fuente. Usa documentación normal cuando necesites panorámicas conceptuales, comportamiento del producto o prosa extensa. Para equipos de redacción técnica, code-tour funciona mejor como complemento guiado por el código, no como sustituto de documentación pulida.

¿Cuáles son los límites principales de la skill code-tour?

No implementa funciones, no refactoriza código ni redacta colecciones amplias de documentación. También depende de rutas de archivo estables y de una estructura de código con sentido. Si el repo es caótico, generado o tiene nombres pobres, la skill aún puede producir un tour, pero el resultado requerirá una revisión manual más intensa.

¿Cuándo no encaja bien?

Evita code-tour si basta con una respuesta rápida en el chat, si el usuario quiere documentación en Markdown en lugar de un artefacto .tour, o si la solicitud es demasiado amplia para secuenciarla bien. También encaja peor cuando no hay una audiencia clara; los tours mejoran mucho en cuanto sabes para quién son.

Cómo mejorar la skill code-tour

Dar mejores indicaciones para leer el repositorio

La mayor mejora de calidad llega al aportar una ruta de descubrimiento antes de generar. Indica a la skill por dónde empezar: puntos de entrada, routers, handlers, servicios centrales, pruebas y configuración. Si es relevante, añade diffs de PR o notas de incidentes. Anclas mejores producen tours mejores.

Evitar fallos comunes de code-tour

Resultados débiles típicos:

• demasiadas paradas
• paradas ancladas a líneas poco importantes
• comentarios genéricos que valdrían para cualquier repo
• ausencia de audiencia clara
• sin transición narrativa entre pasos

Evita esto fijando un presupuesto de paradas, nombrando al lector y pidiendo en cada parada “por qué importa esto” más “qué revisar después”.

Mejorar los prompts con audiencia e intención

Para code-tour para Technical Writing, pide terminología, definiciones de fronteras y conceptos que merezcan documentación. Para revisión de PR, pide secuenciación de archivos cambiados y puntos de riesgo. Para onboarding, pide un orden centrado en arquitectura y deja las pruebas al final. El mismo repo, con un prompt distinto, produce una calidad de tour muy diferente.

Iterar después del primer borrador

Trata la primera salida como un mapa, no como el artefacto final. Abre el .tour, elimina paradas redundantes, ajusta los rangos de líneas y añade una parada de síntesis cerca del final. Si el tour parece un listado de directorios, acota el alcance y vuelve a generarlo. Los mejores resultados de la skill code-tour salen de una revisión enfocada, no de un primer pase demasiado amplio.