Visual — Visualizador de Grafo de Skills

O que Visual — Visualizador de Grafo de Skills faz?

Mapeia cada skill do projeto em um grafo direcionado: o que cada skill consome, o que produz e como as skills se encadeiam em fluxos de trabalho. Gera duas saídas — um arquivo Mermaid markdown para documentação e um grafo interativo no navegador para exploração.

Anunciar no início: "Mapeando grafo de skills..."

Quando Usar

Execute /visual quando você quiser:

• Entender como todas as skills se encaixam em uma visão geral
• Integrar novos contribuidores ao ecossistema de skills
• Auditar o grafo após adicionar ou modificar uma skill

Fluxo de Trabalho

Passo 1: Escanear todas as skills

find skills/ -name "SKILL.md" 2>/dev/null | sort

Leia cada arquivo SKILL.md por completo.

---

Passo 2: Extrair metadados de cada skill

Para cada arquivo de skill, extraia:

Campo	Fonte
id	Nome do diretório (ex.: skills/walkthrough/ → walkthrough)
label	Frontmatter name, prefixado com seu emoji do README se conhecido
description	Frontmatter description — apenas a primeira frase
triggers	Conteúdo: padrões /command encontrados no texto
inputs	Conteúdo: arquivos/origens que a skill lê (ex.: git diff, docs/plans/)
outputs	Conteúdo: arquivos que a skill escreve (ex.: .review/review.md)
relationships	Array do frontmatter relationships — veja esquema abaixo

Esquema do frontmatter relationships (explícito, preferido):

relationships:
  - target: <skill-id>         # nome do diretório de outra skill
    type: <relationship-type>  # um dos tipos abaixo
    label: <frase curta>       # exibida na aresta do grafo (≤ 5 palavras)

Tipos de relacionamento:

Tipo	Significado	Estilo da seta
leads-to	Próximo passo recomendado após esta skill	sólida -->
alternative	Abordagem diferente para a mesma tarefa	tracejada -.->
complements	Propósito diferente, funciona bem junto	sólida -->
feeds-from	Esta skill consome a saída do alvo	sólida -->
analyzes	Esta skill lê e processa os arquivos do alvo	sólida -->

---

Passo 3: Inferir relacionamentos (apenas fallback)

Para qualquer skill sem frontmatter relationships, infira a partir do conteúdo:

1. Referências a triggers nomeadas: O conteúdo menciona o /command ou nome do diretório de outra skill → aresta leads-to em direção à skill referenciada.
2. E/S compartilhada: Duas skills leem/escrevem o mesmo caminho de arquivo → aresta complements entre elas.
3. Linguagem de fluxo: O conteúdo contém "após executar X", "antes de usar Y", "funciona bem com Z" → crie aresta direcionada combinando com a frase.
4. Padrão de sumidouro de conhecimento: Uma skill que apenas escreve em um repositório de conhecimento sem receber saída de outra skill → outras skills que mencionam preservar aprendizados levam a ela (leads-to).

Marque todas as arestas inferidas: "inferred": true no modelo do grafo. Elas renderizam como linhas tracejadas em ambas as saídas.

---

Passo 4: Construir modelo interno do grafo

Produza esta estrutura JSON internamente (não gravada em disco):

{
  "skills": [
    {
      "id": "walkthrough",
      "label": "🚶 walkthrough",
      "description": "Uma frase.",
      "triggers": ["/walkthrough"],
      "inputs": ["git diff"],
      "outputs": []
    }
  ],
  "edges": [
    {
      "source": "walkthrough",
      "target": "compound",
      "type": "leads-to",
      "label": "salvar aprendizados da sessão",
      "inferred": false
    }
  ]
}

---

Passo 5: Escrever docs/SKILL_GRAPH.md

Crie docs/ se não existir. Escreva docs/SKILL_GRAPH.md com quatro seções:

Seção 1 — Grafo geral

## Visão Geral das Skills

\`\`\`mermaid
flowchart LR
    classDef skill fill:#1a1a2e,stroke:#4a90d9,color:#e0e0ff
    classDef terminal fill:#0d2618,stroke:#4a9d6f,color:#a0ffa0

    skill-a["emoji nome\n/trigger"]:::skill
    skill-b["emoji nome\n/trigger"]:::skill
    ...

    skill-a -->|"rótulo"| skill-b
    skill-c -.->|"rótulo"| skill-d
\`\`\`

Regras:

• Arestas leads-to e complements: sólidas -->
• Arestas alternative e inferidas: tracejadas -.->
• Formato do rótulo do nó: "emoji nome\n/trigger" (use \n para quebra de linha)
• Skills sem arestas de saída leads-to recebem classe :::terminal
• IDs de nós Mermaid devem ser identificadores válidos — substitua hífens por underscores nos IDs, mantenha o rótulo como está

Seção 2 — Cadeias de fluxo de trabalho

Encontre todas as skills de entrada (skills sem arestas leads-to de entrada). Para cada uma, trace o caminho completo de leads-to e escreva um fluxo de trabalho nomeado:

## Fluxos de Trabalho

### Fluxo de Revisão de Código
\`\`\`mermaid
flowchart LR
    walkthrough -->|"salvar aprendizados"| compound
\`\`\`

### Fluxo de Implementação
...
\`\`\`

Se dois caminhos compartilham o mesmo nó terminal, eles podem ser mostrados em um único diagrama.

Seção 3 — Fluxo de dados

Mostre origens de entrada, skills e artefatos de saída. Inclua apenas skills que tenham entradas ou saídas explícitas em seus metadados:

## Fluxo de Dados

\`\`\`mermaid
flowchart LR
    classDef artifact fill:#1a1a1a,stroke:#888,color:#ccc
    classDef ext fill:#2a1a0a,stroke:#d9904a,color:#ffd0a0

    git_diff[/"git diff"/]:::ext
    review_md[/".review/review.md"/]:::artifact

    git_diff --> review_diff
    review_diff --> review_md
\`\`\`

Seção 4 — Índice de skills

Uma tabela: Skill | Trigger | Descrição | Lê | Escreve

---

Passo 6: Gerar saídas HTML interativas

Serializar o modelo do grafo do Passo 4 em uma string JSON minificada de uma única linha. Use esta string JSON para ambas as saídas abaixo (mesmos dados, templates diferentes).

6a — Painel de skills (saída principal)

Abra skills/visual/references/dashboard-template.html. Substitua /* GRAPH_DATA_JSON */ pela string JSON. Grave em .docs/skill-dashboard.html.

O painel tem três abas:

• Skills — grade de cartões com o trigger, descrição, leituras/escritas e relacionamentos de saída de cada skill
• Grafo — grafo Cytoscape interativo (inicializado sob demanda na primeira abertura da aba)
• Fluxos de Trabalho — cadeias de fluxo de trabalho derivadas automaticamente, alternativas e complementos

6b — Grafo autônomo (saída secundária)

Abra skills/visual/references/graph-template.html. Substitua /* GRAPH_DATA_JSON */ pela mesma string JSON. Grave em .docs/skill-graph.html.

Se algum arquivo de template não for encontrado, pule essa saída e observe no relatório.

---

Passo 7: Verificação de descoberta

Pesquise SKILL_GRAPH no CLAUDE.md. Se não for encontrado, proponha:

O grafo de skills em docs/SKILL_GRAPH.md ainda não está referenciado no CLAUDE.md. Adicionar este bloco para que futuros agentes o descubram automaticamente?

## Skill Graph
Relacionamentos e fluxos de trabalho das skills: `docs/SKILL_GRAPH.md`
Painel (skills + grafo + fluxos de trabalho): `.docs/skill-dashboard.html`
Grafo autônomo: `.docs/skill-graph.html`

Adicionar ao CLAUDE.md? (sim/não)

Não escreva automaticamente. Aguarde aprovação antes de modificar o CLAUDE.md.

---

Passo 8: Imprimir relatório de conclusão

★ Grafo de skills mapeado
  Skills:        N
  Relacionamentos: M explícitos, K inferidos
  → docs/SKILL_GRAPH.md              [Visão geral Mermaid + fluxos de trabalho + fluxo de dados + índice]
  → .docs/skill-dashboard.html       [Painel: cartões de skills + grafo + fluxos de trabalho]
  → .docs/skill-graph.html           [Grafo interativo autônomo]
  CLAUDE.md: encontrado ✓ / ainda não referenciado

---

Restrições Principais

• Nunca escreva automaticamente no CLAUDE.md — sempre pergunte primeiro
• Explícito sobre inferido — o frontmatter relationships sempre vence; arestas inferidas são tracejadas em ambas as saídas
• Idempotente — executar /visual novamente sobrescreve completamente ambos os arquivos de saída
• Não destrutivo — nunca modifica nenhum arquivo SKILL.md; apenas escreve em docs/ e .docs/
• IDs de nós Mermaid: substitua - por _ para evitar erros de análise (ex.: review_diff não review-diff)
• Comprimento do rótulo do nó: mantenha linhas separadas por \n com no máximo 20 caracteres cada para legibilidade