Noureddine RAMDI / drawio-skill: pure SKILL.md AI agent skill for professional draw.io diagrams with self-checking

Created Mon, 04 May 2026 10:23:01 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
927 Words
github-stars ai drawio skill.md agent-skill diagram-generation self-check

Agents365-ai/drawio-skill

Generating professional diagrams from natural language is a common pain point for AI coding agents. drawio-skill tackles this by providing a pure SKILL.md solution that generates production-grade draw.io diagrams with complex layouts and automatic self-correction. Its standout feature is a self-check plus iterative refinement loop that reads its own exported PNG outputs, detects multiple issue types, and auto-fixes them across rounds, all without external servers or dependencies.

What drawio-skill does and how it works

drawio-skill is a pure SKILL.md implementation designed to enable AI coding agents to generate professional-quality draw.io diagrams directly from natural language descriptions. It supports six diagram type presets — Entity-Relationship Diagrams (ERD), UML Class diagrams, Sequence diagrams, Architecture diagrams, Machine Learning/Deep Learning model diagrams, and Flowcharts.

Under the hood, the skill produces XML that draw.io understands, with precise layout features like 10px grid-aligned coordinates, complexity-scaled spacing between elements, routing corridors for connectors, and animated connectors for better visual clarity. A semantic 7-color system ensures consistent visual branding and clarity.

The skill is architected to be plug-and-play across six agent platforms (Claude Code, Opencode, OpenClaw, Hermes Agent, OpenAI Codex, SkillsMP, ClawHub) with zero configuration beyond copying the SKILL.md file into the right directory. The only external dependency is the draw.io desktop CLI, which is required for exporting diagrams.

Notably, the skill supports generating ML model diagrams with tensor shape annotations, a feature uncommon in diagram generation tools.

The self-check and iterative refinement loop as a technical core

What sets drawio-skill apart is its implementation of a self-check plus iterative refinement loop entirely inside the SKILL.md format. After generating a diagram, the skill exports it as a PNG and reads the output back in to detect six categories of issues such as layout problems or connector malformations.

It then applies auto-fixes over two rounds to address these detected issues, improving the diagram quality before presenting it to the user. Beyond this, it supports up to five rounds of targeted user feedback to iteratively refine the output further.

This pattern is rare because it avoids external MCP servers or runtime dependencies, keeping the skill self-contained and portable. Architecturally, it demonstrates a clean skill-based agent design where the generation, validation, and refinement loops happen as part of the skill itself.

The tradeoff here is complexity inside the SKILL.md and reliance on the draw.io desktop CLI for exporting and reading outputs. This means the skill is tightly coupled to the draw.io ecosystem and requires local CLI tooling, which might limit cloud or serverless deployments.

Code quality under the hood is surprisingly clean for a pure SKILL.md implementation, with well-structured XML generation and clear semantic color schemes. The skill balances between expressive power and the constraints of the SKILL.md format.

Quick start

The draw.io desktop app must be installed for diagram export:

macOS

# (Refer to draw.io official docs for macOS installation)

Claude Code

# Global install (available in all projects)
git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill

# Project-level install
git clone https://github.com/Agents365-ai/drawio-skill.git .claude/skills/drawio-skill

Opencode

# Global install (Opencode-native path)
git clone https://github.com/Agents365-ai/drawio-skill.git ~/.config/opencode/skills/drawio-skill

# Project-level install
git clone https://github.com/Agents365-ai/drawio-skill.git .opencode/skills/drawio-skill

Opencode also reads ~/.claude/skills/ and .claude/skills/, so an existing Claude Code install is automatically picked up — no second clone needed.

OpenClaw

# Manual install
git clone https://github.com/Agents365-ai/drawio-skill.git ~/.openclaw/skills/drawio-skill

# Project-level install
git clone https://github.com/Agents365-ai/drawio-skill.git skills/drawio-skill

Hermes Agent

# Install under design category
git clone https://github.com/Agents365-ai/drawio-skill.git ~/.hermes/skills/design/drawio-skill

Or add an external directory in ~/.hermes/config.yaml:

skills:
  external_dirs:
    - ~/myskills/drawio-skill

OpenAI Codex

# User-level install
git clone https://github.com/Agents365-ai/drawio-skill.git ~/.agents/skills/drawio-skill

# Project-level install
git clone https://github.com/Agents365-ai/drawio-skill.git .agents/skills/drawio-skill

SkillsMP

Browse on SkillsMP or use the CLI:

skills install drawio-skill

ClawHub

Browse on ClawHub or use the CLI:

clawhub install drawio-pro-skill

Installation paths summary

PlatformGlobal pathProject path
Claude Code~/.claude/skills/drawio-skill/.claude/skills/drawio-skill/

verdict

drawio-skill is a well-crafted pure SKILL.md agent skill that addresses a clear pain point: generating complex, professional draw.io diagrams from natural language across multiple AI agent platforms.

Its self-check and iterative refinement loop is a neat demonstration of what’s possible within the SKILL.md format without external dependencies. This makes it portable and straightforward to integrate if you already use any of the supported agents and have access to the draw.io desktop CLI.

That said, the reliance on draw.io desktop CLI means it’s less suited for fully cloud-native workflows or serverless environments. Also, the skill’s complexity and tight coupling to draw.io XML may require some learning curve if you want to customize it deeply.

Overall, it’s a solid choice for AI researchers, developers, or teams wanting to embed diagram generation into their agent workflows with a polished output and self-correcting mechanism. If your pipeline includes local tooling and you want a no-fuss, zero-config skill to produce diagrams reliably, drawio-skill is worth a look.

→ GitHub Repo: Agents365-ai/drawio-skill ⭐ 1,073