# How to Add a New Diagram Type to the Diagram-Design Skill > Learn the six-step declarative workflow to add a new diagram type to the cathrynlavery/diagram-design skill. Register specs, generate examples, and verify without engine changes. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-08-15 --- **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-.md` by copying an existing reference such as [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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. ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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. ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html)) to create three files in `skills/diagram-design/assets/`: 1. `example-.html` — minimal light theme 2. `example--dark.html` — minimal dark theme 3. `example--full.html` — full editorial layout ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html). This ensures discoverability for users and satisfies the docs-sync gate that validates the repository’s integrity. ```bash sed -i '//a\
  • Mytype (light)
    • \
  • Mytype (dark)
    • \
  • Mytype (full)
    • ' 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: ```bash 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-.md` - [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) - `skills/diagram-design/assets/example-*.html` - [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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-.md` to define layout, spacing, and connector rules for the new type. - **Register** the type in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) section 3 and update the front-matter `description` to enable UI selection and prevent [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) failures. - **Generate** three HTML variants (light, dark, full) in `skills/diagram-design/assets/` based on [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) to satisfy gallery and testing requirements. - **List** the new examples in [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) so the gallery can resolve every shipped asset. - **Validate** using [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py) and [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) script—executed during CI or via [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html). ### How does the verification suite validate my new diagram type? The [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) runner performs broader integration tests, including documentation sync validation, ensuring that entries in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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-.html`, `example--dark.html`, `example--full.html`) are mandatory inputs for the self-check suite and the documentation gallery.