How to Add a New Diagram Type to the Diagram-Design Skill

Adding a new diagram type to the cathrynlavery/diagram-design skill follows a purely declarative six-step workflow where you create a reference specification, register it in the skill manifest, generate three HTML example variants, and pass automated verification without modifying any rendering engine code.

Adding support for a new visual type—such as a Radar chart or custom Flowchart—requires extending the skill’s taxonomy through configuration files rather than code changes. According to the cathrynlavery/diagram-design repository, the workflow keeps documentation, assets, and verification suites synchronized while enforcing a strict rule: never edit the rendering engine. Below is the exact pipeline from the source code, including specific file paths and validation commands.

Step 1: Create the Type Reference File

Start by creating the declarative specification that defines layout rules for your new type.

Create skills/diagram-design/references/type-<name>.md by copying an existing reference such as type-architecture.md. This markdown file serves as the single source of truth for SVG primitives, spacing conventions, mandatory connector rules, and anti-patterns for your diagram type.

cp skills/diagram-design/references/type-architecture.md \
   skills/diagram-design/references/type-mytype.md

Edit the new file to document the specific layout constraints and include a worked example that demonstrates valid usage.

Step 2: Register the Type in SKILL.md

Next, expose the new type to the skill’s CLI and UI prompt system by updating the central manifest.

Insert a row into the Visual-type guide table located in section 3 of skills/diagram-design/SKILL.md. The table drives the selection interface that lets users pick your new diagram type. Additionally, append the type name to the front-matter description field at the top of the file.

vim skills/diagram-design/SKILL.md

# Add to section 3 table:

# | My custom diagram | **Mytype** | [type-mytype.md](references/type-mytype.md) |

If you skip this step, the verify-docs-sync.py script will fail during CI because the documentation references will be out of sync with the registered types.

Step 3: Generate Three Example Variants

The skill requires three visual demonstrations to showcase different themes and complexity levels.

Copy the closest existing variant (usually template.html) to create three files in skills/diagram-design/assets/:

1. example-<type>.html — minimal light theme
2. example-<type>-dark.html — minimal dark theme
3. example-<type>-full.html — full editorial layout

cp skills/diagram-design/assets/template.html \
   skills/diagram-design/assets/example-mytype.html

# Repeat for -dark and -full variants

Populate each file with the SVG body that conforms to the layout rules defined in your reference file. These examples are exercised by the self-check suite and displayed in the documentation gallery.

Step 4: Register Examples in the Gallery

The gallery page must resolve every shipped example; missing entries trigger verification failures.

Add list entries for your three new HTML files to assets/index.html. This ensures discoverability for users and satisfies the docs-sync gate that validates the repository’s integrity.

sed -i '/<!-- examples -->/a\
<li><a href="example-mytype.html">Mytype (light)</a></li>\
<li><a href="example-mytype-dark.html">Mytype (dark)</a></li>\
<li><a href="example-mytype-full.html">Mytype (full)</a></li>' assets/index.html

Step 5: Run the Verification Suite

Validate your declarative changes against the skill’s geometry and accessibility rules.

Execute the linting script against your new asset, then run the generic gate runner to perform full verification:

python3 scripts/lint-skin.py skills/diagram-design/assets/example-mytype.html
python3 scripts/self_check.py skills/diagram-design/assets/example-mytype.html

You may also run python3 scripts/lint-skin.py --all to check the entire asset directory. These scripts verify SVG geometry, connector rules, accessibility metadata, and that all generated assets comply with the declarative specifications defined in your reference file.

Step 6: Commit and Open a Pull Request

Complete the workflow by submitting your changes through the repository’s standard Git workflow.

Commit your changes following the Conventional Commits style (e.g., feat: add mytype diagram support). Ensure your pull request touches only the files introduced or updated in the previous steps—specifically:

• skills/diagram-design/references/type-<name>.md
• skills/diagram-design/SKILL.md
• skills/diagram-design/assets/example-<type>*.html
• assets/index.html

This scope restriction keeps review focused and guarantees CI passes before merging.

Summary

• Create a declarative reference in skills/diagram-design/references/type-<name>.md to define layout, spacing, and connector rules for the new type.
• Register the type in skills/diagram-design/SKILL.md section 3 and update the front-matter description to enable UI selection and prevent verify-docs-sync.py failures.
• Generate three HTML variants (light, dark, full) in skills/diagram-design/assets/ based on template.html to satisfy gallery and testing requirements.
• List the new examples in assets/index.html so the gallery can resolve every shipped asset.
• Validate using scripts/lint-skin.py and scripts/self_check.py to enforce SVG geometry, accessibility standards, and documentation sync.
• Submit a focused PR following Conventional Commits without modifying any rendering engine code.

Frequently Asked Questions

Do I need to modify Python or JavaScript rendering code to add a new diagram type?

No. The workflow is purely declarative. You only create markdown reference files and HTML examples that describe layout rules. The rendering engine consumes these declarations without any modification to its core logic, as enforced by the verification suite.

What happens if I forget to update assets/index.html?

The verify-docs-sync.py script—executed during CI or via scripts/self_check.py—will flag an error. The gallery must resolve every shipped example, and the verification suite explicitly checks that all files in skills/diagram-design/assets/ are registered in assets/index.html.

How does the verification suite validate my new diagram type?

The scripts/lint-skin.py utility checks SVG geometry, connector rule compliance, and accessibility metadata against the specifications in your reference file. The scripts/self_check.py runner performs broader integration tests, including documentation sync validation, ensuring that entries in SKILL.md match existing reference files and gallery listings.

Can I add a custom diagram type without creating all three example variants?

No. The skill requires exactly three variants—minimal light, minimal dark, and full editorial—to demonstrate theme compatibility and complexity ranges. These files (example-<type>.html, example-<type>-dark.html, example-<type>-full.html) are mandatory inputs for the self-check suite and the documentation gallery.

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