How to Set Up Diagram Design Locally: A Complete Installation Guide

Clone the repository, register the local checkout with your agent (Pi or Claude Code), and verify the install by opening the bundled HTML gallery to start generating diagrams offline.

Diagram Design is a self-contained AI skill for creating editorial-quality diagrams. Setting it up locally lets you customize the style guide, add new diagram types, and integrate the skill into private CI pipelines. This guide walks through the complete local installation process using the official cathrynlavery/diagram-design repository.

Prerequisites and Repository Overview

Diagram Design lives under skills/diagram-design/ and uses a progressive disclosure architecture—only files required for the current request load at runtime, minimizing memory footprint.

Component	Purpose	Location
Skill core	Entry point routing requests to diagram types	skills/diagram-design/SKILL.md
References	Color tokens, fonts, semantic patterns, animation contracts	skills/diagram-design/references/
Assets	HTML templates and offline preview gallery	skills/diagram-design/assets/
Scripts	Utilities for draw.io/Mermaid extraction, versioning, screenshots	scripts/
CI/Docs	ADRs, screenshots, workflow validations	docs/adr/, .github/workflows/

A simple flowchart request loads only SKILL.md plus references/type-flowchart.md, keeping the agent responsive.

Step 1: Clone the Repository

Start with a local checkout of the full repository:

git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design

This gives you access to all 38 diagram types, the style guide, and helper scripts.

Step 2: Register with Your Agent

The registration method depends on which AI host you're using.

Pi Installation

Tell Pi to treat the folder as a local package:

pi install ~/code/diagram-design

Claude Code Installation

Create a symlink so the skill appears in Claude's skill directory:

ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

After creating the symlink, restart Claude Code or run the host-specific reload command to discover the new skill.

Step 3: Verify the Local Setup

Open the bundled gallery to confirm all HTML assets are accessible:

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdgd-open skills/diagram-design/assets/index.html

The gallery displays 38 diagram types across three visual variants: light, dark, and full-editorial. If the page loads correctly, your local Diagram Design setup is functional.

Step 4: Customize the Style Guide (Optional)

Edit skills/diagram-design/references/style-guide.md to replace default color and font tokens with your brand's palette:

# Edit the style guide

code skills/diagram-design/references/style-guide.md

Changes take effect immediately for newly generated diagrams—no restart required.

Using Diagram Design Locally

Generate Diagrams from Command Line (Pi)

pi ask "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."

Use Slash Commands in Claude Code or Codex

/diagram-design:make

Then enter a natural language request:

"I need a quadrant showing Q2 projects by impact vs effort."

The agent selects the quadrant type, applies default size/detail settings, and returns a self-contained HTML file.

Import and Re-render draw.io Files

/diagram-design:import-drawio path/to/architecture.drawio --size=slide-16x9 --detail=simplified

The command uses scripts/drawio_extract.py to parse the draw.io IR and produce a fresh diagram following your current style guide.

Export to SVG and PNG

# SVG only

/export-diagram my-diagram.html --svg-only

# High-resolution PNG

/export-diagram my-diagram.html --png-only --scale=3

PNG export requires Playwright. Run this once:

pip install playwright && playwright install chromium

Key Files for Local Development

File	Role
skills/diagram-design/SKILL.md	Main routing logic and type-selection guide
skills/diagram-design/references/style-guide.md	Single source of truth for brand tokens
skills/diagram-design/references/semantic-patterns.md	Behavioral patterns independent of visual layout
skills/diagram-design/references/animation.md	Motion and accessibility contracts
skills/diagram-design/references/type-*.md	One file per diagram type (e.g., type-architecture.md, type-quadrant.md)
skills/diagram-design/assets/index.html	Live gallery for offline preview
scripts/drawio_extract.py	Parses draw.io files to structured IR
scripts/mermaid_extract.py	Parses Mermaid source to same IR
skills/diagram-design/scripts/self_check.py	Runtime validator for generated diagrams

Running CI Checks Locally

The repository includes a full CI pipeline in .github/workflows/ci.yml that validates geometry, accessibility, and consistency. You can run checks manually:

python skills/diagram-design/scripts/self_check.py path/to/generated-diagram.html

This ensures your customizations don't break existing diagram types.

Summary

• Clone the repository to ~/code/diagram-design or your preferred path
• Register with Pi via pi install or with Claude Code via symlink to ~/.claude/skills/
• Verify by opening skills/diagram-design/assets/index.html to see all 38 diagram types
• Customize brand tokens in references/style-guide.md for immediate effect
• Generate diagrams via natural language, slash commands, or file imports
• Validate changes using the built-in self_check.py script

Frequently Asked Questions

Can I run Diagram Design without an AI agent?

No. Diagram Design is implemented as an AI skill that requires a compatible host (Pi, Claude Code, Codex, or Factory Droid) to interpret SKILL.md and route requests. The local setup gives you control over the skill's files, but you still need an agent to execute generation commands.

How do I add a new diagram type?

Create a new file in skills/diagram-design/references/ following the naming convention type-{yourtype}.md. Model it after existing type files like type-architecture.md. Include the diagram's purpose, use cases, data schema, and example prompts. The skill automatically discovers new types at runtime.

Will local changes survive a git pull?

Yes, with caveats. Your modifications to style-guide.md and new type files will persist unless they conflict with upstream changes. Stash or commit your customizations before pulling updates, then reapply them. Consider maintaining a fork with your brand-specific overrides in a separate branch.

Does the local setup support team collaboration?

Yes. Since Diagram Design is a standard Git repository, you can fork it, apply team-specific customizations, and share the fork internally. Team members clone your fork instead of the upstream repo. The CI workflows in .github/workflows/ci.yml run on any clone, enforcing consistency standards across your organization.

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