jpmanson/pele-skill

Pele

Renderiza código fuente de Mermaid a SVG con Pele. Pele es una librería síncrona: sin Puppeteer, sin mermaid-cli, sin servidor MCP. La interfaz de este skill es scripts/render.mjs.

La raíz del skill es el directorio que contiene este archivo. Todas las rutas a continuación son relativas a ese directorio. Esto se mantiene incluso después de instalar el skill en Claude Code, Hermes u OpenCode.

Cuándo Usar

• El usuario quiere un diagrama Mermaid como archivo SVG, HTML o imagen.
• Un archivo .mmd, o un bloque ```mermaid, necesita ser renderizado y verificado.
• El usuario pide un diagrama que uno de los 32 tipos soportados puede dibujar, y quiere un archivo, no un bloque de chat. Esto incluye tipos menos conocidos: mapa Wardley, fishbone, Venn, carril, radar, treemap, sankey, gramática de ferrocarril, árbol de archivos, Cynefin, modelo de eventos. Ver Tipos de diagrama más abajo.

No usar cuando:

• El bloque Mermaid debe permanecer en Markdown que GitHub, Obsidian u otro visador ya renderiza.
• El artefacto solicitado no es Mermaid (un JSON de Excalidraw dibujado a mano, una página de arquitectura personalizada, una anotación de captura de pantalla).
• El usuario necesita una salida idéntica en píxeles a mermaid.js. Pele tiene su propio diseño.

No envuelvas esto en un servidor MCP. Una sola llamada al script es toda la capacidad.

Prerrequisitos

• Node.js 20 o más reciente, y npm en PATH.
• La instalación de dependencias ocurre en la raíz del skill (package.json junto a este archivo), nunca en el proyecto del usuario.

Si falta node_modules/pele, el script ejecuta npm install allí. También puedes hacerlo tú mismo:

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

Verificación: node scripts/render.mjs --check sale con código 0 y el JSON en stderr tiene "ok": true y una versión de pele.

Tipos de diagrama

Conoce la lista completa antes de elegir. Pele renderiza 32 tipos, y un tercio de ellos necesita un encabezado -beta que difiere del nombre que diría un usuario.

node scripts/render.mjs --types

Esto imprime JSON: type, el header exacto de la primera línea, para qué sirve, y una ruta example funcional. references/diagram-types.md tiene la misma tabla, los encabezados que fallan y cómo elegir un tipo.

• Elige el tipo que muestre lo que el lector necesita, no el primero que se te ocurra. Dueños por paso → swimlane. Causas de un problema → ishikawa. Tareas con fecha → gantt. Diseño de carpetas → treeView. Flujos proporcionales → sankey.
• Si la solicitud no encaja en ningún tipo (diseño libre, una imagen, un tipo de gráfico no listado), dilo y no lo fuerces a un flowchart.
• Si el usuario nombra un tipo de diagrama específico que no está en la lista, dilo antes de ofrecer el tipo soportado más cercano. No lo aproximes en silencio.

Procedimiento

1. Elige el tipo y su encabezado exacto de --types. Para cualquier tipo -beta, o cualquier tipo cuya sintaxis no conozcas bien, lee primero su archivo example y copia su estructura.
2. Escribe el código fuente Mermaid en un archivo .mmd. No pases un diagrama multilínea como argumento de shell.
3. Renderízalo:

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

4. Lee el recibo JSON en stderr. La finalización exitosa requiere todo lo siguiente: código de salida 0, "ok": true, el type del recibo es el tipo que elegiste, y el archivo de salida comienza con <svg.
5. Si "ok": false:
   • unsupported-diagram: la primera línea no es un encabezado conocido. Usa suggest[0].header si está presente, de lo contrario elige uno de --types.
   • syntax o semantic: corrige el código fuente en line / column usando snippet, compara con el ejemplo del tipo y renderiza de nuevo.
   • No cambies a mermaid-cli, un navegador sin cabeza o un SVG escrito a mano.
6. Reporta la ruta absoluta de salida. No pegues el SVG en el chat a menos que el usuario haya pedido el marcado. No declares éxito con un código de salida distinto de cero.

Usa --html, o una ruta de salida que termine en .html, cuando el usuario necesite un archivo que pueda abrir en un navegador. El HTML incrusta el SVG y establece las variables de color CSS de Pele.

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

Recibo

Éxito en stderr:

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

Fallo en stderr, código de salida 1 (código 2 si Pele no pudo instalarse):

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

code puede ser syntax, semantic, unsupported-diagram, limit, usage, install-failed o render-failed. Muestra message como texto. Puede contener el código fuente del diagrama.

Un recibo unsupported-diagram también tiene hint y suggest:

{"ok":false,"code":"unsupported-diagram","hint":"Reemplaza la primera línea con el encabezado de abajo. Muchos tipos necesitan el sufijo -beta.","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}

Banderas

Bandera	Uso
--check	Carga Pele, imprime versión, no renderiza
--types	Imprime tipos soportados, encabezados y rutas de ejemplo como JSON en stdout
--html	HTML independiente en lugar de SVG puro
--fixed	Tamaño de píxel fijo. Por defecto para un archivo .svg
--responsive	El SVG puede reducirse para ajustarse a su contenedor. Por defecto para stdout y HTML
--max-width <px>	Pide a Pele que adapte el diseño. Puede cambiar un flowchart LR ancho a vertical por debajo de 640px
--font-size <px>	Tamaño de fuente base
--font <family>	Fuente de las etiquetas
--id-prefix <str>	Prefijo único cuando más de un SVG compartirá una página

Stdout contiene el SVG (o HTML). El recibo es siempre la última línea JSON en stderr.

Un bloque ```mermaid circundante se elimina. El frontmatter propio de Mermaid no.

Errores comunes

• El SVG de archivo tiene por defecto responsive: false. Pasa --responsive solo cuando el SVG se incruste y deba encogerse.
• Node no tiene un medidor de canvas. Los anchos de las etiquetas pueden diferir de un renderizado en navegador. Esto es esperado.
• No pases --max-width a menos que el usuario haya solicitado un diseño estrecho. Puede cambiar la dirección.
• Los encabezados son exactos. radar, venn, wardley, swimlane, treeView, usecase, cynefin, railroad, agentflow todos necesitan -beta; architecture también necesita -beta. No hay encabezado fishbone; usa ishikawa-beta.
• Los nombres de iconos (fa:fa-user, iconos de arquitectura distintos de cloud, database, disk, internet, server) se renderizan como un espacio vacío sin error. Este script no proporciona una retrollamada de iconos. Elimina el icono o reemplázalo con texto.
• El límite de código fuente es de 50.000 caracteres. El límite de salida es de 4.000.000. El límite de aristas de flowchart es de 5.000.
• npm install en el repositorio del usuario no satisfará este script. El paquete reside en la raíz del skill.
• Si node_modules existe pero Pele falla al cargar, borra ese node_modules y ejecuta npm install en la raíz del skill.
• Una sesión de agente ya abierta no verá un skill instalado a mitad de sesión. Esto es un problema de caché del cargador, no una mala instalación.

Verificación

Desde la raíz del skill:

npm run smoke

Finalización: código de salida 0, y stdout JSON tiene "ok": true, una versión de pele, "types": 32, una lista rendered con cada tipo del catálogo, y un syntaxError con code: "syntax" y un line distinto de cero. La prueba de humo también falla si scripts/catalog.mjs se desvía de la propia lista de tipos de Pele, o si un encabezado deja de detectarse como su tipo. examples/broken.mmd debe seguir fallando. Una prueba de humo exitosa no significa que un nuevo diagrama sea correcto; cada nuevo diagrama sigue necesitando su propio recibo.