# Diagram Design Repository Directory Structure: A Complete File-by-File Guide

> Explore the cathrynlavery/diagram-design repository's directory structure. This guide details the layered organization of agent plugins, commands, prompts, and the core skill package for efficient code management.

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

---

**TLDR:** The Diagram Design repository organizes its code into a layered structure with agent plugin manifests, command definitions, prompt templates, and a core skill package under `skills/diagram-design/` that separates references, scripts, and assets for progressive loading.

The **Diagram Design repository** (`cathrynlavery/diagram-design`) is a multi-agent skill for generating presentation-ready diagrams across 39 different visual types. Its directory structure is intentionally modular so that agents — Claude Code, Codex, Factory Droid, and Pi — can fetch only the files they need for a given request. This guide walks through every top-level folder, explains what lives where, and shows you how to interact with the codebase.

## How the Diagram Design Repository Is Organized

The repository separates the skill’s core logic, command surfaces, prompt templates, assets, and CI tooling into distinct directories. Each agent reads its own marketplace manifest and command files, while the shared skill logic lives in `skills/diagram-design/`.

### Top-Level Directory Breakdown

| Directory | Purpose | Notable Contents |
|-----------|---------|------------------|
| `.agents/plugins/` | Marketplace manifest for Factory Droid plugin registration | [`marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/marketplace.json) |
| `.claude-plugin/` | Claude marketplace manifest | [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) |
| `.codex-plugin/` | Codex marketplace manifest | [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) |
| `.factory-plugin/` | Factory Droid marketplace manifest | [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) |
| `commands/` | Slash-command definitions for each agent | [`export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-diagram.md), [`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), [`profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profile.md), [`doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/doctor.md) |
| `prompts/` | Prompt-template files for Pi and other agents | [`export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-diagram.md), [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md), [`profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profile.md), [`doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/doctor.md) |
| `skills/diagram-design/` | The core skill package | [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), subfolders |
| `scripts/` | Build and CI verification tools | [`bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/bump-plugin-version.py), [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py), [`lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-render.py) |
| `docs/adr/` | Architecture Decision Records | [`0005-label-geometry-is-verified.md`](https://github.com/cathrynlavery/diagram-design/blob/main/0005-label-geometry-is-verified.md) |
| `docs/screenshots/` | Images used in README and docs | `architecture.png`, `loop.png` |

The complete top-level tree (as excerpted from the README) looks like this:

```

diagram-design/
├── .agents/plugins/
├── .claude-plugin/
├── .codex-plugin/
├── .factory-plugin/
├── commands/
├── prompts/
├── skills/
│   └── diagram-design/
│       ├── SKILL.md
│       ├── references/
│       ├── scripts/
│       └── assets/
├── scripts/
├── docs/adr/
└── docs/screenshots/

```

## Inside the Core Skill Package: `skills/diagram-design/`

The heart of the repository is the **`skills/diagram-design/`** directory. This is where the actual diagram-generation logic lives, and it is structured around a **progressive-disclosure pattern**: it loads only the files relevant to a specific request.

### [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) — The Entry Point

[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) is the main routing file. It receives user requests, identifies the diagram type, and points the agent to the correct lazy-loaded reference documents. It documents the full design system and all 39 diagram types.

### `references/` — Lazy-Loaded Design Knowledge

The `references/` directory contains markdown files that define the skill’s design vocabulary:

- [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) — the single source of truth for colors, fonts, and token names
- [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) — seven behavior-rich patterns that combine with any visual type
- [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) — the contract for optional motion and accessibility requirements
- [`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), etc. — one reference file per diagram type

An agent handling a **flowchart** request only pulls [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md). Adding animation pulls [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) on top. This selective loading keeps runtime overhead minimal.

### `scripts/` — Parsing and Validation Utilities

Three core Python scripts handle the parsing and validation workflow:

- [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) — parses Draw.io files into the internal representation
- [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) — parses Mermaid source blocks into the internal representation
- [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) — validates generated output against the skill’s contract

These scripts are invoked from the command line and referenced by the command definitions throughout the repository.

### `assets/` — Templates and Live Gallery

- [`index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/index.html) — the live gallery that links to every generated diagram type
- [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) — base HTML template for rendering new diagrams
- `example-<type>.html` — sample diagrams for each visual type

## Commands and Prompts: The Agent Surface Layer

The `commands/` and `prompts/` directories both define the same operations but target different agents.

- **`commands/`** holds markdown files that define slash commands for interactive agents: [`export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export-diagram.md), [`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), [`profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profile.md), [`doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/doctor.md)
- **`prompts/`** holds equivalent `.md` files used by Pi and other agents to perform the same set of operations

This duplication keeps each agent’s interaction model isolated without duplicating the core logic — both surfaces point back to `skills/diagram-design/scripts/`.

## Root-Level `scripts/` — CI and Developer Tooling

The repository root also contains its own `scripts/` directory for build and verification utilities used by CI and local developers:

- [`bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/bump-plugin-version.py) — tracks plugin versioning
- [`render-canonical-screenshots.py`](https://github.com/cathrynlavery/diagram-design/blob/main/render-canonical-screenshots.py) — generates the 39-type PNG catalog for the README gallery
- [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) — CI gate that checks label placement for geometric correctness
- [`lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-render.py) — code-quality gate for generated output

## Documentation Directories

- **`docs/adr/`** holds Architecture Decision Records — short, rationale documents for key design choices (e.g., [`0005-label-geometry-is-verified.md`](https://github.com/cathrynlavery/diagram-design/blob/main/0005-label-geometry-is-verified.md))
- **`docs/screenshots/`** stores the PNG images that the README and other docs reference

## Practical Examples: Interacting with the Directory Structure

Here are four runnable commands that demonstrate walking through the repository structure.

### 1. Import a Draw.io diagram

```bash
diagram-design/skills/diagram-design/scripts/drawio_extract.py \
    path/to/source.drawio \
    --detail balanced \
    --size slide-16x9 \
    --output my-diagram.html

```

### 2. Run the self-check on a generated diagram

```bash
python3 skills/diagram-design/scripts/self_check.py generated-diagram.html

# Expected output: "OK"

```

### 3. List all downloadable diagram-type reference files

```bash
git ls-files "skills/diagram-design/references/type-*.md"

# Example output:

# skills/diagram-design/references/type-architecture.md

# skills/diagram-design/references/type-flowchart.md

```

### 4. Build the SVG icon set used by many diagram types

```bash
python3 scripts/build-icons.py

# Populates: skills/diagram-design/assets/icons.html

```

These commands show the modular nature of the codebase — every script and asset resides in a predictable location, and the corresponding command or prompt definition points directly to it.

## Summary

- The **Diagram Design repository** is organized into plugin manifests, command definitions, prompt templates, a core skill package, and tooling scripts.
- The core skill lives in **`skills/diagram-design/`** with [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) as the entry point, `references/` for lazy-loaded docs, `scripts/` for Python parsers, and `assets/` for HTML templates.
- **`commands/`** and **`prompts/`** materialize the same cognitive functionality for different agents without duplicating code.
- Root-level **`scripts/`** contains CI-build and verification utilities, while **`docs/adr/`** and **`docs/screenshots/`** ground the project’s reasoning and visual docs.
- The layout supports progressive disclosure — an agent loads only the files needed per request, keeping runtime overhead minimal.

## Frequently Asked Questions

### Where is the main entry point of the Diagram Design repository?

The main entry point is [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). It routes user requests to the correct diagram type, documents the design system, and refers agents to lazy-loaded files in `skills/diagram-design/references/` when needed.

### What is the purpose of the `references/` directory?

The `references/` directory contains reusable markdown files that define the skill’s design vocabulary: style tokens, semantic patterns, animation contracts, and one file per diagram type. An agent loads only the specific reference file relevant to the request, keeping runtime tiny.

### How do the `commands/` and `prompts/` directories differ?

Both directories define the same operations, but `commands/` holds slash-command markdown files for interactive agents like Claude Code and Codex, while `prompts/` holds the prompt templates that Pi consumes for the same set of actions. They share the underlying skill logic.

**How do I add a new diagram type to this repository?**

To add a new type, create a `type-<name>.md` file in `skills/diagram-design/references/`, register it in the ecosystem, and add a corresponding command/prompt in the agent surfaces. Then run [`scripts/render-canonical-screenshots.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/render-canonical-screenshots.py) to refresh the gallery preview.