SkillLens

SkillLens: uso e manutenção

SkillLens transforma qualquer SKILL.md em um fluxograma swimlane animado: cartas são etapas, diamantes são decisões, linhas sólidas avançam, linhas tracejadas fazem loops, pontos brilhantes viajam ao longo das linhas e a carta acesa é a etapa atual. A interface e o texto fixo do gráfico vêm em inglês (padrão) e chinês; "中 / EN" no canto superior direito alterna.

title: SkillLens
subtitle: SKILL.md in · extração automática · fluxograma animado out
hero: SkillLens | importar · extrair · ajustar · exportar

trigger start: Quer entender um skill [Quando] {bell}
  ler o fluxo de trabalho
  verificar ou apresentá-lo

lane L1: Importar [import] (green)
  step open: Abrir SkillLens [start.bat] {play}
    lista todos os skills locais
    redesenha a cada salvamento
  step add: Arrastar ou colar [drop] {upload}
    pastas, arquivos .md
    ou texto colado

lane L2: Extrair [extract] (blue)
  decide has: bloco skillflow? [skillflow?]
  step auto: Extração heurística [auto] {sparkles}
    seções → lanes
    etapas / decisões / loops
  step check: Verificar com a origem [review] {scan-eye}
    clique em uma carta para ver seu texto
    veja onde ela se conecta
  step tune: Ajustar na Estrutura [edit] {pencil}
    aplicar para redesenhar
    copiar como bloco de código

lane L3: Saída [export] (purple)
  step draw: Desenhar a partir do bloco [render] {layers}
    lanes · cartas · diamantes
    pontos fluem ao longo das linhas
  step out: Exportar [export] {download} +end
    HTML / SVG / PNG
    gravar um mp4

flow:
  start -> open -> add -> has
  has -> auto : Não
  has -> draw : Sim
  auto -> check -> tune -> draw -> out
  check ~> auto : corrigir o texto fonte

Abrir

• Clique duas vezes em start.bat: inicia um servidor local e abre o navegador. A lista contém os skills/ e examples/ do repositório, além dos skills locais do Claude (usuário e plugins), e redesenha em menos de 2 segundos após uma alteração no SKILL.md. Equivalente a npm start; npm run start:project lista apenas os skills do próprio repositório.
• Abra index.html diretamente: sem servidor, mas a lista vem de data/skills.js, então execute npm run scan primeiro. A gravação de vídeo e a tradução automática precisam do servidor.
• Pastas extras: --root Nome=<caminho>, ou um skillviz.config.json na raiz do repositório: {"roots":[{"label":"Skills da equipe","dir":"<caminho>"}]}.

Escrevendo skills que são bem visualizados

As regras de extração estão em src/extract.js. Um SKILL.md escrito assim é visualizado corretamente sem um bloco skillflow:

1. Coloque o procedimento sob um título como ## Fluxo de trabalho / ## Etapas / ## Processo, como uma lista ordenada ou subseções ### numeradas; escreva cada etapa como **Título curto**: explicação.
2. Inicie uma decisão com "Se …" / "Caso …"; Se X, faça Y se torna um diamante com saída Sim.
3. Escreva um roteador como uma tabela de duas colunas cujo cabeçalho tenha "Estado / Condição / Se" à esquerda e "Ação / Fazer / Rota" à direita: ele se torna uma cadeia de decisões de primeira correspondência.
4. Escreva loops como "volte para a etapa N até …".
5. Marque etapas opcionais com um [Se necessário] / [opcional] inicial; a carta ganha uma borda tracejada.
6. Regras sob ## Regras / ## Notas se tornam notas âmbar; material sob ## Referência se torna uma lane de referência não conectada.

O bloco skillflow (controle exato)

Quando um SKILL.md contém um bloco ```skillflow, o SkillLens desenha apenas ele. A maneira mais rápida de escrever um: corrija o gráfico extraído automaticamente no painel Estrutura, clique em "Copiar como bloco de código" e cole-o no SKILL.md. Sintaxe:

Linha	Significado
title: subtitle: hero: título | subtítulo footer: window: cols: 4	texto da página e cartas por linha
trigger id: Título [tag] {ícone}	a carta do gatilho no topo; linhas indentadas abaixo são sua descrição
lane id: Título [tag] (cor tipo)	uma lane; cores green / blue / purple / teal / rose / amber / slate; tipos flow (padrão, encadeado) / ref (referência, não conectado) / bare (sem moldura)
step id: Título [tag] {ícone} +optional +end	uma carta de etapa; +end é a etapa final (ícone sólido), +optional uma carta tracejada
decide id: Pergunta? [subtítulo]	um diamante de decisão
note: texto	uma nota dentro da lane
a -> b -> c : rótulo sob flow:	linhas para frente; ~> é um loop tracejado; a -> "texto" : Sim é uma saída apontando para um texto curto

Sem flow:, as cartas das lanes não-ref são encadeadas em ordem. Os ícones são nomes do Lucide, listados em src/icons.js; para adicionar um, copie seu corpo SVG de lucide-static.

Alterando o SkillLens

• Camadas: markdown.js analisa → extract.js / dsl.js constroem a estrutura → layout.js posiciona cartas e roteia linhas → render.js desenha o SVG e o reproduz → app.js é a interface. Todas as strings da interface e do gráfico estão em i18n.js; adicione cada chave tanto em en quanto em zh.
• A página deve abrir com duplo clique, então usa tags <script> simples, sem módulos ES. Cada script é escrito como SV.mod.nome = function (SV) {…} para que a exportação autônoma possa incluir o código com toString().
• Cada quadro deve ser uma função pura do tempo t (sem animação CSS, Math.random ou relógio de parede), ou a gravação quadro a quadro de vídeo quebra.
• Temas: Blueprint (padrão), Midnight e Glass. As cores do gráfico estão em THEMES em render.js, as cores da interface nas variáveis CSS no topo de style.css; altere ambos juntos. Detalhes exclusivos do Blueprint (grade, réguas, marcas de canto, números das cartas, etapa ativa âmbar) estão atrás de P.blueprint.
• Fontes: Noto Sans SC (chinês), Inter (latim), JetBrains Mono (tags e caminhos) do Google Fonts, com fallback para fontes do sistema offline. O layout mede o texto com um canvas, então deve esperar as fontes: app.js limpa o cache de medidas e redesenha em loadingdone, e o modo de gravação mais a exportação autônoma chamam document.fonts.load para o texto do gráfico primeiro. Mantenha o link da fonte em index.html, FONT / MONO em layout.js e o link no modelo autônomo em sincronia.
• Tradução automática: scripts/lib/translate.mjs (servidor, /api/translate) e useTranslation em src/app.js (quais strings no gráfico são traduzidas). Apenas o texto do gráfico e o texto fonte aberto são traduzidos; tags, nomes de arquivo, caminhos e Sim / Não são mantidos. Ordem do backend: Anthropic SDK quando uma chave de API está configurada e @anthropic-ai/sdk está instalado, senão o Claude Code CLI local (no Windows chame node_modules/@anthropic-ai/claude-code/bin/claude.exe diretamente para evitar problemas de citação com .cmd). A chave do cache é lang + \u0001 + text em ambos os lados.
• Verifique alterações em um navegador headless: npm run scan, depois node scripts/record.mjs <skill> --seconds 3, ou captura de tela via scripts/lib/cdp.mjs. Para uma bateria de regressão, execute cada skill através de SV.extract → SV.layout → SV.render.toSVG e certifique-se de que nada lance exceção e nenhum texto transborde sua carta.
• A gravação precisa de um Chrome / Edge local e ffmpeg; defina SV_CHROME / SV_FFMPEG se eles não forem encontrados.
• Mídia do hero do README: docs/promo.webp (a animação exibida inline) linka para docs/promo.mp4 (o vídeo completo com som) em modo raw. O GitHub nunca reproduz um MP4 de repositório: nem inline no README e nem na visualização do arquivo, independentemente do tamanho, então o link raw baixa o arquivo; um player inline precisa do vídeo enviado através do editor do github.com (uma URL user-attachments). Use WebP animado, não GIF: com os gradientes escuros do Blueprint, um GIF de 30 s tem mais de 20 MB, enquanto o WebP fica abaixo de 8 MB com cor mais limpa. A partir de um 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 e 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.