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

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
.claude-plugin/	Claude marketplace manifest	plugin.json
.codex-plugin/	Codex marketplace manifest	plugin.json
.factory-plugin/	Factory Droid marketplace manifest	plugin.json
commands/	Slash-command definitions for each agent	export-diagram.md, import-drawio.md, import-mermaid.md, profile.md, doctor.md
prompts/	Prompt-template files for Pi and other agents	export-diagram.md, import-mermaid.md, profile.md, doctor.md
skills/diagram-design/	The core skill package	SKILL.md, subfolders
scripts/	Build and CI verification tools	bump-plugin-version.py, verify-geometry.py, lint-render.py
docs/adr/	Architecture Decision Records	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 — The Entry Point

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 — the single source of truth for colors, fonts, and token names
• semantic-patterns.md — seven behavior-rich patterns that combine with any visual type
• animation.md — the contract for optional motion and accessibility requirements
• type-architecture.md, type-flowchart.md, etc. — one reference file per diagram type

An agent handling a flowchart request only pulls SKILL.md and references/type-flowchart.md. Adding animation pulls 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 — parses Draw.io files into the internal representation
• mermaid_extract.py — parses Mermaid source blocks into the internal representation
• 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 — the live gallery that links to every generated diagram type
• 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, import-drawio.md, import-mermaid.md, profile.md, 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 — tracks plugin versioning
• render-canonical-screenshots.py — generates the 39-type PNG catalog for the README gallery
• verify-geometry.py — CI gate that checks label placement for geometric correctness
• 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)
• 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

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

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

# Expected output: "OK"

3. List all downloadable diagram-type reference files

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

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 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. 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 to refresh the gallery preview.

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