code-tour
por alirezarezvanicode-tour ayuda a los agentes a crear archivos .tour de VS Code CodeTour para recorridos de repositorios orientados a distintas audiencias, con anclajes reales a archivos y líneas. Úsalo para onboarding, recorridos de arquitectura, revisiones de PR, rutas de RCA, guías para colaboradores y flujos de Technical Writing en los que la salida debe ser un artefacto .tours navegable, no cambios en el código fuente.
Esta skill obtiene 78/100, lo que la convierte en una candidata sólida para usuarios del directorio que quieren que los agentes generen recorridos VS Code CodeTour con menos incertidumbre que usando un prompt genérico. SKILL.md ofrece activadores, alcance, restricciones y un flujo de descubrimiento claros, pero la confianza para adoptarla se ve limitada por la ausencia de archivos de apoyo, instrucciones de instalación o herramientas de validación.
- Muy fácil de activar: el frontmatter cubre explícitamente solicitudes de code tours, onboarding, arquitectura, revisión de PR, RCA, guía para colaboradores y recorridos estructurados.
- Alcance operativo claro: indica al agente que cree únicamente archivos JSON CodeTour .tour en .tours/ y que nunca modifique el código fuente.
- Guía práctica de flujo de trabajo: pide al agente inspeccionar primero el repo, leer archivos README/config, mapear la estructura, identificar puntos de entrada y asegurarse de que cada ruta del tour exista.
- No incluye archivos de apoyo, ejemplos, README ni comando de instalación, por lo que los usuarios deben basarse por completo en SKILL.md para adoptarlo.
- La evidencia del repositorio muestra orientación de flujo de trabajo, pero no validación ejecutable para el JSON .tour generado ni para la precisión de los números de línea.
Descripción general de code-tour skill
Qué crea code-tour
La code-tour skill ayuda a un agente de IA a generar archivos JSON CodeTour .tour para la extensión VS Code CodeTour. Un tour es un recorrido guiado que vincula pasos explicativos con archivos y números de línea reales, normalmente guardado en .tours/. La skill está pensada para explorar repositorios de forma estructurada, no para editar código: su límite principal es crear únicamente archivos de tour y evitar modificar el código fuente.
Mejor uso en Technical Writing y onboarding
Usa code-tour para Technical Writing cuando necesites una ruta de onboarding, una guía para contribuidores, un recorrido de arquitectura, un tour de revisión de PR, una ruta de revisión de seguridad, un hilo de análisis de causa raíz o un recorrido de “explica cómo funciona esto”. Funciona mejor cuando el lector tiene una persona clara: nuevo ingeniero backend, mantenedor frontend, revisor, responsable de incidentes, staff engineer o stakeholder no técnico que necesita una ruta curada por los detalles de implementación.
Qué la hace mejor que un prompt genérico
Un prompt genérico puede resumir archivos de forma imprecisa. La code-tour skill orienta al agente hacia un artefacto utilizable: pasos narrativos adaptados a una persona, con anclajes concretos a archivos y líneas. Eso importa porque un tour debe poder navegarse en VS Code, debe referenciar rutas existentes y debe explicar por qué cada parada importa, en lugar de volcar un resumen de carpetas. El resultado útil no es “qué contiene el repo”, sino “dónde debería hacer clic este lector primero, después, y por qué”.
Consideraciones antes de instalar
La skill tiene un SKILL.md enfocado y no incluye scripts, reglas ni paquetes de referencia adicionales. Eso hace que code-tour install sea liviano, pero también significa que la calidad depende mucho del acceso al repositorio y del nivel de detalle del prompt. Funciona mejor cuando el agente puede inspeccionar el árbol de archivos, el README, los archivos de configuración y los puntos de entrada del código fuente. No es una buena opción si solo quieres documentación en prosa, diagramas Mermaid, ediciones de código fuente o un tour sobre archivos que el agente no puede leer.
Cómo usar code-tour skill
Instalación de code-tour y contexto del repositorio
Instala desde el repositorio de origen con tu herramienta de skills, por ejemplo:
npx skills add alirezarezvani/claude-skills --skill code-tour
Después de instalar, verifica la ruta de la skill si hace falta: engineering/code-tour/skills/code-tour/SKILL.md. En el proyecto de destino, el agente debería inspeccionar primero el directorio raíz, README.md, la configuración de paquetes o build, y el primer o segundo nivel de carpetas antes de redactar. El tour debe guardarse como un archivo JSON .tour dentro de .tours/, compatible con la extensión VS Code CodeTour.
Entradas que necesita la skill
Para un buen code-tour usage, proporciona cinco elementos: la audiencia, el objetivo, el alcance, la profundidad deseada y cualquier archivo o nombre de feature que deba incluirse. Solicitud débil: “make a tour of this repo.” Solicitud fuerte: “Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines.”
Si el tour es para Technical Writing, añade el propósito de publicación: documento de onboarding, apoyo para release notes, guía interna de arquitectura, ayuda para revisión o artefacto de aprendizaje posterior a un incidente.
Flujo de trabajo sugerido para un primer tour
Empieza con descubrimiento, no con redacción. Pide al agente que identifique el propósito del proyecto, lenguajes, frameworks, puntos de entrada y directorios importantes. Después, elige una ruta narrativa: de configuración a primera feature, de request a response, de acción de UI a API, de síntoma de bug a causa raíz, o de diff de PR a riesgo. Solo entonces debería generar el archivo .tour. Esta secuencia reduce anclajes rotos y evita un “tour de carpetas” superficial que nombra directorios sin enseñar al lector cómo funciona el sistema.
Patrón práctico de prompt
Usa un prompt como este:
“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”
Funciona porque le da al agente un marco de decisión, no solo un tema.
Preguntas frecuentes sobre code-tour skill
Cuándo conviene usar code-tour en lugar de documentación
Usa code-tour cuando el producto sea la navegación por el código. La documentación tradicional es mejor para conceptos, políticas o referencias de API. Un CodeTour es mejor cuando los lectores necesitan abrir archivos en secuencia y entender relaciones entre rutas, servicios, tests, configuraciones y puntos de entrada.
¿Pueden los principiantes usar la code-tour skill?
Sí, pero los principiantes deberían acotar la solicitud. Pide primero un tour pequeño: una feature, una ruta de bug o un corte de arquitectura. Las solicitudes amplias como “explain the entire codebase” suelen generar tours ruidosos, salvo que el repositorio sea muy pequeño. En repositorios muy pequeños, con menos de un puñado de archivos fuente, un tour rápido con profundidad moderada suele ser suficiente.
¿code-tour edita el código de mi aplicación?
No. El resultado esperado es un archivo JSON .tour, normalmente ubicado en .tours/. El límite explícito de la skill es evitar modificar código fuente. Si tu flujo necesita correcciones de código, tests o refactors, usa primero otra skill de ingeniería y luego usa code-tour para documentar la ruta resultante.
Qué puede impedir un buen resultado con code-tour
Los mayores bloqueos son la falta de acceso al repositorio, una audiencia vaga, la ausencia de límites de alcance y rutas de archivo sin verificar. Los pasos de CodeTour dependen de anclajes reales. Si el agente no puede leer los archivos de destino o los números de línea cambian mucho durante ediciones activas, genera el tour después de que el código se estabilice, o pide primero anclajes a nivel de ruta y deja el refinamiento de líneas para más adelante.
Cómo mejorar code-tour skill
Haz que los prompts de code-tour sean específicos por persona
La forma más rápida de mejorar el resultado de code-tour es nombrar al lector. “New contributor” produce una ruta distinta a “security reviewer” o “technical writer preparing onboarding material.” Incluye qué sabe ya el lector y qué debe ser capaz de hacer después del tour. Esto cambia la selección de pasos, la profundidad de las explicaciones y el vocabulario.
Pide una narrativa, no un inventario
Un tour débil enumera archivos. Un tour sólido cuenta una historia: dónde empieza la ejecución, cómo se mueven los datos, dónde se toman decisiones, dónde están los riesgos y qué tests prueban el comportamiento. Pide al agente que conecte cada parada con la anterior y que incluya una frase de “por qué esto importa” en cada paso. Esto es especialmente valioso para Technical Writing, porque el artefacto final se vuelve didáctico, no solo clicable.
Itera después del primer resultado
Después del primer borrador .tour, revisa tres problemas: rutas de archivo rotas o imprecisas, pasos demasiado amplios y transiciones faltantes. Luego pide revisiones específicas: “split step 4 into route and service steps,” “add the test that covers this behavior,” o “reduce frontend detail and focus on API error handling.” Iterar suele ser más eficaz que pedir un tour perfecto de todo el repo en una sola pasada.
Valida los anclajes antes de compartir
Antes de publicar un CodeTour, ábrelo en VS Code con la extensión CodeTour y confirma que cada ruta y línea lleva al lugar esperado. Si el repositorio cambia con frecuencia, prioriza tours vinculados a archivos de arquitectura estables, tests o puntos de entrada, y regenera los números de línea después de refactors grandes. Así la code-tour skill sigue siendo útil como recurso de onboarding, en lugar de convertirse en un mapa obsoleto.