# How Diagram Design Integrates with Factory Droid: Complete Plugin Architecture Guide > Explore how Diagram Design integrates with Factory Droid as a native plugin using Agent Skills. Discover zero-configuration installation and execution of 39 diagram types. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: architecture - Published: 2026-08-23 --- **Diagram Design integrates with Factory Droid as a native plugin through the Agent Skills contract, enabling zero-configuration discovery, installation, and execution of all 39 diagram types via shared skill files and Git-based marketplace versioning.** The `cathrynlavery/diagram-design` repository implements a dual-manifest architecture that allows Factory Droid to consume the same skill code base used by Claude Code, Codex, and Pi. This integration eliminates duplicated logic while providing Factory Droid-specific marketplace metadata and CLI-driven lifecycle management. ## Plugin Manifest and Marketplace Structure Factory Droid discovers Diagram Design through a dedicated plugin manifest that declares the skill's capabilities and entry points. Unlike other agents that rely on display versioning, Factory Droid tracks integration state via commit SHA for deterministic reproducibility. ### Core Manifest Files The `.factory-plugin/` directory contains the metadata required for Droid's Git-based marketplace: - **[`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json)** – Declares the plugin name, version, and skill routing metadata that Factory Droid reads during `droid plugin marketplace add` operations - **[`.factory-plugin/marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/marketplace.json)** – Provides marketplace-specific metadata that mirrors the structure used by Claude Code's manifest, ensuring consistency across agents These files enable Factory Droid to register the `diagram-design` skill namespace without custom adapter code, allowing immediate access to the visual type library upon installation. ## Shared Skill Files and Single Source of Truth All diagram generation logic resides in `skills/diagram-design/`, serving as the single source of truth across the entire Agent Skills ecosystem. Factory Droid loads the same files as Claude Code, Codex, and Pi, including: - **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** – High-level routing guide and capability description loaded at runtime - **`skills/diagram-design/references/`** – Type-specific semantic patterns, animation references, and style tokens for all 39 supported visual types - **`commands/*.md`** – Slash command definitions for `/export-diagram`, `/import-mermaid`, and other CLI-style interactions This shared architecture ensures that updates to diagram logic, new visual types, or prompt template improvements propagate simultaneously to Factory Droid without requiring separate maintenance tracks. ## Installation and Discovery Workflow Factory Droid integrates Diagram Design through a four-phase lifecycle that leverages Git-native versioning rather than package managers. ### 1. Marketplace Registration Factory Droid scans the repository's `.factory-plugin/` directory when adding the Git URL to its marketplace index: ```bash # Add the Diagram Design repository to Factory Droid's plugin marketplace droid plugin marketplace add https://github.com/cathrynlavery/diagram-design ``` The [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) file tells Droid that this repository provides the `diagram-design` skill and specifies the entry point under `skills/diagram-design/`. ### 2. User-Scoped Installation Once registered, install the plugin for the current user scope: ```bash # Install the diagram-design skill for the current user droid plugin install diagram-design@diagram-design --scope user ``` This command copies the skill files into Droid's plugin store, making all 39 visual types available immediately. ### 3. Commit-Based Updates Factory Droid tracks plugin state by Git commit SHA rather than semantic version strings. After upstream changes merge to the main branch, update through the marketplace: ```bash # Update marketplace index to latest commit droid plugin marketplace update diagram-design # Pull the newest commit into local installation droid plugin update diagram-design@diagram-design --scope user ``` This approach guarantees that `droid plugin update` retrieves exactly the code state represented by the repository's commit history. ## Runtime Command Execution Once installed, Factory Droid resolves natural language requests to Diagram Design commands using the shared skill definitions. The runtime loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and relevant reference files from `skills/diagram-design/references/` on demand. ### Example Runtime Interactions ```text # Generate an architecture diagram using the shared type definitions > make me an architecture diagram of my app: frontend, backend, database, Redis cache ``` Factory Droid resolves this to the `diagram-design` skill, loads [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md), and returns a self-contained HTML file. ### Profile and Configuration Access Factory Droid accesses the same profile library used by other agents: ```text # Load a stored client profile (shared with Claude Code and Pi) > /profile acme-client ``` This reads `~/.diagram-design/profiles/acme-client.md` and applies stored style tokens, ensuring visual consistency across different AI agents working on the same project. ## CI Validation and Consistency Enforcement The repository maintains synchronization between Factory Droid-specific documentation and the actual skill implementation through automated validation. **[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)** runs in CI to ensure: - The Factory Droid README installation block matches the current [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) structure - The marketplace manifest aligns with the skill directory layout - Command definitions in `commands/*.md` are consistent across all agent manifests This prevents drift between the Git-based marketplace metadata and the functional skill code, ensuring that Factory Droid installations always receive valid, synchronized plugin structures. ## Summary - **Dual-manifest architecture**: Factory Droid uses [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json) and [`marketplace.json`](https://github.com/cathrynlavery/diagram-design/blob/main/marketplace.json) for discovery while sharing the actual skill code under `skills/diagram-design/` with Claude Code, Codex, and Pi - **Git-native versioning**: Unlike display-version agents, Factory Droid tracks Diagram Design by commit SHA, requiring `droid plugin marketplace update` followed by `droid plugin update` to sync changes - **Zero-configuration runtime**: All 39 diagram types, slash commands, and profile management features work immediately after installation without custom wiring - **CI-guarded consistency**: [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) validates that Factory Droid integration files stay synchronized with the shared skill source ## Frequently Asked Questions ### How does Factory Droid discover the Diagram Design plugin? Factory Droid scans the `.factory-plugin/` directory when executing `droid plugin marketplace add`. The [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) file declares the skill name and entry point, allowing Droid to register the plugin namespace without manual configuration or custom adapter code. ### Why does Factory Droid use commit SHA instead of version numbers? Factory Droid's Git-based marketplace tracks the exact commit SHA rather than semantic versions. This provides deterministic reproducibility—`droid plugin update` retrieves the specific code state from the repository history, ensuring that installations across different environments reference identical skill logic. ### Can I use Diagram Design profiles created in Claude Code with Factory Droid? Yes. Both agents read from the same `~/.diagram-design/profiles/` directory. When you invoke `/profile profile-name` in Factory Droid, it loads the identical markdown profile files used by Claude Code, Codex, and Pi, maintaining style consistency across your entire toolchain. ### What happens if the skill files and Factory Droid manifest become out of sync? The CI pipeline runs [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) to validate that the Factory Droid README instructions, [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json) structure, and `skills/diagram-design/` directory layout remain consistent. If discrepancies exist, the build fails, preventing publication of mismatched marketplace metadata that could break installations.