# Diagram-Design Repository Structure: Complete Guide to Files and Directories

> Explore the cathrynlavery/diagram-design repository structure. Understand its modular Agent Skill architecture with platform manifests, slash-command definitions, and a centralized skill core.

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

---

**The diagram-design repository follows a modular Agent Skill architecture separating platform manifests, slash-command definitions, and a centralized skill core containing templates, validators, and a 39-type visual gallery.**

The cathrynlavery/diagram-design repository is a self-contained Agent Skill installable across Claude Code, Codex, Factory Droid, and Pi. Understanding the diagram-design repository structure reveals how the project maintains strict separation between platform manifests, command logic, and reusable diagram assets while keeping the runtime footprint lightweight through lazy loading.

## Top-Level Directory Organization

The root directory organizes functionality into discrete domains. The `.agents/plugins/` directory serves as the marketplace catalog for Codex agents, while platform-specific manifests reside in `.claude-plugin/`, `.codex-plugin/`, and `.factory-plugin/`. These JSON or YAML files expose the skill's capabilities to each respective AI host.

The `commands/` directory contains Markdown files defining slash-commands such as `/export-diagram` and `/import-drawio`. Corresponding prompt templates live in `prompts/`, ensuring consistent agent behavior across platforms.

Documentation and automation utilities occupy `docs/`—which houses Architecture Decision Records (`adr/`) and visual assets (`screenshots/`)—and `scripts/`, containing CI gates and helper utilities.

## Core Skill Implementation (`skills/diagram-design/`)

The `skills/diagram-design/` directory contains the actual skill logic. This subdirectory represents the only portion loaded during active diagram generation, ensuring efficient resource usage and minimal context window consumption.

### Configuration and Entry Points

The [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file serves as the primary entry point, containing high-level descriptions, type-selection guides, and design-system specifications. This file directs agents toward appropriate diagram types based on user intent and contains the selection logic referenced by all platform manifests.

### Reference Documentation (`references/`)

The `references/` subdirectory stores lazily-loaded documentation including [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) (the single source of truth for colors, fonts, and branding), [`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), and individual type specifications. Agents access these files only when generating specific diagram variants, keeping the active context lean.

### Asset Library and Templates (`assets/`)

The `assets/` folder contains [`index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/index.html), an interactive HTML gallery displaying all 39 supported diagram types. It also houses scaffolding templates (`template*.html`) and example diagrams for every visual category, enabling rapid diagram prototyping and visual regression testing.

### Skill-Specific Scripts (`skills/diagram-design/scripts/`)

This nested scripts directory contains Python extractors such as [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) and [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for importing external formats. The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script provides runtime validation that users can invoke on generated diagrams to verify geometric integrity and semantic correctness before export.

## CI Automation and Utility Scripts (`scripts/`)

The root-level `scripts/` directory powers continuous integration and maintenance workflows. Key utilities include:

- [`bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/bump-plugin-version.py): Synchronizes version numbers across all platform manifests
- [`render-canonical-screenshots.py`](https://github.com/cathrynlavery/diagram-design/blob/main/render-canonical-screenshots.py): Generates the 39-type PNG catalog used in documentation
- [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) and [`verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-sankey.py): CI gates enforcing geometric precision, semantic validity, and accessibility compliance
- [`lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-render.py): Headless Chromium renderer for automated visual regression testing and screenshot generation

## Practical Usage Examples

Explore the repository structure through common workflows:

```bash

# Launch the visual gallery to browse all 39 diagram types

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

# Validate an existing diagram using the self-check script

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

```

Agents interact with the structure through standardized slash commands defined in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) and sister files:

```bash

# Export a diagram to various formats

/diagram-design:export-diagram path/to/diagram.html

# Import from Mermaid or Draw.io sources

/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-drawio my-architecture.drawio

```

## Summary

- The **diagram-design repository structure** separates platform manifests (`.claude-plugin/`, `.codex-plugin/`, `.factory-plugin/`) from core logic to enable multi-platform deployment without code duplication
- **Slash commands** reside in `commands/` while **prompt templates** live in `prompts/`, creating a clear separation between user interface definitions and agent instructions
- The **`skills/diagram-design/`** directory contains the lightweight runtime core, including [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), reference docs, templates, and format extractors
- **CI validation scripts** in the root `scripts/` directory enforce quality gates for geometry, semantics, and accessibility across all 39 diagram types
- **[`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html)** provides an interactive gallery for exploring the complete diagram type catalog without installing external tools

## Frequently Asked Questions

### What is the purpose of the `skills/diagram-design/` directory?

The `skills/diagram-design/` directory contains the core runtime logic of the Agent Skill. It houses [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) for configuration, `references/` for documentation including [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), `assets/` for templates and the HTML gallery, and skill-specific scripts like [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py). This modular design ensures that only necessary files load during diagram generation, keeping the agent context window efficient.

### How do the plugin manifests work across different AI platforms?

Platform-specific directories—`.claude-plugin/`, `.codex-plugin/`, and `.factory-plugin/`—contain manifest files that declare the skill's capabilities to each respective host. The `commands/` directory defines standardized slash-commands that work identically across Claude Code, Codex, Factory Droid, and Pi, while `prompts/` provides the underlying templates that adapt to each platform's specific requirements and context window constraints.

### Where are diagram validation and quality checks implemented?

Quality assurance scripts reside in the root `scripts/` directory. Files like [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) enforce label placement and clipping rules, [`verify-sankey.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-sankey.py) validates flow diagram semantics, and [`lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-render.py) performs headless browser rendering for visual regression testing. Additionally, [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) offers runtime validation that end users can execute on generated diagrams to catch errors before final export.

### How can I browse the available diagram types in the repository?

The repository includes a complete visual catalog at [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html). This HTML gallery displays all 39 supported diagram variants with live examples and scaffolding templates. Open this file in any browser to explore available types, or reference `docs/adr/` for Architecture Decision Records explaining the design rationale behind specific diagram implementations.