Skip to content

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.

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.yml
index 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 ClawHub
run: |
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 metadata
id: version
diff --git a/README.md b/README.md
index 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
# SkillsMP
skills 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
+
## License
MIT
diff --git a/README_CN.md b/README_CN.md
index 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
# SkillsMP
skills 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` 文件未保留
+
## 开源协议
MIT
diff --git a/SKILL.md b/SKILL.md
index 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 path
2. **Plan** — identify shapes, relationships, layout (LR or TB), group by tier/layer
3. **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' + urll
This 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
```bash
diff --git a/agents/openai.yaml b/agents/openai.yaml
index 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.sh
index 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; then
exit 2
fi
-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'" >&2
exit 2
fi
if [ "$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 0
else
- echo "drawio-skill is up to date."
+ echo "drawio-skill is up to date (branch: $BRANCH)."
exit 1
fi
diff --git a/temp/codex-review-suggestions.md b/temp/codex-review-suggestions.md
new file mode 100644
index 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