How Diagram Design Integrates with Codex: Plugin Architecture and Installation Guide

Diagram Design integrates with Codex as a standardized plugin using a JSON manifest at .codex-plugin/plugin.json, a marketplace entry in .agents/plugins/marketplace.json, and a shared skill directory at skills/diagram-design/ that provides consistent cross-platform functionality.

Diagram Design by Cathryn Lavery is distributed as a Codex plugin that follows the Agent Skills convention, enabling users to generate architecture diagrams and flowcharts through natural language requests. The integration relies on a declarative manifest system and shared source files that ensure identical behavior across Claude, Codex, and Factory hosts. According to the cathrynlavery/diagram-design source code, the architecture separates host-specific configuration from reusable skill logic.

Plugin Manifest and Registration

Codex discovers Diagram Design through a two-tier registration system combining a local plugin manifest with a global marketplace entry.

The .codex-plugin/plugin.json Configuration

The file .codex-plugin/plugin.json resides at the repository root and serves as the primary descriptor read by Codex at startup. This JSON structure defines the plugin name, version, author, keywords, and the location of the skill source. By declaring the relative path "./skills/", the manifest directs Codex to resolve skill implementations from the shared directory when loading the plugin.

Marketplace Catalog Entry in .agents/plugins/marketplace.json

The marketplace registration lives at .agents/plugins/marketplace.json, which registers the plugin under the identifier diagram-design. The entry points the source.path field to the repository root ("./") and declares the required policy with installation: AVAILABLE and authentication: ON_INSTALL. The category is set to Productivity, classifying the plugin's utility for workflow visualization tasks.

Shared Skill Architecture

Diagram Design eliminates code duplication by using a single physical skill folder referenced by all host manifests.

Cross-Platform Skill Directory

All host-specific manifests (Claude, Codex, and Factory) reference the same directory at skills/diagram-design/. When Codex loads the plugin, it resolves the skills field from the manifest and reads the skill definition (SKILL.md) and command files from the commands/ subdirectory. This guarantees that every host sees identical behavior regardless of the AI platform executing the request.

Version Synchronization and Validation

To prevent drift between platforms, the repository includes automated safeguards that enforce manifest consistency.

The Python script scripts/verify-plugin-package.py validates that the Codex manifest, Claude manifest, and Factory manifest remain in lock-step with identical name, description, and version fields. It also verifies that the marketplace entry points to the correct root and that the packaged skill is present. This guardrail ensures Codex users experience smooth upgrades without configuration mismatches.

Installation and Runtime Workflow

Installing Diagram Design requires two explicit CLI commands, after which the skill becomes available in any Codex chat session.

CLI Installation Commands

To make Diagram Design available, users execute the following sequence:

# Add the repository to Codex's list of Git marketplaces

codex plugin marketplace add cathrynlavery/diagram-design

# Install the plugin from that marketplace

codex plugin add diagram-design@diagram-design

Codex automatically refreshes its marketplace list at startup. For immediate availability without restarting, force a refresh:

codex plugin marketplace upgrade diagram-design

Natural Language and Command Execution

After installation, Codex resolves the /diagram-design skill and loads assets from skills/diagram-design/. Users can invoke the skill with natural-language requests (e.g., "Make an architecture diagram of my app") or explicit command prefixes:

/diagram-design:import-drawio architecture.drawio --detail=faithful --format=png
/diagram-design:import-mermaid
/export-diagram --type=quadrant --size=slide-16x9 --detail=balanced

The skill returns self-contained HTML, SVG, or PNG payloads, optionally enriched with accessible motion or brand-matching style tokens.

Summary

• Declarative Registration: Codex discovers Diagram Design via .codex-plugin/plugin.json and registers it through .agents/plugins/marketplace.json under the Productivity category with installation: AVAILABLE policy.
• Shared Implementation: The skills/diagram-design/ directory provides identical functionality across Claude, Codex, and Factory hosts, eliminating code duplication.
• Quality Assurance: scripts/verify-plugin-package.py enforces version synchronization across all platform manifests to prevent behavioral drift.
• Simple Installation: Users run codex plugin marketplace add followed by codex plugin add to enable the skill in their environment.
• Flexible Invocation: Diagram Design responds to both natural language and explicit slash commands like /diagram-design:import-drawio and /export-diagram.

Frequently Asked Questions

How do I install Diagram Design in Codex?

Run the two-step command sequence: first codex plugin marketplace add cathrynlavery/diagram-design to register the repository, then codex plugin add diagram-design@diagram-design to install the plugin. The @diagram-design suffix pins the installation to the correct repository tag. After installation, the plugin appears in Codex automatically upon the next startup, or immediately after running codex plugin marketplace upgrade diagram-design.

What files control the Diagram Design plugin behavior?

The .codex-plugin/plugin.json file defines metadata and skill location, while .agents/plugins/marketplace.json controls marketplace visibility, categorization as Productivity, and installation policies (installation: AVAILABLE, authentication: ON_INSTALL). The actual skill logic resides in skills/diagram-design/SKILL.md and the commands/ subdirectory.

How does Diagram Design maintain consistency across AI platforms?

All host manifests (Claude, Codex, Factory) reference the same physical skill folder at skills/diagram-design/. The scripts/verify-plugin-package.py validation script ensures that name, version, and description fields remain synchronized across every platform's manifest. This shared architecture guarantees that a diagram generated in Codex behaves identically when rendered through Claude or Factory.

What commands are available after installing Diagram Design?

Available commands include /diagram-design:import-drawio for importing draw.io files, /diagram-design:import-mermaid for Mermaid syntax diagrams, and /export-diagram for generating final outputs. Users can also invoke these capabilities through natural language requests without memorizing specific command syntax.

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