# Directory Structure of the Diagram Design Skill: Complete Technical Guide

> Explore the Diagram Design skill directory structure in cathrynlavery/diagram-design. Learn about its Commands, Prompts, and Skill Core layers for efficient documentation loading.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/export-diagram.md) – Defines the `/export-diagram` command
- [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) – Handles Draw.io file ingestion
- [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) – Processes Mermaid diagram syntax
- [`profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profile.md) – Manages user profile settings
- [`doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/export-diagram.md) – Prompt template for diagram export operations
- [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) – Prompt for parsing Mermaid syntax
- [`profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profile.md) and [`doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) (colors, fonts, branding tokens), [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)
- **Import Specifications**: [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md), [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md), [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md)
- **Type Definitions**: [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md), [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md), and 36 additional visual-type references
- **User Guides**: [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md), [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md), [`export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export.md)

### Scripts Directory

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

- [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) – Transforms `.drawio` files into the skill's internal intermediate representation
- [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) – Parses Mermaid syntax for diagram generation
- [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) – Automated validation of diagram outputs

### Assets Directory

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

- [`index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) for routing logic
2. [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash

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

```bash

# 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

```

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) – Validates label placement and geometric constraints
- [`bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/bump-plugin-version.py) – Version management for marketplace manifests
- [`render-canonical-screenshots.py`](https://github.com/cathrynlavery/diagram-design/blob/main/render-canonical-screenshots.py) – Generates documentation images

These tools ensure that additions to the `references/` directory or changes to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py).
- **Assets** are self-contained in [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md), [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)). The [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) defines the user interface for the slash command, while [`prompts/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) for command definition, [`prompts/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/import-drawio.md) for LLM instructions, [`references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-drawio.md) for technical specifications, and [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) for Python-based XML extraction and transformation into the skill's internal representation.