# How Diagram Design Integrates with Codex: Plugin Architecture and Installation Guide > Learn how Diagram Design integrates with Codex as a standardized plugin. Discover its JSON manifest, marketplace entry, and shared skill directory for consistent functionality. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-08-23 --- **Diagram Design integrates with Codex as a standardized plugin using a JSON manifest at [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json), a marketplace entry in [`.agents/plugins/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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: ```bash # 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: ```bash 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: ```text /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`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) and registers it through [`.agents/plugins/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) file defines metadata and skill location, while [`.agents/plugins/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.