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

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, located at 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 and type-flowchart.md. It also includes shared documentation like semantic-patterns.md, animation.md, and style-guide.md that define layout grammar and connector constraints.

Templates and Assets

HTML templates reside in assets/, including template.html, template-full.html, and 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 and drawio_extract.py for parsing source diagrams into normalized JSON digests. The 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 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.

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 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 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:

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 and throughout the verification suite.

Running Extractor Scripts

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

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 to normalize Mermaid sources into digest format.

Self-Check Validation

Before final output, the system runs internal validation:

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, 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	Central manifest defining version, description, and loading rules
references/type-*.md	Layout grammar and constraints for each visual type
references/semantic-patterns.md	Behavior-first selection patterns
references/animation.md	Motion specifications (reveal, step, loop)
assets/template.html	Base HTML template for SVG injection
scripts/mermaid_extract.py	Mermaid source parser and normalizer
scripts/drawio_extract.py	draw.io file parser and normalizer
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 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 or 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 and 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 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 manifest before the self-contained HTML file is returned.

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