jpmanson/pele-skill

Pele

Renderiza código-fonte Mermaid para SVG com Pele. Pele é uma biblioteca síncrona: sem Puppeteer, sem mermaid-cli, sem servidor MCP. A interface desta skill é scripts/render.mjs.

A raiz da skill é o diretório que contém este arquivo. Todos os caminhos abaixo são relativos a esse diretório. Isso permanece verdadeiro após a skill ser instalada no Claude Code, Hermes ou OpenCode.

Quando Usar

• O usuário deseja um diagrama Mermaid como arquivo SVG, HTML ou imagem.
• Um arquivo .mmd, ou uma cerca ```mermaid, precisa ser renderizada e verificada.
• O usuário solicita um diagrama que um dos 32 tipos suportados pode desenhar, e deseja um arquivo, não uma cerca de chat. Isso inclui tipos menos comuns: mapa Wardley, fishbone, Venn, swimlane, radar, treemap, Sankey, gramática railroad, árvore de arquivos, Cynefin, modelo de eventos. Veja Tipos de diagrama abaixo.

Não use quando:

• A cerca Mermaid deve permanecer no Markdown que GitHub, Obsidian ou outro visualizador já renderiza.
• O artefato solicitado não é Mermaid (JSON Excalidraw desenhado à mão, uma página de arquitetura personalizada, uma anotação de captura de tela).
• O usuário precisa de saída mermaid.js pixel-idêntica. Pele tem seu próprio layout.

Não envolva isso em um servidor MCP. Uma única chamada de script é toda a capacidade.

Pré-requisitos

• Node.js 20 ou mais recente, e npm no PATH.
• A instalação de dependências ocorre na raiz da skill (package.json próximo a este arquivo), nunca no projeto do usuário.

Se node_modules/pele estiver faltando, o script executa npm install lá. Você também pode fazer isso manualmente:

npm install --no-fund --no-audit

Conclusão: node scripts/render.mjs --check sai com código 0 e o stderr JSON tem "ok": true e uma versão do pele.

Tipos de diagrama

Conheça a lista completa antes de escolher. Pele renderiza 32 tipos, e um terço deles precisa de um cabeçalho -beta que difere do nome que o usuário diria.

node scripts/render.mjs --types

Isso imprime JSON: type, header exato da primeira linha, para que serve e um caminho example funcional. references/diagram-types.md tem a mesma tabela, os cabeçalhos que falham e como escolher um tipo.

• Escolha o tipo que mostra o que o leitor precisa, não o primeiro que vem à mente. Donos por etapa → swimlane. Causas de um problema → ishikawa. Tarefas com datas → gantt. Layout de pastas → treeView. Fluxos proporcionais → sankey.
• Se a solicitação não se encaixa em nenhum tipo (layout livre, uma imagem, um tipo de gráfico não listado), diga isso e não force em um fluxograma.
• Se o usuário nomear um tipo de diagrama específico que não está na lista, diga isso antes de oferecer o tipo suportado mais próximo. Não aproxime silenciosamente.

Procedimento

1. Escolha o tipo e seu cabeçalho exato de --types. Para qualquer tipo -beta, ou qualquer tipo cuja sintaxe você não tem certeza, leia primeiro seu arquivo example e copie sua estrutura.
2. Escreva o código-fonte Mermaid em um arquivo .mmd. Não passe um diagrama de várias linhas como argumento do shell.
3. Renderize-o:

node scripts/render.mjs INPUT.mmd OUTPUT.svg

4. Leia o recibo JSON no stderr. A conclusão é tudo isso: código de saída 0, "ok": true, o type do recibo é o tipo que você escolheu, e o arquivo de saída começa com <svg.
5. Se "ok": false:
   • unsupported-diagram: a primeira linha não é um cabeçalho conhecido. Use suggest[0].header se presente; caso contrário, escolha um de --types.
   • syntax ou semantic: corrija a fonte em line / column usando snippet, compare com o exemplo do tipo e renderize novamente.
   • Não mude para mermaid-cli, um navegador headless ou um SVG escrito à mão.
6. Informe o caminho absoluto de saída. Não cole o SVG no chat a menos que o usuário tenha solicitado a marcação. Não afirme sucesso em uma saída não zero.

Use --html, ou um caminho de saída terminando em .html, quando o usuário precisar de um arquivo que possa abrir em um navegador. O HTML incorpora o SVG e define as variáveis de cor CSS do Pele.

node scripts/render.mjs --html INPUT.mmd OUTPUT.html

Recibo

Sucesso no stderr:

{"ok":true,"type":"flowchart","width":180,"height":80,"bytes":1200,"output":"/abs/OUTPUT.svg","html":false,"pele":"1.6.0"}

Falha no stderr, código de saída 1 (código de saída 2 se Pele não pôde ser instalado):

{"ok":false,"code":"syntax","message":"...","type":"flowchart","line":2,"column":5,"snippet":"..."}

code pode ser syntax, semantic, unsupported-diagram, limit, usage, install-failed ou render-failed. Exiba message como texto. Pode conter o código-fonte do diagrama.

Um recibo unsupported-diagram também tem hint e suggest:

{"ok":false,"code":"unsupported-diagram","hint":"Substitua a primeira linha pelo cabeçalho abaixo. Muitos tipos precisam do sufixo -beta.","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}

Flags

Flag	Uso
--check	Carrega Pele, imprime versão, não renderiza
--types	Imprime tipos suportados, cabeçalhos e caminhos de exemplo como JSON no stdout
--html	HTML independente em vez de SVG bruto
--fixed	Tamanho de pixel fixo. Padrão para um arquivo .svg
--responsive	O SVG pode encolher para seu contêiner. Padrão para stdout e HTML
--max-width <px>	Pede ao Pele para adaptar o layout. Pode inverter um fluxograma LR largo para vertical abaixo de 640px
--font-size <px>	Tamanho base da fonte
--font <family>	Fonte dos rótulos
--id-prefix <str>	Prefixo único quando mais de um SVG compartilhará uma página

O stdout permanece o SVG (ou HTML). O recibo é sempre a última linha JSON no stderr.

Uma cerca ```mermaid circundante é removida. O frontmatter próprio do Mermaid não.

Armadilhas

• O SVG de arquivo padrão é responsive: false. Use --responsive apenas quando o SVG for incorporado e precisar encolher.
• Node não tem um medidor de canvas. As larguras dos rótulos podem diferir de uma renderização de navegador. Isso é esperado.
• Não use --max-width a menos que o usuário tenha solicitado um layout estreito. Pode mudar a direção.
• Os cabeçalhos são exatos. radar, venn, wardley, swimlane, treeView, usecase, cynefin, railroad, agentflow todos precisam de -beta; architecture também precisa de -beta. Não existe cabeçalho fishbone; use ishikawa-beta.
• Nomes de ícones (fa:fa-user, ícones de arquitetura diferentes de cloud, database, disk, internet, server) renderizam como um espaço vazio sem erro. Este script não fornece um callback de ícone. Remova o ícone ou substitua por texto.
• O limite da fonte é de 50.000 caracteres. O limite de saída é de 4.000.000. O limite de arestas do fluxograma é de 5.000.
• npm install no repositório do usuário não satisfará este script. O pacote reside na raiz da skill.
• Se node_modules existir, mas Pele falhar ao carregar, exclua esse node_modules e execute npm install na raiz da skill.
• Uma sessão de agente já aberta não verá uma skill instalada durante a sessão. Isso é um cache do loader, não uma instalação ruim.

Verificação

A partir da raiz da skill:

npm run smoke

Conclusão: código de saída 0, e o stdout JSON tem "ok": true, uma versão do pele, "types": 32, uma lista rendered com todos os tipos do catálogo, e um syntaxError com code: "syntax" e um line não zero. O smoke também falha se scripts/catalog.mjs se desviar da própria lista de tipos do Pele, ou se um cabeçalho parar de ser detectado como seu tipo. examples/broken.mmd deve continuar falhando. Um smoke passar não significa que um novo diagrama está correto; cada novo diagrama ainda precisa de seu próprio recibo.