# Diagram-Design Skill Loading Process Architecture: A Complete Guide

> Explore the diagram-design skill loading process architecture. Learn about the three-phase pipeline for efficient skill loading without hard-coded paths.

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

---

**The diagram-design skill uses a three-phase, convention-driven pipeline—manifest discovery, skill enumeration, and asset loading—that lets Claude and Codex hosts load skills without hard-coded paths or runtime configuration.**

This article explains how the `cathrynlavery/diagram-design` repository implements a declarative, file-system-based architecture for skill discovery and loading. Understanding this architecture helps developers extend the skill with new diagram types, debug loading issues, or build compatible skill systems.

## Three-Phase Skill Loading Architecture

The skill loading process follows a deterministic pipeline that separates configuration from code. Each phase has a distinct responsibility and operates on specific files within the repository.

### Phase 1: Manifest Discovery

The host begins by reading the plugin's **manifest file** at [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json). This JSON file declares where skill definitions live through the `"skills"` key.

```json
{
  "name": "diagram-design",
  "skills": "./skills/",
  "version": "1.0.0",
  "description": "Diagram design and visualization tools"
}

```

The manifest uses a **relative path** (`./skills/`) that the host resolves against the repository root. The same manifest structure appears in [`.claude-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json) for cross-platform compatibility.

### Phase 2: Skill Enumeration

Once the host locates the skills directory, it performs a **directory scan** to find valid skill modules. A folder qualifies as a skill if and only if it contains a [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file at its root.

In the diagram-design repository, this yields a single skill:

- [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) — the skill's metadata and capability declaration

The host parses [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) to extract:
- Display name
- Capabilities and default prompts
- Version and author information

### Phase 3: Asset and Reference Loading

After identifying a valid skill folder, the host aggregates **auxiliary resources** from three subdirectories:

| Directory | Content Type | Example Files |
|-----------|-------------|---------------|
| `references/*.md` | Markdown documentation describing diagram types, style guides, and output formats | [`mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid.md), [`drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio.md), [`output_formats.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output_formats.md) |
| `assets/*.html` | Ready-made HTML snippets for direct serving | [`example-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-flowchart.html), [`template-sequence.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-sequence.html) |
| `scripts/*.py` | Helper utilities for diagram processing | [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py), [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) |

These resources are **bundled into an in-memory skill object** that the platform exposes through its UI and API.

## Complete Loading Flow Implementation

The following pseudo-code illustrates the exact sequence the host follows, mirroring the production implementation:

```python
import json
import os
from pathlib import Path

def load_plugin(root):
    # Phase 1: Manifest discovery

    manifest_path = Path(root) / ".codex-plugin" / "plugin.json"
    with open(manifest_path) as f:
        manifest = json.load(f)

    skill_dir = Path(root) / manifest["skills"]
    loaded_skills = []

    # Phase 2: Skill enumeration

    for skill_path in skill_dir.iterdir():
        skill_md = skill_path / "SKILL.md"
        if not skill_md.exists():
            continue  # Skip non-skill directories

        # Parse skill metadata

        meta = parse_skill_md(skill_md)

        # Phase 3: Asset and reference loading

        meta["assets"] = list((skill_path / "assets").glob("*.html"))
        meta["references"] = list((skill_path / "references").glob("*.md"))
        meta["scripts"] = list((skill_path / "scripts").glob("*.py"))

        loaded_skills.append(meta)

    return loaded_skills

# Example usage

skills = load_plugin("/path/to/diagram-design")
print(f"Loaded {len(skills)} skill(s): {[s['displayName'] for s in skills]}")

```

The production host follows this same logical flow, with additional error handling and caching optimizations.

## Key Architectural Benefits

The diagram-design skill loading architecture provides several advantages for maintainability and extensibility:

**No code changes required for extensions.** Adding a new diagram type means creating [`references/new-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/new-diagram.md) and optionally [`assets/new-diagram.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/new-diagram.html)—the host discovers these automatically on next load.

**Cross-platform compatibility.** Identical manifests in [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json) ensure the skill works with multiple AI coding platforms without modification.

**Deterministic debugging.** The file-system-based approach makes loading failures easy to diagnose: missing [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), malformed JSON, or absent directories surface as clear, location-specific errors.

**Clean separation of concerns.** The manifest handles configuration, [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) declares capabilities, and subdirectories organize implementation resources—no single file accumulates excessive responsibility.

## Critical Source Files

| File Path | Purpose |
|-----------|---------|
| [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) | Primary manifest declaring the skills directory |
| [`.claude-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json) | Claude-platform equivalent manifest |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Skill metadata and capability declaration |
| `skills/diagram-design/references/` | Markdown documentation for diagram types |
| `skills/diagram-design/assets/` | HTML templates and examples |
| `skills/diagram-design/scripts/` | Python utilities for diagram extraction |

## Summary

- The **diagram-design skill loading process** uses a three-phase pipeline: manifest discovery, skill enumeration, and asset aggregation.
- The host reads [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) to locate skills, then scans `./skills/` for folders containing [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).
- Each skill bundles `references/` (documentation), `assets/` (HTML examples), and `scripts/` (Python helpers) into a platform-ready object.
- This **convention-driven architecture** eliminates hard-coded paths and enables skill extensions through simple file additions.

## Frequently Asked Questions

### What file triggers the host to recognize a folder as a valid skill?

The presence of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) in a directory beneath the configured skills path. The host ignores folders without this file, making [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) the mandatory marker for skill modules.

### Can the same skill load on both Claude and Codex platforms?

Yes. The repository maintains **identical manifests** in [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json). Both platforms use the same directory structure and loading logic, so the skill works interchangeably.

### How do I add a new diagram type without modifying code?

Create a new Markdown file in `skills/diagram-design/references/` describing the diagram type, and optionally add an HTML example to `skills/diagram-design/assets/`. The host discovers these files automatically on next startup—no manifest edits or code changes required.

### Where does the host look for helper scripts that process diagrams?

The host collects all `*.py` files from `skills/diagram-design/scripts/`. Current utilities include [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for Mermaid diagram parsing and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) for Draw.io format handling.