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

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 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 (the single source of truth for colors, fonts, and branding), semantic-patterns.md, 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, 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 and mermaid_extract.py for importing external formats. The 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: Synchronizes version numbers across all platform manifests
• render-canonical-screenshots.py: Generates the 39-type PNG catalog used in documentation
• verify-geometry.py and verify-sankey.py: CI gates enforcing geometric precision, semantic validity, and accessibility compliance
• lint-render.py: Headless Chromium renderer for automated visual regression testing and screenshot generation

Practical Usage Examples

Explore the repository structure through common workflows:

# 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 and sister files:

# 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, 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 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 for configuration, references/ for documentation including style-guide.md, assets/ for templates and the HTML gallery, and skill-specific scripts like 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 enforce label placement and clipping rules, verify-sankey.py validates flow diagram semantics, and lint-render.py performs headless browser rendering for visual regression testing. Additionally, 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. 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.

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