# Drawio Syntax Metadata > > - **Type:** Skill - **Install:** `agentstack add skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-metadata` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio) - **Source:** https://github.com/Impertio-Studio/Draw.io-Claude-Skill-Package/tree/main/skills/source/drawio-syntax/drawio-syntax-metadata ## Install ```sh agentstack add skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-metadata ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Draw.io Syntax: Metadata ## Purpose This skill teaches how to build multi-page Draw.io diagrams, manage layers, attach custom properties via `` wrappers, define file-level variables, use the `%placeholder%` substitution system, add tooltips and links, and enable MathJax/LaTeX rendering. It covers everything OUTSIDE the individual cell creation covered by `drawio-syntax-cells`. ## Critical Rules (Memorize These) 1. **ALWAYS use unique `id` values on every `` element.** Duplicate diagram IDs corrupt the file. 2. **NEVER nest `` elements inside each other.** Every `` is a direct child of ``. 3. **ALWAYS set `placeholders="1"` on the `` wrapper** to enable `%variable%` substitution. Without it, placeholder tokens render as literal text. 4. **ALWAYS use single-quoted JSON for the `vars` attribute** on ``: `vars='{"key":"value"}'`. Double quotes around the attribute value break XML parsing. 5. **NEVER omit the structural cells** (`id="0"` and `id="1" parent="0"`) on ANY page. Every `` MUST contain both. 6. **ALWAYS keep cell IDs unique across ALL pages** in the file, not just within a single page. 7. **ALWAYS use the full `` wrapper** when the diagram needs multi-page support, file-level variables, or MathJax. 8. **NEVER put `id` or `value` on the inner ``** when using an `` wrapper. These attributes belong on ``. ## Decision Tree: When Do I Need This Skill? ``` Does the diagram need multiple pages/tabs? YES --> Section 1 (Multi-Page Diagrams) Does the diagram need layers (background, foreground, annotations)? YES --> Section 2 (Layer System) Does any cell need custom key-value metadata? YES --> Section 3 (Custom Properties) Does the diagram need shared variables across all pages? YES --> Section 4 (File-Level Variables) Does any label contain %placeholder% tokens? YES --> Section 5 (Placeholder System) Does any cell need a tooltip or hyperlink? YES --> Section 6 (Tooltips and Links) Does the diagram contain mathematical formulas? YES --> Section 7 (MathJax/LaTeX) ``` --- ## 1. Multi-Page Diagrams A multi-page diagram uses the full `` wrapper with multiple `` children. Each `` represents one tab/page in the Draw.io editor. ### Structure ```xml ``` ### Rules | Rule | Enforcement | |------|-------------| | Each `` has a unique `id` | ALWAYS — duplicate IDs corrupt the file | | Each `` has a `name` attribute | ALWAYS — this is the tab label | | Each page has its own `` and `` | ALWAYS — pages are independent | | Each `` contains `id="0"` and `id="1" parent="0"` | ALWAYS — mandatory structural cells | | Cell IDs are unique across ALL pages | ALWAYS — NEVER reuse an ID from another page | | `` elements are siblings, not nested | ALWAYS — NEVER nest a diagram inside another | | `compressed="false"` on `` | ALWAYS for AI-generated XML | ### Internal Page Links Link from one cell to another page using the `data:page/id,` prefix: ```xml ``` The `link` value `data:page/id,page-2` navigates to the `` with `id="page-2"`. --- ## 2. Layer System Layers are `` elements with `parent="0"`. The default layer is `id="1"`. Additional layers are added as sibling cells with `parent="0"`. ### Adding Layers ```xml ``` ### Assigning Content to Layers Set the `parent` attribute on content cells to the layer's ID: ```xml ``` ### Layer Rules | Rule | Enforcement | |------|-------------| | Layer cells have `parent="0"` | ALWAYS | | Layer cells have a `value` attribute (display name) | ALWAYS — shown in the Layers panel | | Default layer `id="1"` exists in every page | ALWAYS — mandatory | | Layer stacking follows XML document order | ALWAYS — earlier layers render BEHIND later layers | | `visible="0"` hides a layer and all its content | Use for annotation or draft layers | | Content cells reference their layer via `parent` | ALWAYS — `parent="1"` or `parent=""` | ### Layer with Custom Properties Wrap a layer cell in `` to attach metadata and enable placeholder inheritance: ```xml ``` Child cells of this layer inherit the `env` property for placeholder resolution. --- ## 3. Custom Properties via object Wrapper To attach custom key-value metadata to any cell, wrap the `` in an `` element. `` and `` are functionally identical. ### Structure ```xml ``` ### Attribute Placement Rules | Attribute | On `` | On inner `` | |-----------|---------------|---------------------| | `id` | ALWAYS | NEVER | | `label` | ALWAYS (replaces `value`) | NEVER (`value` not used) | | `tooltip` | YES | NEVER | | `link` | YES | NEVER | | `placeholders` | YES | NEVER | | `tags` | YES | NEVER | | Custom attributes | YES | NEVER | | `vertex` / `edge` | NEVER | ALWAYS | | `parent` | NEVER | ALWAYS | | `source` / `target` | NEVER | ALWAYS (edges) | | `style` | NEVER | ALWAYS | ### Reserved Attributes on object | Attribute | Purpose | |-----------|---------| | `id` | Unique identifier (REQUIRED) | | `label` | Display text (REQUIRED) | | `tooltip` | Hover text shown in the editor | | `link` | URL or internal page link | | `placeholders` | `"1"` to enable `%variable%` substitution | | `tags` | Comma-separated tags for search/filter | Any attribute NOT in this list becomes a custom property visible in Edit Data (Ctrl+M). --- ## 4. File-Level Variables File-level variables are defined as a JSON string in the `vars` attribute of ``. They are available to all cells on all pages. ### Syntax ```xml ``` ### Rules | Rule | Enforcement | |------|-------------| | `vars` value is a JSON string | ALWAYS | | `vars` attribute uses single quotes around the JSON | ALWAYS — double quotes break XML: `vars='{"key":"val"}'` | | JSON keys and values use double quotes inside | ALWAYS — valid JSON requires double-quoted strings | | File-level variables require `` wrapper | ALWAYS — NOT available with simplified `` format | | Variables are available across all pages | ALWAYS | ### Accessing File-Level Variables Use `%variableName%` in labels or tooltips. The containing cell MUST have `placeholders="1"`: ```xml ``` Renders as: "Project: Atlas v2.1" --- ## 5. Placeholder System Placeholders substitute `%variableName%` tokens in labels and tooltips with values from properties and variables. ### Enabling Placeholders Set `placeholders="1"` on the `` wrapper: ```xml ``` ### Resolution Order (First Match Wins) Draw.io resolves `%placeholder%` by walking UP the containment hierarchy: | Priority | Scope | Source | |----------|-------|--------| | 1 | Cell level | Attributes on the `` wrapper itself | | 2 | Parent container | Attributes on the parent group/container `` | | 3 | Ancestor containers | Continue upward through nested containers | | 4 | Layer level | Attributes on the layer cell (`parent="0"`) | | 5 | Root cell | Attributes on `` (or its `` wrapper) | | 6 | File level | JSON variables in `vars` on `` | If no match is found at any level, the placeholder renders as blank text. ### Predefined Placeholders These work without defining custom properties: | Placeholder | Value | |-------------|-------| | `%id%` | Cell ID | | `%width%` | Cell width in pixels | | `%height%` | Cell height in pixels | | `%length%` | Edge length (edges only) | | `%date%` | Current date | | `%time%` | Current time | | `%timestamp%` | Full timestamp | | `%date{format}%` | Formatted date (Java SimpleDateFormat syntax) | | `%page%` | Current page name | | `%pagenumber%` | Current page number | | `%pagecount%` | Total page count | | `%filename%` | File name | Unit conversion variants: `%width:mm%`, `%height:in%`, `%width:m%`. ### Escaping Literal Percent Signs Use `%%` to display a literal `%`: ``` Battery: 80%% charged --> "Battery: 80% charged" ``` --- ## 6. Tooltips and Links ### Tooltips Set `tooltip` on the `` wrapper: ```xml ``` Tooltips support `%placeholder%` substitution when `placeholders="1"` is set. ### External Links Set `link` to a URL: ```xml ``` ### Internal Page Links Link to another page within the same file using `data:page/id,`: ```xml ``` ### HTML Links in Labels Links inside HTML labels use XML-escaped `` tags: ```xml ``` --- ## 7. MathJax / LaTeX Support Draw.io supports LaTeX math rendering via MathJax. Formulas are rendered inline in cell labels. ### Enabling MathJax Set `math="1"` on the `` element: ```xml ``` ### Inline Math Use `$$...$$` delimiters in the cell value: ```xml ``` ### Display Math (Block) Use `$$...$$` on its own line for display-mode rendering: ```xml ``` ### MathJax Rules | Rule | Enforcement | |------|-------------| | `math="1"` on `` | ALWAYS — without it, LaTeX renders as plain text | | `html=1` in the cell style | ALWAYS — MathJax requires HTML rendering | | `$$...$$` delimiters around formulas | ALWAYS — this is the only supported delimiter | | XML-escape special characters in formulas | ALWAYS — `` has a unique `id` and a `name` - [ ] No `` elements are nested inside each other - [ ] Every `` contains `` and `` - [ ] Cell IDs are unique across ALL pages - [ ] `vars` attribute uses single-quoted JSON: `vars='{"key":"val"}'` - [ ] `placeholders="1"` is set on every `` that uses `%variable%` tokens - [ ] `` wrappers have `id` and `label`; inner `` has neither - [ ] `math="1"` is set on `` when LaTeX formulas are present - [ ] Layer cells have `parent="0"` and a `value` attribute - [ ] Internal page links use `data:page/id,` format - [ ] `compressed="false"` is set on `` for AI-generated diagrams ## References - [references/methods.md](references/methods.md) — Complete attribute reference for pages, layers, variables, and placeholders - [references/examples.md](references/examples.md) — Working XML examples for every metadata pattern - [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do, with explanations ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Impertio-Studio](https://github.com/Impertio-Studio) - **Source:** [Impertio-Studio/Draw.io-Claude-Skill-Package](https://github.com/Impertio-Studio/Draw.io-Claude-Skill-Package) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-metadata - Seller: https://agentstack.voostack.com/s/impertio-studio - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.