Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.
Python agent-skillsarchitecturearchitecture-diagramasyncapibpmnc4-modelclaude-codediagramdiagrams-as-codedrawioflowchartgithub-actionsgraphqlimage-to-diagramkubernetesmcp-serverprotobufsysmlterraformuml
fix: address Codex review findings — docs, scripts, CI, and metadata
Agents365-aif1b4f46b6905
diff --git a/.github/workflows/publish-clawhub.yml b/.github/workflows/publish-clawhub.ymlindex d0ba70d..e52f123 100644--- a/.github/workflows/publish-clawhub.yml+++ b/.github/workflows/publish-clawhub.yml@@ -8,6 +8,13 @@ on:- 'SKILL.md'- 'scripts/**'+concurrency:+ group: clawhub-publish+ cancel-in-progress: true++permissions:+ contents: read+jobs:publish:runs-on: ubuntu-latest@@ -19,12 +26,13 @@ jobs:node-version: '20'- name: Install ClawHub CLI- run: npm install -g clawhub+ run: npm install -g clawhub@latest- name: Authenticate with ClawHubrun: |mkdir -p "$HOME/.config/clawhub"echo '{"registry":"https://clawhub.ai","token":"'"${{ secrets.CLAWHUB_TOKEN }}"'"}' > "$HOME/.config/clawhub/config.json"+ chmod 600 "$HOME/.config/clawhub/config.json"- name: Get version from metadataid: versiondiff --git a/README.md b/README.mdindex f46acbe..d2da0b3 100644--- a/README.md+++ b/README.md@@ -232,7 +232,7 @@ Platform-specific package managers:```bash# OpenClaw-clawhub update drawio-skill+clawhub update drawio-pro-skill# SkillsMPskills update drawio-skill@@ -295,6 +295,15 @@ CI/CD pipeline with a closed loop and 2 spur branches. Edges flow along the peri> All example diagrams were generated by Claude Opus 4.6 with this skill.+## Known Limitations++- **Command name varies by platform**: macOS Homebrew installs the command as `draw.io`; some Linux packages use `drawio`. The skill handles both, but verify which name works on your system with `draw.io --version` or `drawio --version`+- **Linux headless export**: Requires `xvfb` for display virtualization — without it, CLI export will fail on servers without a display+- **Browser fallback requires Python**: The `diagrams.net` URL generator uses `python3` for compression/encoding. If neither CLI nor Python is available, the skill generates `.drawio` XML only+- **Self-check requires vision**: The auto-fix step reads exported PNGs using the model's vision capability. Models without vision support skip this step+- **Cloud icons**: Currently supports basic AWS resource icons. GCP, Azure, and Kubernetes icon sets are not yet included+- **No source .drawio for microservices example**: The `microservices-example.png` in assets was generated in a session but the source `.drawio` was not preserved+## LicenseMITdiff --git a/README_CN.md b/README_CN.mdindex e84c658..8ebfbc8 100644--- a/README_CN.md+++ b/README_CN.md@@ -232,7 +232,7 @@ cd <你的安装路径>/drawio-skill && git pull```bash# OpenClaw-clawhub update drawio-skill+clawhub update drawio-pro-skill# SkillsMPskills update drawio-skill@@ -296,6 +296,15 @@ CI/CD 流水线,包含闭合回路和 2 个分支。线条沿矩形外围流> 所有示例图表均由 Claude Opus 4.6 配合本 skill 生成。+## 已知限制++- **命令名因平台而异**:macOS Homebrew 安装的命令是 `draw.io`,部分 Linux 包使用 `drawio`。本 skill 兼容两者,请用 `draw.io --version` 或 `drawio --version` 确认你的系统使用哪个+- **Linux 无头导出**:需要 `xvfb` 进行显示虚拟化 — 没有显示器的服务器上 CLI 导出会失败+- **浏览器降级需要 Python**:`diagrams.net` URL 生成器使用 `python3` 进行压缩/编码。如果 CLI 和 Python 都不可用,skill 仅生成 `.drawio` XML 文件+- **自检需要视觉能力**:自动修复步骤需要模型的视觉能力来读取导出的 PNG。不支持视觉的模型会跳过此步骤+- **云图标**:目前支持基础 AWS 资源图标。GCP、Azure 和 Kubernetes 图标集尚未包含+- **微服务示例缺少源文件**:`assets/` 中的 `microservices-example.png` 在会话中生成,但源 `.drawio` 文件未保留+## 开源协议MITdiff --git a/SKILL.md b/SKILL.mdindex 18e240c..3989acd 100644--- a/SKILL.md+++ b/SKILL.md@@ -55,6 +55,13 @@ Install draw.io desktop if missing:## Workflow+Before starting the workflow, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:+- **Diagram type** — which preset? (ERD, UML, Sequence, Architecture, ML/DL, Flowchart, or general)+- **Output format** — PNG (default), SVG, PDF, or JPG?+- **Scope/fidelity** — how many components? Any specific technologies or labels?++Skip clarification if the request already specifies these details or is clearly simple (e.g., "draw a flowchart of X").+1. **Check deps** — verify `draw.io --version` succeeds; note platform for correct CLI path2. **Plan** — identify shapes, relationships, layout (LR or TB), group by tier/layer3. **Generate** — write `.drawio` XML file to disk (output dir same as user's working dir)@@ -340,6 +347,17 @@ print('https://viewer.diagrams.net/?tags=%7B%7D&lightbox=1&edit=_blank#R' + urllThis produces a client-side URL that opens the diagram in the browser for viewing and editing. No data is uploaded to any server — the entire diagram XML is encoded in the URL fragment (after `#`), which is never sent to the server. Useful when the user cannot install the desktop app.+### Fallback chain++When tools are unavailable, degrade gracefully:++| Scenario | Behavior |+|----------|----------|+| draw.io CLI missing, Python available | Use browser fallback (diagrams.net URL) |+| draw.io CLI missing, Python missing | Generate `.drawio` XML only; instruct user to open in draw.io desktop or diagrams.net manually |+| Vision unavailable for self-check | Skip self-check (step 5); proceed directly to showing user the exported PNG |+| Export fails (Chromium/display issues) | On Linux, retry with `xvfb-run -a`; if still failing, deliver `.drawio` XML and suggest manual export |+### Checking if draw.io is in PATH```bashdiff --git a/agents/openai.yaml b/agents/openai.yamlindex aa3431c..4720321 100644--- a/agents/openai.yaml+++ b/agents/openai.yaml@@ -1,7 +1,19 @@interface:display_name: "Draw.io Diagrams"- short_description: "Generate draw.io diagrams from natural language and export to PNG/SVG/PDF"+ short_description: "Generate draw.io diagrams from natural language and export to PNG/SVG/PDF/JPG with self-check and iterative refinement"brand_color: "#F08705"policy:allow_implicit_invocation: true++capabilities:+ - Generate .drawio XML from natural language descriptions+ - Export to PNG, SVG, PDF, JPG via draw.io desktop CLI+ - 6 diagram presets (ERD, UML Class, Sequence, Architecture, ML/DL, Flowchart)+ - Self-check exported images and auto-fix layout issues+ - Iterative review loop with targeted XML edits+ - Browser fallback via diagrams.net URL when CLI unavailable+ - Animated connectors for data-flow diagrams++prerequisites:+ - draw.io desktop app (macOS/Linux/Windows)diff --git a/scripts/check-update.sh b/scripts/check-update.shindex 5bd950d..e4f87dd 100755--- a/scripts/check-update.sh+++ b/scripts/check-update.sh@@ -13,21 +13,40 @@ if ! git -C "$SKILL_DIR" rev-parse --git-dir &>/dev/null; thenexit 2fi-REMOTE_HASH=$(git -C "$SKILL_DIR" ls-remote origin HEAD 2>/dev/null | cut -f1)+# Detect current branch and its upstream+BRANCH=$(git -C "$SKILL_DIR" symbolic-ref --short HEAD 2>/dev/null) || {+ echo "Detached HEAD — cannot check for updates. Please checkout a branch." >&2+ exit 2+}++UPSTREAM=$(git -C "$SKILL_DIR" rev-parse --abbrev-ref "${BRANCH}@{upstream}" 2>/dev/null) || {+ echo "Branch '$BRANCH' has no upstream configured. Set with: git branch --set-upstream-to=origin/$BRANCH" >&2+ exit 2+}++REMOTE_NAME="${UPSTREAM%%/*}"++# Fetch latest refs from remote+if ! git -C "$SKILL_DIR" fetch "$REMOTE_NAME" --quiet 2>/dev/null; then+ echo "Cannot reach remote '$REMOTE_NAME' (offline?)" >&2+ exit 2+fi+LOCAL_HASH=$(git -C "$SKILL_DIR" rev-parse HEAD 2>/dev/null)+REMOTE_HASH=$(git -C "$SKILL_DIR" rev-parse "$UPSTREAM" 2>/dev/null)if [ -z "$REMOTE_HASH" ]; then- echo "Cannot reach remote (offline?)" >&2+ echo "Cannot resolve upstream ref '$UPSTREAM'" >&2exit 2fiif [ "$REMOTE_HASH" != "$LOCAL_HASH" ]; then- echo "Update available for drawio-skill."+ echo "Update available for drawio-skill (branch: $BRANCH)."echo " Local: ${LOCAL_HASH:0:8}"echo " Remote: ${REMOTE_HASH:0:8}"- echo " Run: cd $SKILL_DIR && git pull"+ echo " Run: cd \"$SKILL_DIR\" && git pull"exit 0else- echo "drawio-skill is up to date."+ echo "drawio-skill is up to date (branch: $BRANCH)."exit 1fidiff --git a/temp/codex-review-suggestions.md b/temp/codex-review-suggestions.mdnew file mode 100644index 0000000..58b42d7--- /dev/null+++ b/temp/codex-review-suggestions.md@@ -0,0 +1,92 @@+# Codex Review Suggestions for drawio-skill++## Top Risks++- **High**: Over-claims parity with competitors; `assets/` only demonstrates 3 topology demos + workflow, not 6 presets+- **High**: Command naming inconsistent: `draw.io` in SKILL.md vs `drawio` in READMEs+- **High**: OpenClaw package naming inconsistent: `drawio-pro-skill` (install) vs `drawio-skill` (update)++## 1) SKILL.md++| Priority | Suggestion |+|----------|-----------|+| High | Add clarification policy for underspecified requests (ask 1-3 questions) |+| High | Define fallback behavior when CLI, vision, or Python is unavailable |+| Medium | Add edge cases: existing files, filename collisions, multi-page, large diagrams, non-English labels |+| Medium | Add planning template for each preset (nodes, edges, groups, orientation, labels, formats) |+| Low | Soften absolute "always" wording in routing rules |++## 2) README.md / README_CN.md++| Priority | Suggestion |+|----------|-----------|+| High | Add "Known Limitations" section |+| High | Fix EN/CN consistency: CN title still English, OpenClaw slug mismatch |+| Medium | Add quickstart with end-to-end example |+| Medium | Add feature matrix: "implemented" vs "demonstrated" vs "metadata only" |+| Low | Move support/donation blocks below troubleshooting |++## 3) scripts/check-update.sh++| Priority | Suggestion |+|----------|-----------|+| High | Compare against current branch upstream, not `origin HEAD` |+| High | Handle missing `origin`, detached HEAD, shallow clones, dirty trees |+| Medium | Quote `cd` path, print current branch/upstream |+| Low | Add `--json` and `--fetch` modes |++## 4) .github/workflows/publish-clawhub.yml++| Priority | Suggestion |+|----------|-----------|+| High | Pin CLI version instead of `npm install -g clawhub` |+| High | Add concurrency control; gate publish on version change |+| Medium | Replace grep-based version extraction with robust parser |+| Medium | Add validation before publish (schema/lint, link check, dry-run) |+| Low | Set minimal job permissions |++## 5) .claude/settings.local.json++| Priority | Suggestion |+|----------|-----------|+| High | Too permissive (git push, broad python3, clawhub publish) |+| High | Hard-coded absolute paths leak local machine structure |+| Medium | Split authoring/demo permissions from normal use |+| Low | Document why each permission exists |++## 6) docs/index.html / docs/zh.html++| Priority | Suggestion |+|----------|-----------|+| High | Accessibility: tabs use divs, no keyboard support, no focus states, no aria-labels |+| High | Mobile: comparison table has no overflow wrapper |+| Medium | SEO: add canonical URL, og:*, Twitter cards, hreflang, favicon |+| Medium | Demo images use remote URLs instead of local assets |+| Low | Both docs omit Hermes install instructions |++## 7) agents/openai.yaml++| Priority | Suggestion |+|----------|-----------|+| High | Too minimal to justify "Full support" claim |+| Medium | Add examples, capabilities, prerequisites, output formats |+| Low | Align wording with SKILL.md |++## 8) assets/*.drawio++| Priority | Suggestion |+|----------|-----------|+| High | No ERD, UML, sequence, or ML/DL .drawio examples (claimed 6 presets) |+| High | microservices-example.png has no matching source .drawio |+| Medium | Add domain-diverse examples |+| Low | Export sample SVG/PDF artifacts |++## Broken Links / Inconsistencies++- Command naming and ClawHub slug drift are confirmed inconsistencies+- No broken relative links found++## Competitor Gaps++- `bahayonghang/drawio-skills`: real-time browser preview, version history, cloud icons, math typesetting+- `jgraph/drawio-mcp`: Mermaid/CSV entry, inline/browser app modes