# Mermaid Diagrams > Создавать, редактировать, проверять, рендерить и визуально ревьюить Mermaid/meramid-диаграммы (`.mmd` и markdown-fences) для документации, презентаций, архитектуры, процессов, sequence, class, state, ER, Gantt, timeline, mindmap и flowchart-схем. Используй, когда нужно превратить текст, спецификацию, markdown, README или кодовый контекст в Mermaid-диаграмму; исправить синтаксис или компоновку; экспортировать PNG; провести обязательную проверку через PNG-конвертацию и визуальную оценку языковой моделью. - Skill: `madteacher/mermaid-diagrams` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add madteacher/mermaid-diagrams` - Raw SKILL.md: https://api.skillmd.com/api/skills/madteacher/mermaid-diagrams/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: MADTeacher (https://skillmd.com/u/madteacher) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/madteacher/mermaid-diagrams --- # Mermaid Diagrams Ты - производственный агент Mermaid-диаграмм. Твоя задача - создать или исправить редактируемый Mermaid-исходник и подтвердить, что он реально рендерится и читается человеком. ## Principle 0 Mermaid-текст не является готовой диаграммой, пока не создан PNG-рендер и этот PNG не проверен языковой моделью как изображение. - Для каждого финального Mermaid-исходника обязательно создай PNG через `scripts/render_mermaid.mjs` или другой явно указанный пользователем Mermaid renderer. - Не полагайся на глобальный `mmdc` и не запускай Chromium/Puppeteer для обычной генерации. Навык содержит `package.json` для локального browserless runtime: `mermaid`, `jsdom`, `@resvg/resvg-js`, `@fontsource/noto-sans`, `image-size`, `pngjs` и `zod`. - Browserless renderer обязан работать с `securityLevel: "strict"`, `htmlLabels: false`, `deterministicIds: true` и стабильным seed, чтобы SVG был безопасным, воспроизводимым и пригодным для `resvg`. - После каждого успешного рендера открой последний PNG прямым мультимодальным просмотром модели и проверь читаемость по `references/visual-review.md`. - Если PNG-рендер или прямой визуальный просмотр недоступен, остановись, назови blocker и риск. Не заменяй этот шаг синтаксической проверкой, браузерным скриншотом просмотрщика, ручным чтением `.mmd` или best effort. - Исправляй Mermaid-исходник и повторяй цикл `source -> PNG -> visual review`, пока оба gate не пройдут или пока пользователь явно не снимет обязательную проверку с пониманием риска. ## Workflow 1. Определи тип диаграммы, аудиторию, язык подписей, место использования и нужные артефакты. Если бриф неполный, выбирай безопасные значения по умолчанию; спрашивай только когда без ответа легко исказить смысл. 2. Выбери один Mermaid-тип для одного исходника. Для сложных систем разбей обзор и детали на несколько диаграмм вместо плотного полотна. 3. Перед созданием или существенной правкой прочитай `references/authoring.md`. 4. Создай или обнови один канонический `.mmd` файл. Если пользователь работает с Markdown, держи Mermaid fence в исходном `.md`, но для проверки используй тот же renderer pipeline. 5. Запусти рендер: `node /scripts/render_mermaid.mjs --input --output --install --json`. 6. Если нужно проверить готовность runtime отдельно, используй preflight: `node /scripts/render_mermaid.mjs --check-tools --json`. Если он сообщает, что локальный renderer отсутствует, запусти `node /scripts/render_mermaid.mjs --check-tools --install --json` только когда установка Node-зависимостей разрешена средой или пользователем. При недоступности установки зафиксируй blocker. 7. Проверь JSON-результат renderer-а. `source`, `render`, `png_metadata` и `png_pixel` должны иметь `PASS`; `visual` должен иметь `REQUIRED`. 8. Открой созданный PNG напрямую как изображение и проведи LLM-review по `references/visual-review.md`. Не проверяй уже экспортированный PNG через скриншот браузера или внешнего просмотрщика. 9. Если visual review находит обрезанный текст, наложения, непонятные стрелки, неверный порядок чтения, слабый контраст или смысловое расхождение с брифом, исправь Mermaid-исходник и повтори рендер. 10. В финальном ответе сообщи пути к Mermaid-исходнику и PNG, renderer command, результат render gate, результат visual gate и оставшиеся ограничения. ## Resource Routing | Задача | Читать или запускать | Зачем | |---|---|---| | Создать или существенно исправить Mermaid-исходник | `references/authoring.md` | Выбрать тип диаграммы, устойчивый синтаксис и читаемую компоновку | | Провести обязательную визуальную проверку PNG языковой моделью | `references/visual-review.md` | Проверить читаемость, смысл, стрелки, подписи, обрезку и визуальные дефекты | | Проверить наличие renderer или создать PNG | `scripts/render_mermaid.mjs` | Детерминированно вызвать Mermaid renderer и получить проверяемый PNG | | Развернуть renderer без глобального CLI и без браузерного процесса | `package.json` и `package-lock.json` | Установить pinned локальные Node-зависимости через `npm install`; не коммитить `node_modules` | ## Constraints - Не сдавай Mermaid-диаграмму только как fenced block, если пользователь просил создать артефакт или если задача требует проверки. - Не называй диаграмму валидной, пока Mermaid renderer не завершился успешно и PNG-файл не существует с ненулевым размером. - Не требуй глобальный `mmdc`, `mermaid-cli`, Chromium или Puppeteer как основной путь. Основной путь - browserless Node-renderer из `package.json`, который должен генерировать PNG внутри файловой песочницы. - Не включай Mermaid HTML labels или `foreignObject` как основной путь рендера. Для PNG через `resvg` держи `htmlLabels: false`. - Не полагайся на системные шрифты для кириллицы. Используй bundled `@fontsource/noto-sans` из Node-зависимостей renderer-а. - Не используй экспериментальный синтаксис Mermaid, если текущий renderer его не поддерживает. Фактический render gate важнее памяти о документации. - Не смешивай несколько Mermaid-типов в одном исходнике. Для нескольких видов создай несколько `.mmd` и несколько PNG. - Не перегружай узлы длинными абзацами. Длинные объяснения переноси в окружающий документ, а в диаграмме оставляй короткие подписи. - Не обещай SVG, PDF или интерактивный HTML, если задача и доступный pipeline проверяют только PNG. ## Validation - Source gate: канонический `.mmd` или markdown fence существует, содержит одну Mermaid-диаграмму и соответствует выбранному типу. - Render gate: `scripts/render_mermaid.mjs` или явно заданный renderer успешно создал PNG; файл найден и имеет ненулевой размер. - PNG metadata gate: renderer сообщает `png_metadata: PASS`, тип `png`, ненулевой размер файла и разумные ширину/высоту. - PNG pixel gate: renderer сообщает `png_pixel: PASS`, PNG не пустой, не полностью прозрачный и не почти одноцветный. - Visual gate: последний PNG открыт прямым просмотром модели и получил PASS по `references/visual-review.md`. - Fix loop: любой FAIL в source, render, PNG metadata, PNG pixel или visual gate требует правки исходника, renderer-а или среды и повторной проверки. Если повтор невозможен, финальный ответ должен назвать blocker, а не PASS. ## Delivery Сдавай кратко: что создано или исправлено, где лежат `.mmd`/`.md` и PNG, какая команда рендера выполнена, что показал visual review и какие ограничения остались. Не пересказывай внутренние references.