wliafe/drawio-skill

Draw.io MCP Operation Skill

Uses the Next AI Draw.io MCP Server (@next-ai-drawio/mcp-server) to execute determined drawing tasks. This skill is responsible for tool usage and reliable delivery; it does not dictate layout, color schemes, fonts, or research representation methods. The core flow applies to different AI clients; tool discovery, invocation, and skill loading methods are determined by the current host.

Determine the Task and Service

1. From the user request and current context, determine: create a new file, modify an existing file, continue with the current canvas, or save manual modifications the user just made. Prioritize explicitly specified materials, target directories, and existing versions.
2. Check the currently exposed MCP tools. Map the service tool names below (e.g., get_diagram, edit_diagram, export_diagram) according to the actual tool descriptions. Do not hardcode client namespaces, service aliases, or call syntax.
3. When the target tool is exposed and the current client allows invocation, use the read-only get_drawing_guide to verify the response; preserve existing disable and reject decisions. If already available, proceed and do not re-add. An unexposed tool does not mean it is not installed; to check configuration, installation, reload, or diagnostics, read MCP Check & Installation.
4. This flow targets the package above. If the user explicitly specifies another drawing service, keep their choice, explain the adaptation boundaries, and do not replace it without permission.

Existing services are identified by package identity; the service name may not be drawio. Only report "configured but not yet verified" when configuration is visible but the service has not actually responded. If access to tools, terminal, or configuration is missing, provide the current feasible method without claiming the service does not exist just because it cannot be checked.

Determine Delivery Location and Version

By default, save four files with the same name in project docs/topic name/v1/: topic name.drawio, topic name.png, topic name.svg, topic name.drawio.svg. The name can be in Chinese or English; the version is only in the directory. Start a new topic from v1; for existing diagrams, keep the current version and only add vN when the user explicitly requests it.

For existing files, continue using the original path and name. Do not automatically rename, migrate, or upgrade versions. The user's specified directory, format, and edit boundaries take precedence. When naming, versioning, multi-page, or splitting diagrams is involved, read Drawing & File Conventions.

Session and Object Operations

• Execute MCP operations based on the content and design provided by the current task; when required input cannot be inferred, confirm only the missing items that would change the operation target or result.
• Prioritize reusing confirmed target sessions. When it is indeed necessary to create or resume a session, call start_session and read the tool format and operation constraints from it; if that information is missing, use get_drawing_guide. Checking connectivity does not require creating a new session.
• After loading an existing file with load_diagram, first read object IDs via get_diagram, then modify via edit_diagram by ID. If the current canvas is known and still valid, local edits can be made directly; in case of concurrent modification conflicts, reorganize edits based on the latest content returned by the service, without overwriting the user's new modifications.
• load_diagram and create_new_diagram replace the current document. Before switching, confirm whether the current canvas is the target and whether there are manual modifications to preserve. When the user asks to save current modifications, read and export the current canvas directly without first loading the old file from disk.
• Only use create_new_diagram for new diagrams or when the user explicitly requests a full replacement. All .drawio / .drawio.svg writes and modifications go through MCP; do not use file tools or scripts to directly rewrite diagram XML. Constructing XML parameters as required by the tool is normal invocation.
• Keep text, nodes, relationships, and groups editable; assets can be embedded, but do not flatten the entire diagram into an image to replace the editable source file.
• Before using icons like cloud services or network devices, call get_shape_library and use the actual style names returned; do not guess icon identifiers.
• For multi-page editing, first use list_pages to determine the target, and explicitly use page selection parameters; do not rely on the default first page. When the user says "this box" or "selected arrow", use get_selection. If selection reading is unavailable, read the canvas and locate by page, label, and position; only ask for specifics if there are still multiple candidates. Do not reload the service or repeatedly ask for re-selection.

Images and Capacity

Before inserting images, read Image Preprocessing & Capacity Control. First check the asset and estimated embedded size; compress copies if necessary: allow moderate scaling and lossy compression for photos; prioritize fidelity for text, thin lines, and transparent assets. Do not overwrite original assets, and do not automatically install preprocessing software.

The budget should cover real Base64, full diagram XML, serialized requests, and export responses. get_diagram may collapse image data; do not use the length of the returned text to prove the diagram is not oversized. After inserting large assets, attempt a trial export via MCP early. Diagram creation, modification, and export of all four formats must only use MCP; do not supplement exports with other tools or fabricate unexposed parameters like width, height, scale.

If still blocked after compressing to acceptable clarity, preserve successful results, explain the bottleneck, and let the user decide whether to continue compressing, removing assets, or splitting the diagram. Do not automatically change content or paginate.

Save and Export

1. Before saving, use get_diagram to read the current canvas, corresponding file, page, and output path. First check for sync warnings; "call succeeded but may miss latest manual modifications" is not a confirmation of latest state. Restore sync before formal export; if the tool has already written the file, clarify that the file's recency is not yet verified, and re-export after restoration.
2. Save .drawio via export_diagram; for a complete multi-page source file, do not include page selection parameters. By default, also export PNG, SVG, and editable .drawio.svg; only export the formats the user explicitly requests. For images and editable SVG, explicitly select the target page; do not rely on the browser's active page.
3. .drawio.svg must be exported using the actual format; do not rename a regular SVG as a substitute. Verify the embedded diagram source content; save the current canvas before safe readback. For multi-page, state which pages the copy contains; do not treat a single-page copy as the complete source file.
4. After export, re-read and check the observable content state; check for sync warnings. The service has no universal snapshot lock; if content changes during this time, re-sync and re-export the affected files. Do not treat a single read as proof of consistency across all four files. If changes persist or cannot be confirmed, explicitly state that sync verification is incomplete; if necessary, ask the user to pause manual editing.
5. Use absolute paths in the actual MCP runtime environment. Verify content integrity and whether assets are missing in the generated files and final rendering; a successful screenshot does not mean a successful formal export. Viewing XML or seeing an export success message does not replace actual rendering checks.
6. After connection recovery, retry once; if there is a clear capacity issue, fix the capacity first, then retry the affected steps once. Do not call repeatedly without changes; if still failing, explain the specific bottleneck and missing formats. See Drawing & File Conventions for detailed save rules.

Feedback Results

Briefly give the source file, image, version used, and checks performed. Report "configuration exists", "tool responded", "file saved", and "rendering checked" truthfully as appropriate.

If image export or visual inspection is blocked, first preserve the successfully saved source file, and explain the missing formats and specific reasons; do not use old images to impersonate the current export, and do not present unverified parts as complete.