# Diagram-Design Skill Loading System Architecture: A File-Based Pipeline

> Explore the file-based skill loading system architecture for diagram-design. Discover how it efficiently loads resources and generates HTML diagrams with no external dependencies.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: architecture
- Published: 2026-08-15

---

**The diagram-design skill implements a deterministic, file-based skill loading system architecture that lazily reads only necessary resources—metadata, reference definitions, templates, and extractor scripts—from the `skills/diagram-design/` directory to generate self-contained HTML diagrams without external dependencies.**

The `cathrynlavery/diagram-design` repository organizes its skill loading system architecture around a self-contained directory structure that enables portability and deterministic execution. When invoked, the skill dynamically loads its manifest and selectively pulls reference files based on the specific visual type requested, ensuring no external configuration or database connections are required. This lazy-loading approach keeps the skill lightweight while maintaining strict validation constraints throughout the rendering pipeline.

## Directory Structure and Component Organization

The skill loading system architecture relies on a predictable directory layout under `skills/diagram-design/`. Each subdirectory serves a specific purpose in the resource loading pipeline.

### Skill Metadata and Manifest

The central entry point is [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), located at [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). This file contains the skill name, version, description, and high-level usage rules including the "pre-output checklist" that governs final validation.

### Reference Library

The `references/` directory houses 27 visual-type definitions (`type-*.md`) such as [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md). It also includes shared documentation like [`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 [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) that define layout grammar and connector constraints.

### Templates and Assets

HTML templates reside in `assets/`, including [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html), [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-full.html), and [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html). These serve as the base containers into which generated SVG diagrams are injected.

### Extractor Scripts and Validation

The `scripts/` directory contains Python helpers like [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) for parsing source diagrams into normalized JSON digests. The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script performs internal validation, while `verify-*.py` utilities ensure CI integrity.

## The Loading Pipeline Execution Flow

The skill loading system architecture follows a 10-step deterministic pipeline that executes lazily—files are only read when specifically required by the current request.

1. **Read the skill manifest** – The system loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) to obtain version information and validation rules.

2. **Determine visual type** – User intent maps to a semantic pattern and specific visual type (e.g., Architecture, Flowchart).

3. **Load semantic patterns** – If required, the system reads [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md).

4. **Load visual-type reference** – The matching `type-<name>.md` file is loaded, supplying layout grammar and connector rules.

5. **Load animation specifications** – For motion requests, [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) is read.

6. **Select HTML template** – One of the templates from `assets/` is chosen based on output requirements.

7. **Execute extractor (if importing)** – For Mermaid (`.mmd`) or draw.io (`.drawio`) sources, the corresponding extractor script produces a normalized digest describing nodes, edges, and containers.

8. **Render SVG** – Using the digest and reference rules, the system builds an inline SVG with ARIA attributes and rounded-right-angle connectors.

9. **Run self-check** – [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) validates connector rules, label gaps, accessibility, and size limits.

10. **Return HTML** – The SVG is injected into the selected template and returned as a self-contained `.html` file.

## Implementation Details and Code Examples

The following Python implementations demonstrate how the skill loading system architecture handles resource acquisition and processing.

### Loading Visual Type References

When the system needs to load a specific visual type definition, it constructs the path dynamically:

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).parents[2]                     # …/skills/diagram-design

REFS_ROOT = SKILL_ROOT / "references"

def load_type_reference(vtype: str) -> str:
    """Read the markdown that defines the chosen visual type."""
    ref_path = REFS_ROOT / f"type-{vtype}.md"
    if not ref_path.is_file():
        raise FileNotFoundError(f"Reference for type {vtype!r} missing")
    return ref_path.read_text(encoding="utf-8")

```

This pattern appears in [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) and throughout the verification suite.

### Running Extractor Scripts

For importing external diagram formats, the system invokes extractor scripts as subprocesses:

```python
import subprocess
import json
from pathlib import Path

def run_mermaid_extractor(source_path: Path) -> dict:
    """Execute mermaid_extract.py and return the parsed JSON digest."""
    cmd = ["python3", str(SKILL_ROOT / "scripts" / "mermaid_extract.py"),
           "--json", str(source_path)]
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return json.loads(result.stdout)

```

This implementation is utilized in [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) to normalize Mermaid sources into digest format.

### Self-Check Validation

Before final output, the system runs internal validation:

```python
def self_check(html_path: Path) -> None:
    """Run the skill's internal sanity-check on a generated diagram."""
    cmd = ["python3", str(SKILL_ROOT / "scripts" / "self_check.py"),
           str(html_path)]
    subprocess.run(cmd, check=True)

```

This validation step, defined in [`scripts/test-self-check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-self-check.py), ensures the generated diagram obeys all mandatory constraints including connector rules and accessibility requirements.

## Key Files in the Skill Loading System

| File | Role in the Architecture |
|------|-------------------------|
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | Central manifest defining version, description, and loading rules |
| `references/type-*.md` | Layout grammar and constraints for each visual type |
| [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) | Behavior-first selection patterns |
| [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) | Motion specifications (reveal, step, loop) |
| [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html) | Base HTML template for SVG injection |
| [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) | Mermaid source parser and normalizer |
| [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) | draw.io file parser and normalizer |
| [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) | Internal validation and constraint checking |
| `scripts/verify-*.py` | CI utilities ensuring loading pipeline integrity |

## Summary

- The diagram-design skill loading system architecture uses a **file-based, lazy loading approach** that reads resources from `skills/diagram-design/` only when needed.
- The pipeline follows a **10-step deterministic flow** from manifest reading through SVG rendering to final HTML output.
- **Visual type definitions** in `references/type-*.md` files provide layout grammar and connector constraints specific to each diagram type.
- **Extractor scripts** normalize external formats (Mermaid, draw.io) into JSON digests that the rendering engine processes uniformly.
- The **self-check validation** in [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) ensures all output meets accessibility, size, and connector rule requirements before delivery.

## Frequently Asked Questions

### What makes the diagram-design skill loading system architecture self-contained?

The architecture keeps all dependencies within the `skills/diagram-design/` directory. It reads local markdown files for configuration, uses local Python scripts for extraction and validation, and requires no external databases or API calls to function. This allows the skill to be shipped, installed, or executed from any location on the filesystem.

### How does the skill determine which reference files to load?

The skill maps user intent to a specific visual type (e.g., Architecture, Flowchart) and then constructs the filename `type-<name>.md` to load the appropriate reference from the `references/` directory. It only loads [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) or [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) if the request specifically requires semantic patterns or motion specifications.

### Can the skill loading system architecture handle external diagram formats?

Yes. The system includes extractor scripts ([`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)) that parse external formats into a normalized JSON digest. This digest describes nodes, edges, containers, and budget flags, allowing the rendering engine to process diverse input sources uniformly through the same pipeline.

### What validation occurs before the skill returns the final HTML?

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script executes a mandatory validation step that checks connector rules, label gaps, ARIA accessibility attributes, and size limits. This ensures the generated diagram complies with the constraints defined in the loaded reference files and the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) manifest before the self-contained HTML file is returned.