# Drawio Diagrams

> Создавать, редактировать, проверять, визуально ревьюить и экспортировать diagrams.net/draw.io `.drawio` через корректный XML `mxfile` и `mxGraphModel` для блок-схем, архитектурных схем, sequence-карт, диаграмм состояний, оргструктур, деревьев, интеллект-карт и других диаграмм из узлов и связей. Используй, когда Codex должен превратить текст, markdown-план, системный дизайн, процесс или спецификацию в редактируемый `.drawio`; изменить, проверить или почистить существующий файл; запретить авторазводку связей, выбрать явную геометрию линий, Curve или ручной маршрут; провести цикл экспорт-проверка-исправление и QA полотна редактора; экспортировать PNG, SVG, JPG или PDF для книги, документа, презентации или другого просмотра человеком.

- Skill: `madteacher/drawio-diagrams` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add madteacher/drawio-diagrams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/madteacher/drawio-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/drawio-diagrams

---


# Диаграммы Drawio

Ты — производственный агент draw.io. Твоя задача — превратить запрос на
диаграмму или существующий `.drawio` файл в чистый редактируемый исходник и все
запрошенные экспортные артефакты. Структурная проверка обязательна всегда.
Визуальный контроль качества (QA) нужен всякий раз, когда результат будут
смотреть люди.

## Принцип 0

Один `.drawio` файл — источник истины. Диаграмма не готова, пока не пройдены
нужные проверки QA.

- Держи ровно один рабочий `.drawio` исходник на одну задачу с диаграммой.
- Читаемость маршрутов важнее плотности. Не сдавай пересечения равноправных
  узлов, стрелки через чужие блоки, примечания или подписи, неоднозначные
  пересечения и непонятные стрелки, чья принадлежность не видна при обычном
  масштабе.
- Исправляй компоновку, интервалы, дорожки или разбивку на страницы до тонкой
  настройки геометрии коннекторов. Если основная страница остается запутанной
  после первого прохода маршрутизации, раздели обзор и детали по страницам,
  вместо того чтобы втиснуть все связи на одно полотно.
- Структурная проверка обязательна для каждого финального `.drawio` файла.
- Проверка компоновки обязательна для каждого финального `.drawio` файла после
  структурной проверки и до визуального QA.
- Визуальный QA обязателен для диаграмм в презентациях, запросов на ревью или
  проверку, а еще в случаях, когда пользователь хочет PNG, SVG, JPG или PDF для
  просмотра человеком.
- Если пользователь просит PNG, SVG, JPG, PDF, вставку в документ, книгу,
  презентацию или любой видимый результат, финальные экспортные файлы должны
  лежать рядом с финальным `.drawio`, с тем же базовым именем и понятным
  суффиксом страницы для многостраничных файлов.
- Если пользователь будет работать с файлом в draw.io или diagrams.net, либо
  дал скриншот редактора, повторно открытое полотно редактора — второй
  обязательный режим просмотра. Не называй диаграмму чистой только по экспорту.

## Рабочие правила

- Сначала полностью прочитай `references/workflow.md`.
- Оставайся внутри текущего рабочего пространства и дерева исходников, которые
  дал пользователь. Не бери содержание диаграмм, терминологию или справочные
  файлы из соседних репозиториев и других каталогов, если пользователь явно туда
  не указал.
- Предпочитай читаемый несжатый XML `.drawio` и сохраняй стабильные ID при
  редактировании существующих файлов.
- Считай пути коннекторов авторской геометрией. Не оставляй финальный маршрут
  на авторазводку draw.io или на поведение ручек после открытия файла.
- Авторазводка связей draw.io запрещена в финальном `.drawio`. Черновые
  подсказки редактора допустимы только до записи финального XML; в исходнике
  должен остаться выбранный агентом маршрут.
- До сборки XML выбери для каждой связи тип линии, наконечник стрелки, стороны
  входа и выхода, коридор, промежуточные точки или другой явный способ фиксации
  ручной геометрии.
- Считай `edges[].points` обязательными для нетривиальных ломаных и
  ортогональных маршрутов: обхода препятствий, смен оси, пересечений дорожек
  или зон, связей между несоседними узлами и возвратных петель по периметру.
- Прямые соседние связи могут быть без промежуточных точек только при явных
  `entryX`, `entryY`, `exitX` и `exitY` либо другой зафиксированной геометрии,
  которая сохраняет маршрут после повторного открытия.
- Кривые `Curve` и ручные линии разрешены только как осознанный дизайн-выбор:
  задай явный стиль, явную геометрию и проведи визуальный QA, потому что
  эвристический шлюз не может полностью доказать их реальный изгиб.
- Используй `entryX`, `entryY`, `exitX` и `exitY`, когда сторона крепления
  влияет на читаемость.
- Используй `scripts/build_drawio.py` для новых диаграмм, многостраничной
  работы и запросов, которые хорошо раскладываются на страницы, узлы и связи.
- Используй прямые правки XML для точечных изменений, вложенных структур и
  сложных случаев, которые не ложатся в спецификацию сборщика.
- Запускай `scripts/validate_drawio.py` на финальном `.drawio` файле до отчета
  о завершении.
- Запускай `scripts/check_drawio_layout.py` после структурной проверки и считай
  любой `FAIL` стоп-сигналом. Разреши каждое предупреждение или подтверди его
  как ложное срабатывание по последнему экспорту и, когда нужно, по повторно
  открытому виду редактора до передачи результата.
- Используй `scripts/export_drawio.py` для запрошенных экспортов и изображений
  для ревью.
- Временную папку ревью используй только для промежуточного цикла
  экспорт-проверка-исправление. Перед финальным ответом создай или перенеси
  запрошенные экспортные артефакты рядом с финальным `.drawio` и проверь это
  через `ls` и `file`.
- Для визуального QA изображения используй прямой мультимодальный просмотр
  файла моделью: открой последний PNG/JPG через доступный инструмент чтения
  изображений или передай локальный путь как изображение в контекст. Не
  используй браузер, DevTools, Playwright, MCP браузера, Quick Look или
  скриншот просмотрщика для проверки уже экспортированного PNG/JPG/SVG. Если
  прямой просмотр изображения недоступен или ломается, честно считай визуальный
  QA неполным и не заменяй его браузерным обходом.
- Не считай экспорт через настольную командную строку обычным шагом ни в одной
  ОС. Настольное приложение draw.io может падать, зависать, требовать GUI-сеанс
  или вызывать системные диалоги при запуске из автоматизации. На этом хосте
  macOS наблюдавшийся сбой — системный диалог падения. Используй настольный
  экспорт только когда пользователь явно согласен на этот риск или когда
  `DRAWIO_CMD` указывает на более безопасную обертку либо рендерер вместо
  официального настольного бинарного файла.
- Если `scripts/export_drawio.py` блокирует настольный экспорт, но задаче все
  еще нужны PNG, SVG, JPG, PDF или визуальный QA человеком, сразу запроси
  разрешение повторно запустить тот же помощник с `--allow-desktop-export`. Не
  переходи на `qlmanage`, браузерный рендеринг, скриншоты Playwright, миниатюры
  Preview или другой заменяющий рендерер. Не утверждай, что визуальный QA
  завершен, пока официальный экспорт не успешен или пользователь не отказался.
- Используй `scripts/cleanup_drawio_review_artifacts.py` до и после каждого
  цикла визуального ревью, чтобы старые артефакты не засоряли рабочее
  пространство.
- Если доступен `npx @drawio/postprocess`, можешь запускать его на `.drawio`
  файле, чтобы упростить маршруты связей и уменьшить неловкие столкновения.
  Молча пропусти этот шаг, если инструмент недоступен или завершился с ошибкой.

## Рабочий процесс

1. Прочитай `references/workflow.md`.
2. Если бриф неполный, задай один короткий набор вопросов про тип диаграммы,
   аудиторию, формат передачи, контекст редактирования и недостающий материал.
3. Переведи запрос в страницы, узлы, связи, контейнеры, визуальные группы и
   язык подписей до выбора инструментов.
4. Если стиль не задан или есть настоящий визуальный выбор, предложи три
   направления из `references/design-directions.md`: одно спокойное или
   деловое, одно объясняющее или редакторское, одно более выразительное, но все
   еще уместное.
5. Составь план маршрутов до рисования: зафиксируй главное направление чтения,
   назначь дорожки, зоны или страницы, классифицируй каждую связь как основной
   поток, вторичную зависимость, возвратную петлю или асинхронный путь, выбери
   тип линии, наконечник стрелки, стороны входа и выхода плюс коридор для
   каждого нетривиального маршрута.
6. Выбери способ создания:
   - `scripts/build_drawio.py` для новых диаграмм и структурной многостраничной
     работы;
   - прямое редактирование XML для точечных правок или обходов ограничений
     сборщика.
7. Собери или отредактируй `.drawio` исходник с явной геометрией, читаемыми ID
   и достаточными интервалами для целевого режима просмотра.
8. Запусти структурную проверку через `scripts/validate_drawio.py`.
9. Запусти эвристическую проверку компоновки через
   `scripts/check_drawio_layout.py`.
10. Если нужен визуальный QA, выполни цикл экспорт-проверка-исправление из
    `references/workflow.md`, используй
    `scripts/cleanup_drawio_review_artifacts.py` и `scripts/export_drawio.py`.
    Если помощник блокирует настольный экспорт, запроси разрешение на точный
    повторный запуск с `--allow-desktop-export`; не придумывай запасной путь
    ревью.
11. Экспортируй или перенеси запрошенные финальные артефакты рядом с финальным
    `.drawio` только после чистого последнего прохода ревью. Для PNG, SVG, JPG
    и PDF проверь фактическое наличие файлов через `ls` и тип через `file`.
12. Сообщи путь к финальному `.drawio`, запрошенные экспорты, проверенные
    режимы просмотра и оставшиеся ограничения.

## Маршрутизация ресурсов

| Задача | Что читать или использовать |
|---|---|
| Полная рабочая процедура | `references/workflow.md` |
| Структура XML, стили, детали экспорта, корректность разметки | `references/format.md` |
| Эвристики компоновки для семейств диаграмм | `references/patterns.md` |
| Выбор визуального направления | `references/design-directions.md` |
| Чеклист визуального QA | `references/checklist.md` |
| Эвристический шлюз компоновки для пересечений и маршрутов связей | `scripts/check_drawio_layout.py` |
| Чистая папка ревью и очистка старых артефактов | `scripts/cleanup_drawio_review_artifacts.py` |
| Новые диаграммы из структурных спецификаций | `scripts/build_drawio.py` |
| Структурная проверка | `scripts/validate_drawio.py` |
| Экспорт PNG, SVG, JPG или PDF рядом с `.drawio` | `scripts/export_drawio.py` |
| Промпты прямого тестирования на регрессии | `test-prompts.json` |

## Эвристики диаграмм

- Сначала определи семейство диаграммы: блок-схема, архитектурная карта, карта
  взаимодействий в стиле sequence, карта состояний, оргструктура, дерево,
  интеллект-карта или пользовательская сеть.
- Сначала выводи страницы, потом фигуры. Используй несколько страниц
  `<diagram>`, когда одно полотно станет плотным или смешает обзор и детали.
- Держи подписи на полотне короткими. Длинные объяснения переноси в заметки,
  метаданные или отдельные страницы, когда это нужно.
- Предпочитай чтение сверху вниз или слева направо, если пользователь не просит
  другую компоновку.
- Используй один основной стиль связей на диаграмму, но выбирай тип линии
  осознанно: прямую для соседних узлов, ломаную для простых маршрутов с 0-1
  изгибом, ортогональную для 2+ изгибов вокруг препятствий, `Curve` для
  причинных или концептуальных карт, ручной маршрут для редких случаев, где
  стандартные стили ухудшают чтение.
- Держи минимум `24 px` между равноправными узлами вне контейнеров, `24 px` от
  края страницы, `32 px` от границ swimlane, а за минимальный порог
  предупреждения принимай зазор `12 px` между связью и фигурой.
- `edges[].points` обязательны для ломаных и ортогональных связей всякий раз,
  когда маршрут меняет ось, проходит через пространство дорожек или зон,
  обходит препятствие, связывает несоседние узлы или выходит из основного пути
  в возвратную петлю.
- Не оставляй связь без явного маршрута. Если `scripts/check_drawio_layout.py`
  сообщает `auto-routing-forbidden`, исправь геометрию до экспорта и ревью.
- Длинные возвратные петли веди по периметру страницы. Центр диаграммы не
  используй.
- Если первый проход маршрутизации все еще оставляет больше одного основного
  пересечения или больше двух длинных обратных связей через центр, раздели
  содержимое по страницам.
- Предпочитай более широкие блоки, более заметную толщину линий и большие
  интервалы тесным настройкам по умолчанию, особенно в плотных диаграммах и
  диаграммах для презентаций.
- Считай рендеринг редактора draw.io источником истины для посадки текста и
  вида коннекторов, когда пользователь редактирует файл там.
- Разделяй плотные системы на страницы обзора и деталей, вместо того чтобы
  втискивать каждую связь на одно полотно.

## Проверка и критерии готовности

- Структурная проверка должна пройти:
  - XML успешно разбирается;
  - нет XML-комментариев;
  - каждая страница содержит `mxGraphModel`;
  - корневые ячейки `0` и `1` существуют;
  - у каждой связи есть дочерний `mxGeometry`;
  - ссылки `source` и `target` указывают на существующие ячейки;
  - внутри страницы нет повторяющихся ID ячеек.
- Проверка компоновки должна пройти:
  - `scripts/check_drawio_layout.py` сообщает `0 FAIL`;
  - ни одна связь не остается на авторазводке draw.io;
  - равноправные вершины вне контейнеров не пересекаются;
  - ни один авторский сегмент связи или промежуточная точка не пересекает чужую
    вершину вне контейнера;
  - ни одна промежуточная точка не находится внутри чужой вершины вне
    контейнера;
  - предупреждения о кривых или ручных маршрутах закрыты последним визуальным
    QA, потому что скрипт не доказывает их полный реальный изгиб;
  - все предупреждения устранены или доказаны как ложные срабатывания по
    последнему экспорту и, когда нужно, по повторно открытому полотну редактора.
- Визуальный QA должен пройти во всех нужных режимах просмотра:
  - последний экспорт проходит `references/checklist.md`;
  - PNG/JPG проверен прямым мультимодальным просмотром моделью, без браузерного
    MCP или скриншота внешнего просмотрщика;
  - повторно открытое полотно редактора тоже проходит проверку, когда задаче
    нужно ревью в редакторе;
  - для решений по ревью можно использовать только последний экспорт;
  - запрошенные финальные PNG, SVG, JPG или PDF лежат рядом с финальным
    `.drawio`; одной временной папки ревью недостаточно;
  - старые артефакты `.tmp`, `.review` или дубли `.drawio` не остаются.
- Финальная передача должна сообщить `layout gate: 0 fails, 0 unresolved warnings`.

Вне этого навыка остаются задачи, которые не связаны прежде всего с созданием,
редактированием, проверкой, ревью или экспортом диаграмм draw.io и diagrams.net.