# How to Generate Diagrams Using the Agent Skills Plugin

> Easily generate SVG and PNG diagrams from Mermaid text or Draw.io XML with the Agent Skills plugin. No manual parsing needed for cathrynlavery/diagram-design.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-08

---

**The Agent Skills plugin in the cathrynlavery/diagram-design repository exposes high-level async commands that convert Mermaid text or Draw.io XML into rendered SVG and PNG images without requiring manual parsing code.**

The **Agent Skills plugin** transforms Instagit into a diagram generation engine by wrapping complex extraction and rendering logic behind a simple Python API. According to the source code in `cathrynlavery/diagram-design`, this plugin registers three core capabilities—importing Mermaid diagrams, importing Draw.io files, and exporting to image formats—allowing developers to generate diagrams using the Agent Skills plugin through a unified skill manifest located at [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

## Core Capabilities Defined in SKILL.md

The plugin's behavior is governed by [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) in the `skills/diagram-design/` directory. This manifest declares three primary commands that Instagit agents invoke to process visual data.

**Import Mermaid** is defined in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md). This capability parses Mermaid-style text blocks—such as flowcharts and sequence diagrams—and converts them into an intermediate diagram model using the underlying [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) parser.

**Import Draw.io** resides in [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md). This command accepts Draw.io XML files, extracts shape and connection data via [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py), and constructs the same intermediate representation used by the Mermaid importer.

**Export Diagram** is implemented in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). This final step takes the intermediate model and renders it as SVG, PNG, or raw JSON using the rendering utilities found in [`skills/diagram-design/scripts/render-canonical-screenshots.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/render-canonical-screenshots.py).

## Plugin Registration Architecture

Before invoking any commands, Instagit loads the plugin through [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json). This registration file maps the skill manifest to the Agent Skills namespace, making the `diagram_design` module available under `agent.skills` in your Python environment. The plugin delegates all heavy lifting to the parser scripts, so you never call [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) directly; instead, you interact with the high-level API exposed by the skill manifest.

## Step-by-Step Generation Workflow

The following Python examples demonstrate the complete workflow to generate diagrams using the Agent Skills plugin. Each snippet references the specific command file responsible for the operation.

### Importing Mermaid Syntax

To convert Mermaid text into a manipulable model, pass the diagram string to the `import_mermaid` method. This corresponds to the logic defined in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md).

```python

# Command defined in: commands/import-mermaid.md

mermaid_source = """
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Proceed]
    B -->|No| D[Stop]
"""

# Returns intermediate diagram model for further processing

diagram_model = await agent.skills.diagram_design.import_mermaid(mermaid_source)

```

### Importing Draw.io XML Files

For existing Draw.io diagrams, provide a local filesystem path or a remote URL to the `import_drawio` method as specified in [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md).

```python

# Command defined in: commands/import-drawio.md

drawio_model = await agent.skills.diagram_design.import_drawio(
    "https://example.com/architecture.drawio"
)

# Extracts shapes and connections into the standard model format

```

### Exporting to SVG or PNG

Once you hold the intermediate model in memory, trigger the export command to generate the final image. The `export_diagram` method supports format selection and optional theming.

```python

# Command defined in: commands/export-diagram.md

svg_output = await agent.skills.diagram_design.export_diagram(
    model=diagram_model,
    format="svg",      # Alternative values: "png" or "json"

    theme="light"      # Optional: defaults to repository theme

)

```

### Complete End-to-End Example

Combine all three commands to transform raw diagram data into a displayable asset within an Instagit session.

```python
from IPython.display import SVG, display

# Step 1: Import raw Mermaid syntax

raw_mermaid = "graph TD; A-->B; B-->C;"
model = await agent.skills.diagram_design.import_mermaid(raw_mermaid)

# Step 2: Export to SVG format

svg_bytes = await agent.skills.diagram_design.export_diagram(
    model=model,
    format="svg"
)

# Step 3: Render in notebook

display(SVG(svg_output))

```

## Summary

- The Agent Skills plugin exposes three primary commands—**Import Mermaid**, **Import Draw.io**, and **Export Diagram**—defined in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md), [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md), and [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) respectively.
- Low-level parsing is handled by [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) located in `skills/diagram-design/scripts/`.
- The plugin registers with Instagit via [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json), making it accessible as `agent.skills.diagram_design`.
- All commands follow an async Python API pattern, accepting source strings or URLs and returning intermediate models before final export to SVG, PNG, or JSON.

## Frequently Asked Questions

### What input formats does the Agent Skills plugin support?

The plugin natively supports Mermaid text syntax and Draw.io XML files. According to the source code in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md), both formats are normalized into a single intermediate model stored in memory before rendering, ensuring consistent export behavior regardless of the original input type.

### Can I customize the visual theme when exporting diagrams?

Yes. The `export_diagram` command accepts an optional `theme` parameter as implemented in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). While the default theme pulls from the repository configuration, you can override it with string values such as `"light"` or `"dark"` when calling the export method to match your documentation style.

### Is the Agent Skills plugin available outside of Instagit?

The plugin is designed specifically for the Instagit environment as indicated by the [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json) registration file. It depends on Instagit's agent runtime to resolve the `agent.skills` namespace and to execute the underlying parser scripts located in `skills/diagram-design/scripts/`.

### How does the plugin handle errors in malformed Mermaid syntax?

The [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) script referenced in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) performs strict validation during the import phase. If the parser encounters invalid syntax, the `import_mermaid` async function raises a runtime exception with diagnostic details before reaching the export stage, preventing the generation of corrupted images.