# How Diagram Design Integrates with Claude Code and Other Agent Skills

> Discover how Diagram Design integrates seamlessly with Claude Code and other agent skills via synchronized manifests. Learn how it eliminates code duplication and provides consistent commands across platforms.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-10

---

**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](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0008-native-host-manifests-share-one-plugin-root.md), 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`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json) for Claude Code
- [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json) for Codex
- [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json) for Factory Droid

The [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) utility increments all three manifest versions simultaneously, while [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/auto-bump.yml) workflow automatically triggers [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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](https://github.com/cathrynlavery/diagram-design/blob/main/README.md#L177)

**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.

```bash

# 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](https://github.com/cathrynlavery/diagram-design/blob/main/docs/cookbook.md#L199) 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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html).

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) – Core skill definition and entry points
- [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) – Claude Code installation strategies and symlink configuration
- [`docs/cookbook.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/cookbook.md) – Complete reference for slash commands (`/diagram-design:import-*`)
- [`docs/adr/0008-native-host-manifests-share-one-plugin-root.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0008-native-host-manifests-share-one-plugin-root.md) – Architectural decision specifying the shared plugin root
- [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py) – Validates that the three manifests stay synchronized
- [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) – Automates version bumping across all host marketplaces
- [`.github/workflows/auto-bump.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/auto-bump.yml) – CI workflow ensuring post-merge version consistency per ADR 0009
- [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) and [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) ensure consistent branding across agents.
- **Automated versioning**: The [`.github/workflows/auto-bump.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) to increment version numbers across [`.claude-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.claude-plugin/plugin.json), [`.codex-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.codex-plugin/plugin.json), and [`.factory-plugin/plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.factory-plugin/plugin.json) simultaneously. The [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py) script validates this synchronization on every push, while [`.github/workflows/auto-bump.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.