How Diagram Design Integrates with Factory Droid: Complete Plugin Architecture Guide

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 – Declares the plugin name, version, and skill routing metadata that Factory Droid reads during droid plugin marketplace add operations
• .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 – 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:

# Add the Diagram Design repository to Factory Droid's plugin marketplace

droid plugin marketplace add https://github.com/cathrynlavery/diagram-design

The 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:

# 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:

# 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 and relevant reference files from skills/diagram-design/references/ on demand.

Example Runtime Interactions

# 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, and returns a self-contained HTML file.

Profile and Configuration Access

Factory Droid accesses the same profile library used by other agents:

# 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 runs in CI to ensure:

• The Factory Droid README installation block matches the current 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 and 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 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 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 to validate that the Factory Droid README instructions, 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.

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