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

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 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, 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 and 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 and three HTML template variants in assets/ (template.html, template-dark.html, 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 — handles Draw.io XML
• skills/diagram-design/scripts/mermaid_extract.py — parses Mermaid syntax

Verification scripts scripts/verify-drawio-import.py and 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) and enforce consistency across documentation, code, and visual output.

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

Run the full suite locally before committing:

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 and follows these phases:

1. Issue Creation and Branch Setup

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 in skills/diagram-design/references/ with layout rules, anti-patterns, and worked example
• Import pipeline change: Modify drawio_extract.py or mermaid_extract.py and update corresponding fixture files
• Documentation fix: Edit relevant .md files and run 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

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 — Complete contribution guide with PR conventions and gate descriptions
• 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 — The accessible-SVG contract; read this to understand visual constraints
• scripts/verify-docs-sync.py — Keeps documentation, command files, and examples aligned
• .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 following the pattern in drawio_extract.py
2. Define the intermediate representation mapping in skills/diagram-design/references/ir-schema.md
3. Add verification script scripts/verify-yourformat-import.py with fixture tests
4. Register the new pipeline in 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 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 only when your change affects the distributed skill package—new types, import parsers, or design system changes. Pure documentation fixes in README.md or CONTRIBUTING.md skip version bumps.

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

Create skills/diagram-design/references/type-yourname.md with layout conventions, anti-patterns, and a worked example. Add three template variants (template.html, template-dark.html, 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. It parses incoming requests, routes to the appropriate type reference, and lazily loads semantic-pattern or animation modules only when the diagram requires them.

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