Directory Structure of the Diagram Design Skill: Complete Technical Guide

The Diagram Design skill organizes its codebase into three logical layers—Commands, Prompts, and Skill Core—enabling lazy loading of only the specific reference documentation needed for each diagram type.

The cathrynlavery/diagram-design repository implements a modular architecture that separates user-facing interfaces from underlying logic. At its heart lies the skills/diagram-design/ directory, which houses the core implementation, reference documentation, and automation scripts. This directory structure supports 39 distinct diagram types while maintaining strict separation between slash-command definitions, LLM prompt templates, and execution logic.

Three-Layer Architecture Overview

The repository splits functionality into three distinct layers that work together to process diagram requests efficiently.

Commands Layer

The commands/ directory at the repository root contains user-facing slash-command definitions that agents expose. Each markdown file maps a command name to its interface contract:

• export-diagram.md – Defines the /export-diagram command
• import-drawio.md – Handles Draw.io file ingestion
• import-mermaid.md – Processes Mermaid diagram syntax
• profile.md – Manages user profile settings
• doctor.md – Diagnostic and troubleshooting utilities

Prompts Layer

The prompts/ directory stores LLM prompt templates that correspond directly to each command. This separation ensures that command interfaces remain distinct from the underlying prompt engineering:

• export-diagram.md – Prompt template for diagram export operations
• import-mermaid.md – Prompt for parsing Mermaid syntax
• profile.md and doctor.md – Supporting command prompts

Skill Core Layer

The skills/diagram-design/ directory contains the actual implementation logic, reference materials, and automation scripts. This is the heavy-lifting component that agents load on demand.

Skill Core Directory Structure

The core skill implementation follows a deliberate hierarchy designed for maintainability and performance.

Core Routing and Documentation

The SKILL.md file serves as the central router and design-system overview. It defines how the skill interprets requests and routes them to appropriate reference files based on diagram type and complexity.

References Directory

The references/ folder contains 39 specialized markdown files—one per visual type—plus shared documentation:

• Style and Standards: style-guide.md (colors, fonts, branding tokens), semantic-patterns.md, animation.md
• Import Specifications: import-drawio.md, import-mermaid.md, output-spec.md
• Type Definitions: type-architecture.md, type-flowchart.md, and 36 additional visual-type references
• User Guides: onboarding.md, profiles.md, export.md

Scripts Directory

The scripts/ folder within the skill contains Python utilities for data extraction and validation:

• drawio_extract.py – Transforms .drawio files into the skill's internal intermediate representation
• mermaid_extract.py – Parses Mermaid syntax for diagram generation
• self_check.py – Automated validation of diagram outputs

Assets Directory

The assets/ directory bundles self-contained HTML galleries and templates:

• index.html – Live gallery showcasing all 39 diagram variants
• template*.html – Reusable HTML scaffolds for diagram generation
• example-<type>.html – Per-type animated examples and icons

How the Structure Enables Lazy Loading

The directory layout supports lazy loading, ensuring agents only pull necessary resources. When processing a simple request like "make a flowchart," the system loads only:

1. skills/diagram-design/SKILL.md for routing logic
2. references/type-flowchart.md for type-specific guidance

Complex requests requiring semantic patterns or animation trigger additional reference files on demand. This architecture minimizes context window usage and improves response times.

Practical Navigation and Usage

Navigate the directory structure using these commands to access specific components:

# Open the visual gallery of all 39 diagram types

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

# On Linux systems

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

When executing slash commands, the agent traverses the directory hierarchy automatically:

# Triggers commands/import-drawio.md, prompts/import-drawio.md,

# and references/import-drawio.md plus type-specific references

/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified

# Invokes the export pipeline using assets/template-*.html scaffolds

/export-diagram path/to/diagram.html --svg-only

Repository-Wide Validation Tools

The root-level scripts/ directory contains CI gates that enforce consistency across the structure:

• verify-geometry.py – Validates label placement and geometric constraints
• bump-plugin-version.py – Version management for marketplace manifests
• render-canonical-screenshots.py – Generates documentation images

These tools ensure that additions to the references/ directory or changes to SKILL.md maintain the repository's architectural standards.

Summary

• The Diagram Design skill resides in skills/diagram-design/ and implements a three-layer architecture separating Commands, Prompts, and Core logic.
• Lazy loading minimizes resource usage by loading only SKILL.md and relevant references/type-*.md files per request.
• The references/ directory contains 39 type-specific guides plus style standards, while scripts/ houses Python extractors like drawio_extract.py.
• Assets are self-contained in assets/index.html and template files, enabling offline gallery browsing.
• Validation scripts in the root scripts/ directory enforce geometry and consistency across the entire directory structure.

Frequently Asked Questions

Where is the main entry point for the Diagram Design skill?

The primary entry point is skills/diagram-design/SKILL.md. This file contains the core skill description, routing logic, and design-system overview that agents consult first when processing any diagram-related request.

How many diagram types does the skill support?

The skill supports 39 distinct visual types, each defined in its own markdown file within skills/diagram-design/references/ (e.g., type-architecture.md, type-flowchart.md). The assets/index.html file provides a browsable gallery of all supported types.

What is the relationship between the commands and prompts directories?

Each file in commands/ has a corresponding template in prompts/ with the same basename. For example, commands/export-diagram.md defines the user interface for the slash command, while prompts/export-diagram.md contains the actual LLM instructions that execute when that command is invoked.

How does the skill handle Draw.io file imports?

The skill processes Draw.io files through a pipeline involving commands/import-drawio.md for command definition, prompts/import-drawio.md for LLM instructions, references/import-drawio.md for technical specifications, and scripts/drawio_extract.py for Python-based XML extraction and transformation into the skill's internal representation.

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