SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdym-diagram-design-install-and-verify

dym-diagram-design-install-and-verify

Design & creation

View repository

Updated 10-18 01:22

About this skill

Skill: dym-diagram-design-install-and-verify — Install it and prove it runs

Why use it: Diagram Design is a plugin/agent-skill, not an npm or pypi package — there's no npm install, no pip install, no binary. Install it in the wrong place and the skill is never loaded, and you'll sit waiting for something that doesn't exist.

What this file produces: an installation of Diagram Design that your agent can load, plus three pieces of real-run evidence (the gallery opens, the scripts in the skill run, the doctor reports).

0. Prerequisites

Item Required? Verified note
Python 3.10+ Required for /doctor references/doctor.md §"Required checks" item 1 — below 3.10 is fail. But see the warning in §4 below: the scripts in the skill still run on 3.9.6.
Playwright + Chromium Only needed when exporting PNG pip install playwright && playwright install chromium — this command string is taken verbatim from references/doctor.md and references/export.md:65-66.
Node/npm Not needed Used only by the repo's own CI (npx @anthropic-ai/claude-code plugin validate), not by users.

There is no build step. There is no node_modules. The entire "product" is Markdown + static HTML files + 3 pure Python scripts (no external libraries).

1. Install by host (pick exactly one)

The /plugin ... commands are typed in the chat box, the codex/droid/pi commands are typed in the terminal.

Claude Code — chat

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Then turn on updates once: type /plugin → Marketplaces → select diagram-design → Enable auto-update. Claude Code disables auto-update by default for third-party marketplaces, so skipping this step leaves you stuck on the installed version. Type /reload-plugins when prompted.

Codex — shell

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
# lấy bản mới ngay, không chờ khởi động phiên sau:
codex plugin marketplace upgrade diagram-design

Factory Droid — shell

droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user
# cập nhật (Droid bám commit, không bám version trong manifest):
droid plugin marketplace update diagram-design
droid plugin update diagram-design@diagram-design --scope user

Pi — shell

pi install https://github.com/cathrynlavery/diagram-design
pi update --extensions   # Pi không tự refresh; phải gọi tay

Inside an open Pi session, type /reload. Pi additionally loads 4 prompt templates /export-diagram, /import-mermaid, /profile, /doctor from the directory prompts/.

Kiro — enter the subdirectory URL

https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design

Kiro copy into .kiro/skills/ (workspace) or ~/.kiro/skills/ (global) — to update, re-enter the URL.

OpenCode and any other Agent-Skills host — symlink

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.config/opencode/skills/diagram-design

2. Install in "editable" mode — choose this when you want to edit it yourself style-guide.md

An install via marketplace gets overwritten on update. If you plan to edit it directly references/style-guide.md in the installation, clone then symlink:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Claude Code
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

# Pi
pi install ~/code/diagram-design

# các host Agent-Skills khác — chỉ tạo root nào bạn thực sự dùng
mkdir -p ~/.agents/skills ~/.cursor/skills ~/.cline/skills ~/.kiro/skills ~/.config/opencode/skills
ln -s ~/code/diagram-design/skills/diagram-design ~/.agents/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.cursor/skills/diagram-design

Important note: even the marketplace installation does not lose your brand if you use profile (~/.diagram-design/profiles/) or project marker (.diagram-design) — see 02-brand-onboarding-and-profiles.md. Editable install is only needed when you deliberately modify the working copy.

3. Prove it runs — 3 pieces of evidence, no guessing

3.1 Gallery opens (no installation needed)

open  ~/code/diagram-design/skills/diagram-design/assets/index.html   # macOS
xdg-open ~/code/diagram-design/skills/diagram-design/assets/index.html # Linux

Expected: a self-contained HTML page showing all 39 diagram types. No server needed, no network needed (except Google fonts).

3.2 Scripts in the skill run — actually run on fixtures

cd ~/code/diagram-design
python3 skills/diagram-design/scripts/drawio_extract.py scripts/fixtures/sample-architecture.drawio | head -12
python3 skills/diagram-design/scripts/self_check.py skills/diagram-design/assets/example-architecture.html

Expected (actually run, verbatim output):

# draw.io IR — sample\-architecture\.drawio
1 page(s): [0] Platform (12n/8e)
...
- budget: nodes OVER (max 9), edges ok (max 12)

OK skills/diagram-design/assets/example-architecture.html

3.3 Doctor reports — chat

/diagram-design:doctor
/diagram-design:doctor --strict --json

In Pi / Factory Droid, type /doctor. This is a command chat, not shell — there is no bin/doctor to call.

Doctor runs read-only: does not install packages, does not modify files, does not run destructive git commands (references/doctor.md §"Safety and behavior rules"). It runs in one of two modes:

  • Installed-skill mode (default) — only checks runtime + installation. Missing maintainer scripts not an error.
  • Maintainer-checkout mode — only enabled when the root directory has enough CONTRIBUTING.md + .github/workflows/ci.yml + scripts/verify-plugin-package.py. Then it checks 5 scripts and 9 routing files.

Fixed output format:

Doctor summary: <PASS|WARN|FAIL> (<n> pass, <n> warn, <n> fail)
[PASS] Python 3.11.9 found at /usr/bin/python3
[WARN] Playwright not installed ...

--json plus an object with status, counts, checks[], timestamp.

4. Two traps I stumbled into myself (measured on a real machine, no speculation)

Trap 1 — macOS defaults to Python 3.9, doctor will report FAIL

On the test machine: /usr/bin/python3 is 3.9.6. Doctor returns exactly as designed:

Doctor summary: FAIL (3 pass, 1 warn, 1 fail)
[FAIL] Python runtime: Python 3.9.6 found via python3 at /usr/bin/python3; Diagram Design requires Python >= 3.10.

But — and this is what the README does not say — all three scripts in the skill still run green on 3.9.6: drawio_extract.py, mermaid_extract.py, self_check.py all rc=0. The 3.10 threshold is a declared threshold in references/doctor.md, not a technical threshold of the import/export path. The cleanest fix is to point python3 to Homebrew (/opt/homebrew/bin/python3) rather than ignoring doctor.

Trap 2 — doctor reports "Playwright not available" EVEN THOUGH Playwright is installed

Measured on the test machine:

$ python3 -c "import importlib.metadata as m; print(m.version('playwright'))"
1.58.0
$ python3 -c "from playwright.sync_api import sync_playwright; print('sync_api import ok')"
sync_api import ok

Playwright is real, sync_api importable. Yet doctor still prints:

[WARN] Playwright PNG export readiness: Playwright package is not available in the active Python interpreter.

Cause, read directly in the code: scripts/verify-doctor.py:158 probes with

[python_cmd, "-c", "import playwright; print(playwright.__version__)"]

but the package playwright does not have the attribute __version__ — this command raises AttributeError and is misinterpreted as "not installed".

$ python3 -c "import playwright; print(playwright.__version__)"
AttributeError: module 'playwright' has no attribute '__version__'

Practical consequence: do not trust doctor's Playwright warning. Check manually with importlib.metadata as above. PNG export still works normally.

5. Complete this step when

  • Gallery assets/index.html opens and shows all 39 diagrams.
  • self_check.py on any example prints OK and rc=0.
  • /diagram-design:doctor can print a summary (including FAIL — what matters is that it runs).
  • You know python3 which version yours is, and have decided to fix or accept it.

Next: 02-brand-onboarding-and-profiles.md — because the first diagram will be blocked by the style-guide gate if you haven't onboarded the brand yet.