How to Generate Diagrams Using the Agent Skills Plugin

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.

Core Capabilities Defined in SKILL.md

The plugin's behavior is governed by 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. 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 parser.

Import Draw.io resides in commands/import-drawio.md. This command accepts Draw.io XML files, extracts shape and connection data via 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. 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.

Plugin Registration Architecture

Before invoking any commands, Instagit loads the plugin through .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 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.

# 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.

# 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.

# 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.

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, commands/import-drawio.md, and commands/export-diagram.md respectively.
• Low-level parsing is handled by mermaid_extract.py and drawio_extract.py located in skills/diagram-design/scripts/.
• The plugin registers with Instagit via .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 and 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. 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 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 script referenced in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}