fengyunzaidushi/markmap-skill

Mapa Mental Markmap com Foco em Conteúdo

Organize projetos, documentação, bases de código ou conceitos em Markdown pronto para renderização com Markmap, validando a estrutura e gerando HTML quando necessário.

Regras Principais

• Primeiro o todo, depois as partes: o tópico raiz descreve o objeto e seu propósito, em seguida expanda os conceitos principais reais, fluxos, módulos e detalhes.
• Use o material em si para organizar o mapa. Não invente títulos genéricos para facilitar a leitura de iniciantes.
• Remova títulos que servem apenas como categorias, como "Posicionamento do Projeto", "Mecanismo de Operação", "Panorama de Desenvolvimento", "Conceitos Principais", "Módulos Principais", "Cenários de Uso", a menos que esses termos façam parte do texto original.
• Cada nó pai pode ter no máximo 7 filhos diretos; prefira cerca de 5, expandindo para 6-7 apenas quando o conteúdo realmente exigir.
• Não espalhe mais de 7 ramificações só porque o conteúdo real é extenso; agrupe por subtópicos reais do material.
• Se um nível parecer precisar de mais de 7 ramificações, primeiro mescle tópicos semelhantes e reorganize na ordem "todo -> grupo -> detalhes locais".
• Analogias são opcionais. Use-as apenas quando realmente ajudarem na memorização, colocando-as após o rótulo de conteúdo; nunca deixe a analogia se tornar o nó principal.
• Não invente certezas. Antes de resumir um repositório, leia o README, documentação, configurações de pacotes, testes, diretório de código fonte e scripts locais.
• Mantenha o mapa conciso. Use rótulos curtos para os nós e, quando necessário, adicione uma breve explicação baseada em evidências.

Ao lidar com repositórios complexos ou documentos longos, leia primeiro references/analogy-structure.md.

Fluxo de Trabalho

1. Primeiro, examine o material.
   • Repositório: leia README, AGENTS.md/CLAUDE.md, configurações de pacotes, documentação e diretório raiz.
   • Documento: identifique tópico, argumentos, seções, conceitos recorrentes e termos que precisam ser memorizados.
2. Esboce o Markdown do todo para as partes.
   • Use um título raiz H1 para descrever o objeto.
   • Use ## para expandir os eixos principais do conteúdo real, sem usar "categorias para o leitor".
   • Cada nó deve priorizar conceitos reais do material: sistemas, fluxos, caminhos de arquivo, APIs, argumentos ou responsabilidades.
   • Expanda apenas quando os detalhes ajudarem na compreensão, não force ramificações.
   • Cada nó pai pode ter no máximo 7 filhos diretos, prefira cerca de 5; acima de 7, reagrupe por subtópicos reais.
3. Valide o Markdown com o script:

python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md --validate-only

4. Quando precisar entregar HTML, renderize o Markmap:

python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md -o output.html

5. Se a validação falhar, corrija a estrutura do mapa primeiro. A menos que o usuário solicite explicitamente um mapa não padrão, não ignore as verificações de "categorias genéricas" e "muitas ramificações por nível".

Renderização Markmap

O script tentará, em ordem:

1. markmap
2. npx --yes markmap-cli
3. CLI compilada local em /root/markmap

Se não houver renderizador disponível, o Markdown validado será entregue como resultado, com uma observação de que o HTML não foi gerado.

Requisitos de Saída

• Após criar os arquivos, retorne os caminhos do .md e do .html.
• Explique quais fontes foram verificadas e o resultado dos comandos de validação/renderização.
• A menos que o usuário solicite modificações no repositório de origem, apenas leia o material original.
• Para usuários de chinês, o mapa mental padrão é em chinês; use inglês apenas para comandos, caminhos, APIs, nomes de pacotes e termos técnicos que devem permanecer em inglês.