How Diagram Design Integrates with Claude Code and Other Agent Skills

Diagram Design is built as a universal Agent Skill that Claude Code, Codex, Pi, and Factory Droid consume through synchronized marketplace manifests and a single source of truth in skills/diagram-design/, eliminating code duplication while providing consistent slash commands across all hosts.

The cathrynlavery/diagram-design repository demonstrates how Diagram Design integrates with Claude Code and other agent skills by exposing a standardized skill directory that multiple AI hosts consume without maintaining separate copies. This architecture ensures that Claude Code, Codex, Pi, and Factory Droid all access the same semantic patterns, rendering logic, and profile configurations through a unified API.

Single Source of Truth Architecture

All skill code resides exclusively under skills/diagram-design/, serving as the single source of truth for every supported host. Rather than duplicating logic across multiple repositories, Claude Code, Codex, Pi, and Factory Droid each point to this shared directory.

According to the architectural decision record ADR 0008 – native host manifests share one plugin root, this design eliminates merge conflicts and version drift by ensuring that bug fixes and feature updates propagate instantly to all consumers. The Python entry points in skills/diagram-design/scripts/*.py handle diagram parsing and rendering through a host-agnostic core, while tiny host-specific wrappers translate slash commands into function calls.

Synchronized Marketplace Manifests

The repository maintains three synchronized manifest files that keep version numbers in lock-step across marketplaces:

• .claude-plugin/plugin.json for Claude Code
• .codex-plugin/plugin.json for Codex
• .factory-plugin/plugin.json for Factory Droid

The scripts/bump-plugin-version.py utility increments all three manifest versions simultaneously, while scripts/verify-plugin-package.py validates synchronization on every push. This verification script runs as a gate in CI to ensure that no host receives an out-of-date plugin definition.

As documented in ADR 0009, the .github/workflows/auto-bump.yml workflow automatically triggers scripts/bump-plugin-version.py after each merge, guaranteeing that every marketplace sees identical version numbers without manual intervention.

Installation Paths and Host Discovery

Each host discovers the skill through standardized installation paths that point to the shared skills/diagram-design/ directory.

Claude Code supports two installation methods:

1. Marketplace installation: Installs to ~/.claude/skills/ via /plugin install diagram-design
2. Development symlink: Links directly to the inner skill directory for local development, documented in the README Claude Code section

Codex, Pi, and Factory Droid automatically discover the skill through their standard skills/ package directories, reading the same physical folder that Claude Code uses. This ensures that /diagram-design:import-mermaid behaves identically regardless of which agent executes the command.

# Installing via Claude Code Marketplace

/plugin install diagram-design
/plugin enable-auto-update diagram-design

# Using in Pi or Factory Droid (same command syntax)

/diagram-design:import-mermaid diagram.mmd

Unified Slash Command API

The skill exposes a consistent command surface across all hosts through the prefix /diagram-design:. These commands are documented in the Cookbook and include:

• /diagram-design:import-drawio <file> – Redraw a draw.io diagram
• /diagram-design:import-mermaid <file-or-md> – Redraw a Mermaid diagram
• /diagram-design:import-excalidraw <file> – Redraw an Excalidraw diagram

When a host receives one of these commands, the skill's Python entry point parses the source file, applies the selected semantic pattern, chooses a visual type, and renders a self-contained HTML or SVG diagram using templates from assets/template.html.

# Host-agnostic invocation (Claude Code translation layer calls this)

from diagram_design import cli

cli.run_command(
    command="import-drawio",
    args=["my-diagram.drawio"],
    profile="default",
    size="doc-inline",
    detail="balanced"
)

Shared Profile Library and Runtime Behavior

All hosts read from and write to the same profile store located at skills/diagram-design/references/profiles.md. This shared library guarantees consistent branding across agents, allowing users to invoke profile commands in any host (/diagram-design:profile in Claude Code or /profile in Pi) while manipulating identical JSON files.

The runtime behavior remains host-agnostic: the skill reads the profile configuration, applies visual styling, and outputs renderable assets without distinguishing between Claude Code, Codex, or other agents.

# Accessing shared profiles from any host environment

from diagram_design.profile import load_profile, save_profile

profile = load_profile("my-company")
profile["accent"] = "#ff6600"
save_profile("my-company", profile)

Key Integration Files

The following files illustrate how Diagram Design integrates with Claude Code and other agent skills:

• skills/diagram-design/SKILL.md – Core skill definition and entry points
• README.md – Claude Code installation strategies and symlink configuration
• docs/cookbook.md – Complete reference for slash commands (/diagram-design:import-*)
• docs/adr/0008-native-host-manifests-share-one-plugin-root.md – Architectural decision specifying the shared plugin root
• scripts/verify-plugin-package.py – Validates that the three manifests stay synchronized
• scripts/bump-plugin-version.py – Automates version bumping across all host marketplaces
• .github/workflows/auto-bump.yml – CI workflow ensuring post-merge version consistency per ADR 0009
• skills/diagram-design/references/profiles.md – Cross-host profile storage used for consistent branding

Summary

• Single source of truth: All code lives in skills/diagram-design/, consumed by Claude Code, Codex, Pi, and Factory Droid without duplication.
• Synchronized manifests: Three marketplace JSON files stay in lock-step via scripts/bump-plugin-version.py and scripts/verify-plugin-package.py.
• Unified commands: The /diagram-design:* slash command API works identically across all hosts, with rendering logic in skills/diagram-design/scripts/*.py.
• Shared state: Profile configurations in skills/diagram-design/references/profiles.md ensure consistent branding across agents.
• Automated versioning: The .github/workflows/auto-bump.yml CI workflow prevents version drift by bumping all manifests simultaneously after every merge.

Frequently Asked Questions

How does Diagram Design prevent version conflicts between Claude Code and other agents?

The repository uses scripts/bump-plugin-version.py to increment version numbers across .claude-plugin/plugin.json, .codex-plugin/plugin.json, and .factory-plugin/plugin.json simultaneously. The scripts/verify-plugin-package.py script validates this synchronization on every push, while .github/workflows/auto-bump.yml automates version bumps after merges, ensuring all hosts receive identical updates through ADR 0009's specification.

Can I use the same diagram profiles across Claude Code, Pi, and Factory Droid?

Yes. All hosts read from the shared profile library at skills/diagram-design/references/profiles.md. When you invoke /diagram-design:profile in Claude Code or /profile in Pi, the skill accesses the same underlying JSON files, guaranteeing consistent visual branding regardless of which agent renders the diagram.

What is the difference between installing Diagram Design via marketplace versus symlink in Claude Code?

Marketplace installation copies the skill to ~/.claude/skills/ and supports auto-updates via /plugin enable-auto-update. The symlink method creates a symbolic link directly to skills/diagram-design/ within your local clone of the repository, intended for development workflows where you want immediate reflection of code changes without reinstalling.

How do the slash commands translate to actual Python execution?

Each host provides a thin wrapper that translates slash commands like /diagram-design:import-drawio into function calls to cli.run_command() from the diagram_design package. The wrapper passes parameters such as command name, file arguments, and profile settings to the host-agnostic Python scripts in skills/diagram-design/scripts/*.py, which handle the actual parsing and rendering logic.

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