noeigenstate/SkillLens

SkillLens: uso y mantenimiento

SkillLens convierte cualquier SKILL.md en un diagrama de flujo animado con carriles: las tarjetas son pasos, los diamantes son decisiones, las líneas sólidas avanzan, las líneas discontinuas vuelven hacia atrás, puntos brillantes viajan a lo largo de las líneas y la tarjeta iluminada es el paso actual. La interfaz y el texto fijo del diagrama están en inglés (predeterminado) y chino; "中 / EN" en la esquina superior derecha cambia el idioma.

title: SkillLens
subtitle: SKILL.md · extracción automática · diagrama animado de salida
hero: SkillLens | importar · extraer · ajustar · exportar

trigger start: ¿Quieres entender una habilidad? [Cuando] {campana}
  lee el flujo de trabajo
  revísalo o preséntalo

lane L1: Importar [importar] (verde)
  step open: Abrir SkillLens [start.bat] {reproducir}
    lista cada habilidad local
    redibuja en cada guardado
  step add: Arrastrar o pegar [soltar] {subir}
    carpetas, archivos .md
    o texto pegado

lane L2: Extraer [extraer] (azul)
  decide has: ¿bloque skillflow? [¿skillflow?]
  step auto: Extracción heurística [auto] {destellos}
    secciones → carriles
    pasos / decisiones / bucles
  step check: Verificar contra la fuente [revisar] {ojo-escáner}
    haz clic en una tarjeta para ver su texto
    observa adónde conecta
  step tune: Ajustar en Estructura [editar] {lápiz}
    aplicar para redibujar
    copiar como bloque de código

lane L3: Salida [exportar] (púrpura)
  step draw: Dibujar desde el bloque [renderizar] {capas}
    carriles · tarjetas · diamantes
    puntos fluyen a lo largo de las líneas
  step out: Exportar [exportar] {descargar} +fin
    HTML / SVG / PNG
    grabar un mp4

flow:
  start -> open -> add -> has
  has -> auto : No
  has -> draw : Sí
  auto -> check -> tune -> draw -> out
  check ~> auto : corregir el texto fuente

Abrirlo

• Haz doble clic en start.bat: inicia un servidor local y abre el navegador. La lista contiene skills/ y examples/ del repositorio, más las habilidades locales de Claude (usuario y plugins), y se redibuja en menos de 2 segundos después de que cambie un SKILL.md. Es equivalente a npm start; npm run start:project lista solo las habilidades del propio repositorio.
• Abre index.html directamente: no necesita servidor, pero la lista proviene de data/skills.js, así que ejecuta npm run scan primero. La grabación de video y la traducción automática requieren el servidor.
• Carpetas adicionales: --root Nombre=<ruta>, o un archivo skillviz.config.json en la raíz del repositorio: {"roots":[{"label":"Habilidades del equipo","dir":"<ruta>"}]}.

Escribir habilidades que se diagramen bien

Las reglas de extracción están en src/extract.js. Un SKILL.md escrito de la siguiente manera se diagrama correctamente sin un bloque skillflow:

1. Coloca el procedimiento bajo un encabezado como ## Flujo de trabajo / ## Pasos / ## Proceso, como una lista ordenada o subsecciones ### numeradas; escribe cada paso como **Título corto**: explicación.
2. Inicia una decisión con "Si…" / "Si… o no…"; Si X, haz Y se convierte en un diamante con una salida Sí.
3. Escribe un enrutador como una tabla de dos columnas cuyo encabezado tenga "Estado / Condición / Si" a la izquierda y "Acción / Hacer / Ruta" a la derecha: se convierte en una cadena de decisiones de primera coincidencia.
4. Escribe bucles como "volver al paso N hasta que…".
5. Marca los pasos opcionales con un [Si es necesario] / [opcional] al inicio; la tarjeta obtiene un borde discontinuo.
6. Las reglas bajo ## Reglas / ## Notas se convierten en notas de color ámbar; el material bajo ## Referencia se convierte en un carril de referencia no conectado.

El bloque skillflow (control exacto)

Cuando un SKILL.md contiene un bloque ```skillflow, SkillLens dibuja solo eso. La forma más rápida de escribir uno: corrige el diagrama extraído automáticamente en el panel Estructura, haz clic en "Copiar como bloque de código" y pégalo en el SKILL.md. Sintaxis:

Línea	Significado
title: subtitle: `hero: título	subtítulo footer: window: cols: 4`
trigger id: Título [etiqueta] {icono}	la tarjeta desencadenante en la parte superior; las líneas sangradas debajo son su descripción
lane id: Título [etiqueta] (color tipo)	un carril; colores verde / azul / púrpura / verde azulado / rosa / ámbar / pizarra; tipos flow (predeterminado, encadenado) / ref (referencia, no conectado) / bare (sin marco)
step id: Título [etiqueta] {icono} +opcional +fin	una tarjeta de paso; +fin es el paso final (icono sólido), +opcional una tarjeta discontinua
decide id: ¿Pregunta? [subtítulo]	un diamante de decisión
note: texto	una nota dentro del carril
a -> b -> c : etiqueta bajo flow:	líneas hacia adelante; ~> es un bucle discontinuo; a -> "texto" : Sí es una salida que apunta a un texto corto

Sin flow:, las tarjetas de los carriles que no son de referencia se encadenan en orden. Los iconos son nombres de Lucide, listados en src/icons.js; para agregar uno, copia su cuerpo SVG de lucide-static.

Cambiar SkillLens

• Capas: markdown.js analiza → extract.js / dsl.js construyen la estructura → layout.js coloca tarjetas y enruta líneas → render.js dibuja el SVG y lo reproduce → app.js es la interfaz de usuario. Todas las cadenas de la interfaz y del diagrama están en i18n.js; agrega cada clave tanto en en como en zh.
• La página debe abrirse con doble clic, por lo que usa etiquetas <script> simples, sin módulos ES. Cada script se escribe como SV.mod.name = function (SV) {…} para que la exportación independiente pueda incluir el código con toString().
• Cada fotograma debe ser una función pura del tiempo t (sin animación CSS, Math.random ni reloj de pared), o la grabación de video fotograma a fotograma se rompe.
• Temas: Blueprint (predeterminado), Midnight y Glass. Los colores del diagrama están en THEMES en render.js, los colores de la interfaz en las variables CSS al inicio de style.css; cambia ambos juntos. Los detalles solo de Blueprint (cuadrícula, reglas, marcas de esquina, números de tarjetas, paso activo ámbar) están detrás de P.blueprint.
• Fuentes: Noto Sans SC (chino), Inter (latín), JetBrains Mono (etiquetas y rutas) de Google Fonts, con fuentes alternativas del sistema sin conexión. El diseño mide el texto con un canvas, por lo que debe esperar las fuentes: app.js limpia la caché de medidas y redibuja en loadingdone, y el modo de grabación más la exportación independiente llaman primero a document.fonts.load para el texto del diagrama. Mantén sincronizados el enlace de fuente en index.html, FONT / MONO en layout.js y el enlace en la plantilla independiente.
• Traducción automática: scripts/lib/translate.mjs (servidor, /api/translate) y useTranslation en src/app.js (qué cadenas del diagrama se traducen). Solo se traducen el texto del diagrama y el texto fuente abierto; las etiquetas, nombres de archivo, rutas y Sí / No se mantienen. Backend: el SDK de Anthropic cuando hay una clave API configurada y @anthropic-ai/sdk está instalado, de lo contrario la CLI local de Claude Code (en Windows llama a node_modules/@anthropic-ai/claude-code/bin/claude.exe directamente para evitar el citado de .cmd). La clave de caché es lang + \u0001 + texto en ambos lados.
• Verifica los cambios en un navegador sin cabeza: npm run scan, luego node scripts/record.mjs <habilidad> --seconds 3, o captura de pantalla mediante scripts/lib/cdp.mjs. Para una ejecución de regresión, ejecuta todas las habilidades a través de SV.extract → SV.layout → SV.render.toSVG y asegúrate de que no se lance ninguna excepción y ningún texto desborde su tarjeta.
• La grabación necesita Chrome / Edge local y ffmpeg; configura SV_CHROME / SV_FFMPEG si no se encuentran.
• Medios del hero de README: docs/promo.webp (la animación mostrada en línea) enlaza al docs/promo.mp4 sin procesar (el video completo con sonido). GitHub nunca reproduce un MP4 de repositorio: ni en línea en el README ni en la vista de archivo, sea cual sea su tamaño, por lo que el enlace sin procesar lo descarga; un reproductor en línea necesita el video subido a través del editor de github.com (una URL user-attachments). Usa WebP animado, no GIF: en los degradados oscuros de Blueprint, un GIF de 30 s supera los 20 MB, mientras que WebP se mantiene por debajo de 8 MB con un color más limpio. Desde un master 1080p: ffmpeg -i master.mp4 -vf "fps=15,scale=960:-1:flags=lanczos" -c:v libwebp -quality 70 -compression_level 6 -loop 0 -an docs/promo.webp y ffmpeg -i master.mp4 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p -c:a aac -b:a 160k -movflags +faststart docs/promo.mp4.