Diagram-Design Skill Loading Process Architecture: A Complete Guide

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. This JSON file declares where skill definitions live through the "skills" key.

{
  "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 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 file at its root.

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

• skills/diagram-design/SKILL.md — the skill's metadata and capability declaration

The host parses 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, drawio.md, output_formats.md
assets/*.html	Ready-made HTML snippets for direct serving	example-flowchart.html, template-sequence.html
scripts/*.py	Helper utilities for diagram processing	mermaid_extract.py, drawio_extract.py, 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:

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 and optionally assets/new-diagram.html—the host discovers these automatically on next load.

Cross-platform compatibility. Identical manifests in .codex-plugin/plugin.json and .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, malformed JSON, or absent directories surface as clear, location-specific errors.

Clean separation of concerns. The manifest handles configuration, 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	Primary manifest declaring the skills directory
.claude-plugin/plugin.json	Claude-platform equivalent manifest
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 to locate skills, then scans ./skills/ for folders containing 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 in a directory beneath the configured skills path. The host ignores folders without this file, making 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 and .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 for Mermaid diagram parsing and drawio_extract.py for Draw.io format handling.

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