# How to Contribute to Diagram Design: A Complete Guide to Agent Skill Development

> Learn how to contribute to Diagram Design by passing validation gates, adding reference files, and bumping the plugin version. Follow this guide for a smooth pull request submission.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Contributing to Diagram Design requires passing eight validation gates, adding type-specific reference files under `skills/diagram-design/references/`, and bumping the plugin version via [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) before submitting your pull request.**

Diagram Design is an **agent skill** that enables Claude Code, Codex, Factory Droid, and Pi to generate editorial-quality diagrams as self-contained HTML files. Learning how to contribute to Diagram Design means following its documentation-first architecture and rigorous validation pipeline. This guide walks through the repository structure, contribution workflow, and quality gates that protect downstream agents from breaking changes.

## Diagram Design Repository Architecture

The Diagram Design skill follows a modular, lazy-loading architecture centered in the `skills/diagram-design/` package.

### Core Entry Point and Routing

The skill's entry point is [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), which routes incoming requests to the appropriate diagram type reference. It loads semantic-pattern and animation modules only when needed—no unnecessary code executes for simple diagram requests.

### Diagram Type References

Each of the **38 visual types** has its own reference file under `skills/diagram-design/references/`. Files like [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) define:

- Layout conventions specific to that diagram type
- Anti-patterns to avoid
- A complete worked example

When contributing a new diagram type, you'll create [`type-yourtype.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-yourtype.md) and three HTML template variants in `assets/` ([`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html), [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html), [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-full.html)).

### Import Pipelines for External Formats

The skill transforms Draw.io and Mermaid sources into a structured intermediate representation:

- [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) — handles Draw.io XML
- [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) — parses Mermaid syntax

Verification scripts [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) and [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) exercise these pipelines and catch regressions.

## Validation Gates: The Quality Fence

Before any pull request merges, **all validation gates must pass**. These gates run automatically via GitHub Actions ([`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml)) and enforce consistency across documentation, code, and visual output.

| Gate | Purpose | Script Location |
|------|---------|-----------------|
| Plugin version bump consistency | Ensures [`package.json`](https://github.com/cathrynlavery/diagram-design/blob/main/package.json) and marketplace manifests stay synchronized | [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) |
| SVG accessibility contract | Validates color palette, font rules, and screen-reader metadata | [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py) |
| Import extractor correctness | Verifies Draw.io and Mermaid parsers against fixtures | [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py), [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) |
| Documentation synchronization | Confirms command definitions match shipped examples | [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) |
| Screenshot freshness | Detects visual drift in canonical renders | [`scripts/verify-screenshot-freshness.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-screenshot-freshness.py) |
| Semantic motion validation | Checks animation timing and easing curves | [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) |
| Geometry validation | Validates coordinate systems and responsive scaling | [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) |
| Package integrity | End-to-end test of the distributed skill | [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py) |

Run the full suite locally before committing:

```bash
python3 scripts/test-plugin-package.py \
  && python3 scripts/verify-plugin-package.py origin/main \
  && claude plugin validate . --strict \
  && python3 scripts/lint-skin.py --all --baseline \
  && python3 scripts/verify-semantic-motion.py --markdown-only \
  && python3 scripts/verify-geometry.py --all \
  && python3 scripts/verify-docs-sync.py

```

## Step-by-Step Contribution Workflow

The canonical workflow for how to contribute to Diagram Design is documented in [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) and follows these phases:

### 1. Issue Creation and Branch Setup

```bash
git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design
git checkout -b feature/add-new-type

```

Open an issue describing your proposed change—new diagram types, import improvements, and documentation fixes all require discussion before implementation.

### 2. Implementation Phase

- **New diagram type**: Add [`type-yourtype.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-yourtype.md) in `skills/diagram-design/references/` with layout rules, anti-patterns, and worked example
- **Import pipeline change**: Modify [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) or [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and update corresponding fixture files
- **Documentation fix**: Edit relevant `.md` files and run [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) to catch cross-reference drift

Keep pull requests focused. The maintainers reject sprawling changes that touch multiple concerns.

### 3. Pre-Submission Validation

Never skip local validation. A failing gate in CI blocks merge and consumes reviewer time. The command chain above exercises every gate except screenshot verification, which requires a rendering environment.

### 4. Version Bump and Commit

```bash
python3 scripts/bump-plugin-version.py    # defaults to patch

# Use --minor or --major for breaking changes or new capabilities

git add .
git commit -m "feat(type): add your-type diagram"
git push -u origin feature/add-new-type

```

Commit messages follow conventional commits with scope tags: `feat(type)`, `fix(import)`, `docs(api)`, `refactor(geometry)`.

## Key Files for Contributors

Understanding these files accelerates your first contribution:

- **[`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md)** — Complete contribution guide with PR conventions and gate descriptions
- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** — Design system description and request routing logic
- **`skills/diagram-design/references/`** — 38 diagram type specifications (your reference for new types)
- **[`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py)** — The accessible-SVG contract; read this to understand visual constraints
- **[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)** — Keeps documentation, command files, and examples aligned
- **[`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml)** — The automated pipeline that enforces all gates on every push

## Extending Import Support

To add support for a new external format (e.g., Excalidraw, Structurizr DSL):

1. Create [`skills/diagram-design/scripts/yourformat_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/yourformat_extract.py) following the pattern in [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)
2. Define the intermediate representation mapping in [`skills/diagram-design/references/ir-schema.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/ir-schema.md)
3. Add verification script [`scripts/verify-yourformat-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-yourformat-import.py) with fixture tests
4. Register the new pipeline in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) routing logic
5. Bump plugin version and run full gate suite

The existing extractors demonstrate error handling, coordinate transformation, and metadata preservation—study them before writing new parsers.

## Summary

- **Diagram Design contribution** requires passing eight validation gates that protect downstream agents
- **New diagram types** need a reference file in `skills/diagram-design/references/` and three HTML template variants
- **Import pipelines** for external formats live in `skills/diagram-design/scripts/` with dedicated verification scripts
- **Version bumps** are mandatory via [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) before any PR affecting the distributed package
- **Local validation** prevents CI failures—run the full gate suite before pushing

## Frequently Asked Questions

### What happens if I skip a validation gate locally?

Your pull request will fail in GitHub Actions and cannot merge. The maintainers do not override failing gates. Run `python3 scripts/lint-skin.py --all --baseline` and the full verification chain to catch issues early.

### Do I need to bump the version for documentation-only changes?

No. Use [`scripts/bump-plugin-version.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/bump-plugin-version.py) only when your change affects the distributed skill package—new types, import parsers, or design system changes. Pure documentation fixes in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) or [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) skip version bumps.

### How do I add a new diagram type to Diagram Design?

Create [`skills/diagram-design/references/type-yourname.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-yourname.md) with layout conventions, anti-patterns, and a worked example. Add three template variants ([`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html), [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html), [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-full.html)) in `assets/`. Run the full gate suite and bump the plugin version before submitting your PR.

### Where does the skill routing logic live?

The main entry point is [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). It parses incoming requests, routes to the appropriate type reference, and lazily loads semantic-pattern or animation modules only when the diagram requires them.