@e4779/skills 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/chrome-devtools/README.md +76 -0
- package/chrome-devtools/SKILL.md +277 -0
- package/chrome-devtools/references/recipes.md +379 -0
- package/chrome-devtools/references/setup.md +138 -0
- package/drawio/SKILL.md +395 -0
- package/gh-cli/SKILL.md +83 -0
- package/grill/SKILL.md +72 -0
- package/layout-check/README.md +32 -0
- package/layout-check/SKILL.md +416 -0
- package/layout-check/scripts/layoutProbe.mjs +539 -0
- package/mcpls/SKILL.md +261 -0
- package/mcpls/references/configuration.md +131 -0
- package/mcpls/references/install.md +13 -0
- package/mcporter/SKILL.md +90 -0
- package/mindmap/SKILL.md +46 -0
- package/mindmap/references/drawio-recipe.md +60 -0
- package/mindmap/references/mindmap-design.md +63 -0
- package/opensource-contribution/SKILL.md +119 -0
- package/package.json +29 -5
- package/shell-taste/.shellcheckrc +16 -0
- package/shell-taste/SKILL.md +95 -0
- package/shell-taste/references/handbook/dialects.md +168 -0
- package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
- package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
- package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
- package/shell-taste/references/handbook/dom/04-network.md +384 -0
- package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
- package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
- package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
- package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
- package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
- package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
- package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
- package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
- package/shell-taste/references/handbook/dom/13-containers.md +13 -0
- package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
- package/shell-taste/references/handbook/family-index.md +230 -0
- package/shell-taste/references/handbook/index.md +41 -0
- package/skill-author/SKILL.md +86 -0
- package/sobesednik/SKILL.md +98 -0
- package/sobesednik/card-template.md +23 -0
- package/sobesednik/personas/advocate.md +27 -0
- package/sobesednik/personas/analyst.md +29 -0
- package/sobesednik/personas/chat.md +42 -0
- package/sobesednik/personas/ifs.md +32 -0
- package/sobesednik/personas/journal/README.md +6 -0
- package/sobesednik/personas/nasreddin.md +29 -0
- package/sobesednik/personas/premortem.md +29 -0
- package/sobesednik/personas/rogers.md +27 -0
- package/sobesednik/personas/socratic.md +29 -0
- package/sobesednik/personas/stoic.md +27 -0
- package/sobesednik/references/persona-design.md +41 -0
- package/zai-mcp/README.md +63 -0
- package/zai-mcp/SKILL.md +160 -0
- package/zai-mcp/references/recipes.md +273 -0
- package/zai-mcp/references/tools.md +266 -0
- package/README.md +0 -3
package/drawio/SKILL.md
ADDED
|
@@ -0,0 +1,395 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: drawio
|
|
3
|
+
description: Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mindmap, mockup, wireframe, or UI sketch, to read or edit an existing diagram, or mentions draw.io, drawio, .drawio files, or diagram export to PNG/SVG/PDF.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Draw.io Diagram Skill
|
|
7
|
+
|
|
8
|
+
Generate draw.io diagrams as native `.drawio` files. Author each diagram either as **Mermaid** (concise text that the draw.io desktop CLI converts and lays out for you) or as **draw.io XML** directly. Optionally auto-layout XML-authored diagrams with **ELK**, export to PNG/SVG/PDF with the diagram XML embedded (so the exported file stays editable in draw.io), or generate a browser URL that opens the diagram directly in the draw.io editor.
|
|
9
|
+
|
|
10
|
+
## Local setup
|
|
11
|
+
|
|
12
|
+
- Requires the draw.io Desktop CLI on PATH as `drawio` (the desktop app bundles it).
|
|
13
|
+
- Optional: the official `@drawio/mcp` server enables direct read/edit of local
|
|
14
|
+
`.drawio` pages via MCP tools; this skill CLI pipeline does not require it.
|
|
15
|
+
|
|
16
|
+
## Authoring: Mermaid or XML?
|
|
17
|
+
|
|
18
|
+
The desktop CLI can convert Mermaid to a native `.drawio` file, so **prefer Mermaid** for the diagram types it handles well — its parser lays the diagram out automatically, which is far more reliable than hand-positioning cells in XML.
|
|
19
|
+
|
|
20
|
+
| Author as | Best for | Needs desktop CLI? |
|
|
21
|
+
|-----------|----------|--------------------|
|
|
22
|
+
| **Mermaid** | Flowcharts, sequence, class, state, ER, gantt, mindmap, timeline, user journey, quadrant, C4, git graph, pie, and other standard types | Yes — to convert to `.drawio` |
|
|
23
|
+
| **XML** | Custom styling, precise/hand positioning, specific shape libraries (AWS, Azure, network, UML detail…), or when the desktop CLI is not installed | No (optional ELK `--layout` needs the CLI) |
|
|
24
|
+
|
|
25
|
+
- **Prefer Mermaid** when the desktop CLI is available and the request is one of the standard types above — write terse Mermaid and let draw.io lay it out.
|
|
26
|
+
- **Use XML** for precise control, or as the universal fallback: XML needs no CLI at all, so it's the only option when the desktop app isn't installed (output a `.drawio` file or a `url`).
|
|
27
|
+
- For XML-authored diagrams you can ask the CLI to apply an **ELK auto-layout** (`--layout`) instead of computing coordinates yourself — the same layouts the draw.io editor's *Arrange ▸ Layout* menu applies, and the same engine the draw.io MCP app server uses. See [ELK layout for XML](#elk-layout-for-xml).
|
|
28
|
+
|
|
29
|
+
If you're unsure whether the desktop CLI is present, detect it first (see [Locating the CLI](#locating-the-cli)). No CLI → author as XML and deliver a `.drawio` file or a `url`.
|
|
30
|
+
|
|
31
|
+
## The pipeline
|
|
32
|
+
|
|
33
|
+
Every diagram becomes a native `.drawio` file first, then is delivered in the requested output format. This keeps the delivery step identical whether you authored Mermaid or XML.
|
|
34
|
+
|
|
35
|
+
1. **Author → `.drawio`**
|
|
36
|
+
- **Mermaid**: write the Mermaid to a `.mmd` file, then convert it with the CLI:
|
|
37
|
+
```bash
|
|
38
|
+
drawio -x -f xml -o diagram.drawio diagram.mmd
|
|
39
|
+
```
|
|
40
|
+
Delete the `.mmd` afterward — the `.drawio` is the artifact. draw.io's Mermaid parser has already laid the diagram out, so no `--layout` is needed.
|
|
41
|
+
- **XML**: write the mxGraphModel XML to `diagram.drawio` (see [XML format](#xml-format)). Optionally apply an ELK layout (see [ELK layout for XML](#elk-layout-for-xml)).
|
|
42
|
+
2. **Deliver** (identical for both sources):
|
|
43
|
+
- *(no format)* → keep `diagram.drawio` and open it.
|
|
44
|
+
- **png / svg / pdf** → export from the `.drawio` with embedded XML, then delete the source `.drawio`:
|
|
45
|
+
```bash
|
|
46
|
+
drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio
|
|
47
|
+
```
|
|
48
|
+
- **url** → build a browser URL from the `.drawio` XML, open it, and keep the `.drawio` as a local copy (see [Browser URL output](#browser-url-output)).
|
|
49
|
+
3. **Open the result** — the exported file, the URL, or the `.drawio`. If the open command fails, print the absolute path (or URL) so the user can open it manually.
|
|
50
|
+
|
|
51
|
+
**Always convert Mermaid to `.drawio` first, then export** — do not export a `.mmd` straight to an image. Direct Mermaid → PNG export with `-e` is broken in current draw.io Desktop (the embedded-XML step crashes); the two-step path (convert, then export the `.drawio`) is reliable and produces an editable embed. See [Troubleshooting](#troubleshooting).
|
|
52
|
+
|
|
53
|
+
If Mermaid was requested but no desktop CLI is available, fall back to authoring the same diagram directly as XML.
|
|
54
|
+
|
|
55
|
+
## ELK layout for XML
|
|
56
|
+
|
|
57
|
+
XML-authored diagrams can be auto-positioned by the CLI's `--layout` pass — the same ELK layouts as the editor's *Arrange ▸ Layout* menu and the same engine the draw.io MCP app server uses. Generate the cells with approximate (or even `0,0`) positions and let ELK place them; you only have to get the graph *structure* — nodes and edges — right.
|
|
58
|
+
|
|
59
|
+
Add `--layout <name>` to any CLI call that reads your XML. The simplest form lays out in place after you write the file (reading and overwriting the same path is supported):
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or combine layout with export in a single call (works for XML input):
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Layout presets
|
|
72
|
+
|
|
73
|
+
| Name | Layout |
|
|
74
|
+
|------|--------|
|
|
75
|
+
| `verticalFlow` | Layered, top-to-bottom — flowcharts, pipelines |
|
|
76
|
+
| `horizontalFlow` | Layered, left-to-right |
|
|
77
|
+
| `verticalTree` | Tree, top-down — hierarchies, org charts |
|
|
78
|
+
| `horizontalTree` | Tree, left-to-right |
|
|
79
|
+
| `radialTree` | Radial tree |
|
|
80
|
+
| `organic` | Force-directed — networks, mind-map-like graphs |
|
|
81
|
+
|
|
82
|
+
### Custom layout JSON
|
|
83
|
+
|
|
84
|
+
For finer control, pass a JSON **array** (starting with `[`) instead of a preset name — the same format as the editor's custom-layout dialog:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Each entry is `{"layout": <algorithm>, "config": { … }}`:
|
|
91
|
+
|
|
92
|
+
- **Algorithms**: `elkLayered`, `elkTree`, `elkRadial`, `elkOrganic`, `elkStress`, `elkBox`.
|
|
93
|
+
- **`config`**: keys starting with `elk.` are ELK options — e.g. `elk.direction` (`UP` / `DOWN` / `LEFT` / `RIGHT`), `elk.spacing.nodeNode`, `elk.layered.spacing.nodeNodeBetweenLayers`. The keys `edgeStyle` (e.g. `orthogonal`) and `corners` (e.g. `rounded`) control connector rendering.
|
|
94
|
+
|
|
95
|
+
### Orthogonal edge routing
|
|
96
|
+
|
|
97
|
+
`--layout libavoid` routes the **edges** orthogonally around the shapes (the editor's *Arrange ▸ Layout ▸ Orthogonal Routing*) without moving any vertex — the complement of the node layouts above. Use it as an in-place pass on hand-positioned XML whose connectors cross shapes:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Skip it after a flow/tree preset — those already route their edges.
|
|
104
|
+
|
|
105
|
+
**When to use it:** author the graph structure as XML without worrying about coordinates, then apply `verticalFlow` / `horizontalFlow` for flow-style diagrams or `organic` for networks. Mermaid-authored diagrams are already laid out — don't add `--layout`.
|
|
106
|
+
|
|
107
|
+
## Mermaid syntax reference
|
|
108
|
+
|
|
109
|
+
When authoring Mermaid, fetch and follow the shared Mermaid reference (all supported diagram types plus flowchart styling — `style`, `classDef`, `linkStyle`):
|
|
110
|
+
|
|
111
|
+
https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md
|
|
112
|
+
|
|
113
|
+
Match the language of the diagram labels to the user's language.
|
|
114
|
+
|
|
115
|
+
## Choosing the output format
|
|
116
|
+
|
|
117
|
+
Check the user's request for a format preference. Examples:
|
|
118
|
+
|
|
119
|
+
- `create a flowchart` → Mermaid → `flowchart.drawio`
|
|
120
|
+
- `png flowchart for login` → Mermaid → `login-flow.drawio.png`
|
|
121
|
+
- `svg: ER diagram` → Mermaid → `er-diagram.drawio.svg`
|
|
122
|
+
- `pdf AWS architecture overview` → XML (needs AWS shapes) → `architecture-overview.drawio.pdf`
|
|
123
|
+
- `url flowchart for user login` → opens browser at `app.diagrams.net` with the diagram, keeps `login-flow.drawio` locally
|
|
124
|
+
|
|
125
|
+
If no format is mentioned, just produce the `.drawio` file and open it in draw.io. The user can always ask to export later.
|
|
126
|
+
|
|
127
|
+
### Supported export formats
|
|
128
|
+
|
|
129
|
+
| Format | Embed XML | Notes |
|
|
130
|
+
|--------|-----------|-------|
|
|
131
|
+
| `png` | Yes (`-e`) | Viewable everywhere, editable in draw.io |
|
|
132
|
+
| `svg` | Yes (`-e`) | Scalable, editable in draw.io |
|
|
133
|
+
| `pdf` | Yes (`-e`) | Printable, editable in draw.io |
|
|
134
|
+
| `jpg` | No | Lossy, no embedded XML support |
|
|
135
|
+
|
|
136
|
+
PNG, SVG, and PDF all support `--embed-diagram` — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.
|
|
137
|
+
|
|
138
|
+
## Browser URL output
|
|
139
|
+
|
|
140
|
+
When the user requests `url` format, generate a draw.io URL that opens the diagram directly in the browser editor at `app.diagrams.net` — no draw.io Desktop required to *view* it. (Mermaid-authored diagrams still need the desktop CLI to convert to `.drawio` first; if no CLI is available, author the diagram as XML and build the URL from that.)
|
|
141
|
+
|
|
142
|
+
### How it works
|
|
143
|
+
|
|
144
|
+
1. The `.drawio` file is written to disk as usual (gives the user a persistent local copy they can re-edit)
|
|
145
|
+
2. The XML is compressed with Node.js's built-in `zlib` and base64-encoded
|
|
146
|
+
3. The result is embedded in a `https://app.diagrams.net/#create=...` URL
|
|
147
|
+
4. The URL is opened in the default browser
|
|
148
|
+
|
|
149
|
+
This uses only Node.js built-in modules (`zlib`, `child_process`) — no external dependencies.
|
|
150
|
+
|
|
151
|
+
### URL generation
|
|
152
|
+
|
|
153
|
+
Run this `node -e` one-liner to read the `.drawio` file and print the URL (replace `DIAGRAM.drawio` with the actual filename):
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
URL=$(node -e '
|
|
157
|
+
const fs = require("fs");
|
|
158
|
+
const zlib = require("zlib");
|
|
159
|
+
const xml = fs.readFileSync(process.argv[1], "utf8");
|
|
160
|
+
const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64");
|
|
161
|
+
const payload = encodeURIComponent(JSON.stringify({ type: "xml", compressed: true, data: compressed }));
|
|
162
|
+
console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#create=" + payload);
|
|
163
|
+
' "DIAGRAM.drawio")
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
The URL format matches the MCP Tool Server. Node.js's `zlib.deflateRawSync` and `pako.deflateRaw` both implement RFC 1951 and produce identical output, so URLs from either source are interchangeable.
|
|
167
|
+
|
|
168
|
+
### Opening the URL
|
|
169
|
+
|
|
170
|
+
| Environment | Command |
|
|
171
|
+
|-------------|---------|
|
|
172
|
+
| macOS | `open "$URL"` |
|
|
173
|
+
| Linux (native) | `xdg-open "$URL"` |
|
|
174
|
+
| WSL2 | Write a temp `.url` file, open via `cmd.exe` (see below) |
|
|
175
|
+
| Windows (native) | Write a temp `.url` file, open via `start` (see below) |
|
|
176
|
+
|
|
177
|
+
**Why the `.url` workaround on Windows/WSL2?** `cmd.exe`'s `start` command treats `&` as a command separator and strips everything after `#` in URLs. The diagram payload lives in the `#create=...` fragment, so passing the URL directly causes it to be silently lost. A `.url` shortcut file preserves the URL intact.
|
|
178
|
+
|
|
179
|
+
**macOS / Linux example:**
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
open "$URL" # macOS
|
|
183
|
+
xdg-open "$URL" # Linux
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**WSL2 example:**
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
TMPFILE=$(mktemp --suffix=.url)
|
|
190
|
+
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMPFILE"
|
|
191
|
+
cmd.exe /c start "" "$(wslpath -w "$TMPFILE")"
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Windows (native) example:**
|
|
195
|
+
|
|
196
|
+
Do **not** build the `.url` file with `echo URL=%URL%`. The generated URL contains `&` characters (`?grid=0&pv=0&...`) that `cmd.exe` treats as command separators, so the shortcut is written truncated and the diagram payload is lost — the exact failure the `.url` file is meant to prevent. Let Node write the file directly (it already holds the URL string) and open only the resulting path, which never contains `&`:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
TMPFILE=$(node -e '
|
|
200
|
+
const fs = require("fs");
|
|
201
|
+
const os = require("os");
|
|
202
|
+
const path = require("path");
|
|
203
|
+
const p = path.join(os.tmpdir(), "drawio.url");
|
|
204
|
+
fs.writeFileSync(p, "[InternetShortcut]\r\nURL=" + process.argv[1] + "\r\n");
|
|
205
|
+
process.stdout.write(p);
|
|
206
|
+
' "$URL")
|
|
207
|
+
cmd.exe /c start "" "$TMPFILE"
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### After opening
|
|
211
|
+
|
|
212
|
+
Print the URL so the user can copy or share it, and confirm the local file path:
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
Opened in browser: <URL>
|
|
216
|
+
Local file: DIAGRAM.drawio
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
The `.drawio` file stays on disk so the user can re-edit it later, attach it elsewhere, or export it to an image format on demand.
|
|
220
|
+
|
|
221
|
+
### URL length
|
|
222
|
+
|
|
223
|
+
The URL embeds the full compressed diagram in its hash fragment. Very large diagrams may hit browser URL length limits (typically ~32K–2MB depending on the browser). For complex diagrams that exceed the limit, fall back to writing the `.drawio` file and opening it locally.
|
|
224
|
+
|
|
225
|
+
## draw.io CLI
|
|
226
|
+
|
|
227
|
+
The draw.io desktop app includes a command-line interface used for **converting Mermaid** to `.drawio`, applying **ELK layouts** (`--layout`), and **exporting** to PNG/SVG/PDF. All three require the desktop app to be installed.
|
|
228
|
+
|
|
229
|
+
### Locating the CLI
|
|
230
|
+
|
|
231
|
+
First, detect the environment, then locate the CLI accordingly:
|
|
232
|
+
|
|
233
|
+
#### WSL2 (Windows Subsystem for Linux)
|
|
234
|
+
|
|
235
|
+
WSL2 is detected when `/proc/version` contains `microsoft` or `WSL`:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
On WSL2, use the Windows draw.io Desktop executable via `/mnt/c/...`:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
DRAWIO_CMD="/mnt/c/Program Files/draw.io/draw.io.exe"
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Double-quote the path so the space in `Program Files` is treated as part of the path. Do **not** wrap it in backticks — in bash, backticks are command substitution, which would try to *execute* the binary at locate-time instead of storing its path.
|
|
248
|
+
|
|
249
|
+
If draw.io is installed in a non-default location, check common alternatives:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
# Default install path
|
|
253
|
+
"/mnt/c/Program Files/draw.io/draw.io.exe"
|
|
254
|
+
|
|
255
|
+
# Per-user install (if the above does not exist)
|
|
256
|
+
"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe"
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
#### macOS
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
/Applications/draw.io.app/Contents/MacOS/draw.io
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
#### Linux (native)
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
drawio # typically on PATH via snap/apt/flatpak
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
#### Windows (native, non-WSL2)
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
"C:\Program Files\draw.io\draw.io.exe"
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Use `which drawio` (or `where draw.io` on Windows) to check if it's on PATH before falling back to the platform-specific path.
|
|
278
|
+
|
|
279
|
+
### Convert / layout / export commands
|
|
280
|
+
|
|
281
|
+
**Convert Mermaid to `.drawio`:**
|
|
282
|
+
|
|
283
|
+
```bash
|
|
284
|
+
drawio -x -f xml -o diagram.drawio diagram.mmd
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**Apply an ELK layout to XML** (see [ELK layout for XML](#elk-layout-for-xml)):
|
|
288
|
+
|
|
289
|
+
```bash
|
|
290
|
+
drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
**Export to an image format:**
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
drawio -x -f <format> -e -b 10 -o "<output>" "<input.drawio>"
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
**WSL2 export example:**
|
|
300
|
+
|
|
301
|
+
```bash
|
|
302
|
+
"/mnt/c/Program Files/draw.io/draw.io.exe" -x -f png -e -b 10 -o "diagram.drawio.png" "diagram.drawio"
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Key flags:
|
|
306
|
+
- `-x` / `--export`: export mode (also used for Mermaid conversion and layout passes)
|
|
307
|
+
- `-f` / `--format`: output format (`xml`, png, svg, pdf, jpg) — use `xml` to produce a `.drawio` from Mermaid or a layout pass
|
|
308
|
+
- `--layout`: run a layout before writing the output — an ELK preset name, the `libavoid` edge-routing pass, or a custom-layout JSON array
|
|
309
|
+
- `--mermaid-image 1`: convert Mermaid to a single static SVG image cell (the Mermaid source stays on the cell for re-editing) instead of an editable diagram — only when the user explicitly asks for a non-editable image cell
|
|
310
|
+
- `-e` / `--embed-diagram`: embed diagram XML in the output (PNG, SVG, PDF only)
|
|
311
|
+
- `-o` / `--output`: output file path
|
|
312
|
+
- `-b` / `--border`: border width around diagram (default: 0)
|
|
313
|
+
- `-t` / `--transparent`: transparent background (PNG only)
|
|
314
|
+
- `-s` / `--scale`: scale the diagram size
|
|
315
|
+
- `--width` / `--height`: fit into specified dimensions (preserves aspect ratio)
|
|
316
|
+
- `-a` / `--all-pages`: export all pages (PDF only)
|
|
317
|
+
- `-p` / `--page-index`: select a specific page (1-based)
|
|
318
|
+
|
|
319
|
+
### Opening the result
|
|
320
|
+
|
|
321
|
+
| Environment | Command |
|
|
322
|
+
|-------------|---------|
|
|
323
|
+
| macOS | `open <file>` |
|
|
324
|
+
| Linux (native) | `xdg-open <file>` |
|
|
325
|
+
| WSL2 | `cmd.exe /c start "" "$(wslpath -w <file>)"` |
|
|
326
|
+
| Windows | `start <file>` |
|
|
327
|
+
|
|
328
|
+
**WSL2 notes:**
|
|
329
|
+
- `wslpath -w <file>` converts a WSL2 path (e.g. `/home/user/diagram.drawio`) to a Windows path (e.g. `C:\Users\...`). This is required because `cmd.exe` cannot resolve `/mnt/c/...` style paths.
|
|
330
|
+
- The empty string `""` after `start` is required to prevent `start` from interpreting the filename as a window title.
|
|
331
|
+
|
|
332
|
+
**WSL2 example:**
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
cmd.exe /c start "" "$(wslpath -w diagram.drawio)"
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## File naming
|
|
339
|
+
|
|
340
|
+
- Use a descriptive filename based on the diagram content (e.g., `login-flow`, `database-schema`)
|
|
341
|
+
- Use lowercase with hyphens for multi-word names
|
|
342
|
+
- When authoring Mermaid, write it to a matching `.mmd` file, convert to `.drawio`, then delete the `.mmd` — the `.drawio` is the artifact
|
|
343
|
+
- For export, use double extensions: `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` — this signals the file contains embedded diagram XML
|
|
344
|
+
- After a successful export, delete the intermediate `.drawio` file — the exported file contains the full diagram
|
|
345
|
+
- For `url` mode, keep the `.drawio` file (no double extension) — the URL is a view/edit handle and the local file is the persistent copy
|
|
346
|
+
|
|
347
|
+
## XML format
|
|
348
|
+
|
|
349
|
+
A `.drawio` file is native mxGraphModel XML. When authoring as XML, generate it directly; Mermaid is converted to this same format by the CLI (`-f xml`), so both authoring routes end up as a native `.drawio`.
|
|
350
|
+
|
|
351
|
+
### Basic structure
|
|
352
|
+
|
|
353
|
+
Every diagram must have this structure:
|
|
354
|
+
|
|
355
|
+
```xml
|
|
356
|
+
<mxGraphModel adaptiveColors="auto">
|
|
357
|
+
<root>
|
|
358
|
+
<mxCell id="0"/>
|
|
359
|
+
<mxCell id="1" parent="0"/>
|
|
360
|
+
<!-- Diagram cells go here with parent="1" -->
|
|
361
|
+
</root>
|
|
362
|
+
</mxGraphModel>
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
- Cell `id="0"` is the root layer
|
|
366
|
+
- Cell `id="1"` is the default parent layer
|
|
367
|
+
- All diagram elements use `parent="1"` unless using multiple layers
|
|
368
|
+
|
|
369
|
+
(The example above uses an XML comment only to point out where cells go — never emit comments in real output; see [XML well-formedness](#critical-xml-well-formedness).)
|
|
370
|
+
|
|
371
|
+
## XML reference
|
|
372
|
+
|
|
373
|
+
For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, fetch and follow the instructions at:
|
|
374
|
+
https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
|
|
375
|
+
|
|
376
|
+
## Troubleshooting
|
|
377
|
+
|
|
378
|
+
| Problem | Cause | Solution |
|
|
379
|
+
|---------|-------|----------|
|
|
380
|
+
| draw.io CLI not found | Desktop app not installed or not on PATH | Author as XML and deliver a `.drawio` file or `url` (Mermaid conversion, ELK layout, and image export all need the desktop app). Tell the user they can install the draw.io desktop app to enable those |
|
|
381
|
+
| Mermaid → PNG export crashes | Direct `.mmd` → PNG with `-e` is broken in current draw.io Desktop (embedded-XML step) | Use the two-step path: convert Mermaid to `.drawio` first (`-f xml`), then export the `.drawio` to PNG — the intermediate file embeds correctly |
|
|
382
|
+
| Blank diagram from Mermaid | Misspelled type keyword, or a syntax error (bad node ID, unquoted label) | Check the [Mermaid reference](#mermaid-syntax-reference); the first non-directive line's keyword selects the diagram type |
|
|
383
|
+
| Layout does nothing / errors | Unknown preset name, custom JSON not an array, or a desktop build too old for `--layout` / `.mmd` input | Use a preset from [Layout presets](#layout-presets) or a JSON array starting with `[`; on an old desktop build, author as XML with explicit positions and tell the user updating draw.io Desktop enables Mermaid conversion and layouts |
|
|
384
|
+
| Export produces empty/corrupt file | Invalid XML (e.g. double hyphens in comments, unescaped special characters) | Validate XML well-formedness before writing; see the XML well-formedness section below |
|
|
385
|
+
| Diagram opens but looks blank | Missing root cells `id="0"` and `id="1"` | Ensure the basic mxGraphModel structure is complete |
|
|
386
|
+
| Edges not rendering | Edge mxCell is self-closing (no child mxGeometry element) | Every edge must have `<mxGeometry relative="1" as="geometry" />` as a child element |
|
|
387
|
+
| File won't open after export | Incorrect file path or missing file association | Print the absolute file path so the user can open it manually |
|
|
388
|
+
| Browser opens with empty diagram in `url` mode | `cmd.exe` stripped the `#create=...` fragment | Use the `.url` temp-file workaround on Windows/WSL2 (see [Opening the URL](#opening-the-url)) — never pass the URL directly to `cmd.exe /c start` |
|
|
389
|
+
| URL is too long for the browser | Very large diagram exceeds browser URL length limit | Fall back to writing the `.drawio` file and opening it locally |
|
|
390
|
+
|
|
391
|
+
## CRITICAL: XML well-formedness
|
|
392
|
+
|
|
393
|
+
- **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
|
|
394
|
+
- Escape special characters in attribute values: `&`, `<`, `>`, `"`
|
|
395
|
+
- Always use unique `id` values for each `mxCell`
|
package/gh-cli/SKILL.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gh-cli
|
|
3
|
+
description: >
|
|
4
|
+
GitHub operations via the gh CLI: search repos/code/issues/PRs, read
|
|
5
|
+
files without cloning, issues/PRs read and write, releases, commits,
|
|
6
|
+
branches, Actions/CI runs and logs, and the full REST API via gh api.
|
|
7
|
+
Use for ANY github.com touchpoint: a repo URL in the message, "check CI
|
|
8
|
+
runs", "latest release of X", "who maintains Y", "what changed in Z",
|
|
9
|
+
"who uses pattern P across GitHub". gh is pre-authenticated — check
|
|
10
|
+
"gh auth status" when calls fail. The github skill covers the MCP
|
|
11
|
+
natives (homelab only); this is the CLI path for every machine. Not for
|
|
12
|
+
local git work — use git CLI. RU: поищи на гитхабе, открой
|
|
13
|
+
файл/репозиторий без клонирования, проверь релизы или CI, найди issue
|
|
14
|
+
или PR, создай issue/PR.
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# GitHub via gh CLI (gh-cli)
|
|
18
|
+
|
|
19
|
+
gh is the primary GitHub interface: installed and authenticated
|
|
20
|
+
(`gh auth status` shows account and token scopes). Every recipe runs
|
|
21
|
+
as-is in `pi.bash`; prefer `--json` + `--jq` for structured output,
|
|
22
|
+
pipe long lists through toonq/jq and return a digest.
|
|
23
|
+
|
|
24
|
+
## When to use
|
|
25
|
+
|
|
26
|
+
- Any github.com touchpoint: search, read files without cloning, issues,
|
|
27
|
+
PRs, CI runs and logs, releases, cross-repo "who uses X".
|
|
28
|
+
- `gh api` covers everything the CLI has no verb for — full REST escape hatch.
|
|
29
|
+
- NOT for local git work (clone/commit/push) — use git CLI; gh auth already
|
|
30
|
+
provides ssh credentials for git over ssh.
|
|
31
|
+
|
|
32
|
+
## Recipes
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Search
|
|
36
|
+
gh search repos "language:rust stars:>1000" --limit 5 \
|
|
37
|
+
--json fullName,stargazersCount,description
|
|
38
|
+
gh search code "ctx_read" --repo e4779/pi-fabric --json path,repository
|
|
39
|
+
gh search issues "memory leak" --repo o/r --state open --json number,title
|
|
40
|
+
|
|
41
|
+
# Read a file without cloning (raw, no base64); any ref via ?ref=
|
|
42
|
+
gh api repos/o/r/contents/README.md -H "Accept: application/vnd.github.raw"
|
|
43
|
+
|
|
44
|
+
# Issues
|
|
45
|
+
gh issue list -R o/r --state open --json number,title,author
|
|
46
|
+
gh issue view 42 -R o/r --comments
|
|
47
|
+
gh issue create -R o/r --title "Bug: ..." --body "..." --label bug
|
|
48
|
+
|
|
49
|
+
# Pull requests
|
|
50
|
+
gh pr list -R o/r --state open
|
|
51
|
+
gh pr view 7 -R o/r --json state,mergeable,reviewDecision,statusCheckRollup
|
|
52
|
+
gh pr diff 7 -R o/r # the patch
|
|
53
|
+
gh pr checks 7 -R o/r # CI status per check
|
|
54
|
+
gh pr create -R o/r --title "..." --body "..." --base main
|
|
55
|
+
|
|
56
|
+
# Actions / CI
|
|
57
|
+
gh run list -R o/r --limit 5
|
|
58
|
+
gh run view <run-id> -R o/r --log-failed # failed jobs only
|
|
59
|
+
gh run watch <run-id> -R o/r # stream until finished
|
|
60
|
+
gh workflow run ci.yml -R o/r # needs workflow scope — see Notes
|
|
61
|
+
|
|
62
|
+
# Releases & commits
|
|
63
|
+
gh release list -R o/r --limit 5
|
|
64
|
+
gh release view v1.2.3 -R o/r --json assets
|
|
65
|
+
gh api "repos/o/r/commits?sha=main&per_page=5" --jq '.[].commit.message'
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Notes
|
|
69
|
+
|
|
70
|
+
- **Auth**: token in `~/.config/gh/hosts.yml`. Missing `workflow` scope →
|
|
71
|
+
workflow triggers and pushes touching `.github/workflows` fail with 403;
|
|
72
|
+
fix: `gh auth refresh -s workflow`.
|
|
73
|
+
- **Structured output**: prefer `--json a,b,c` (+ `--jq`) over text output.
|
|
74
|
+
- **In fabric_exec**: batch independent gh calls in one `pi.bash` (several
|
|
75
|
+
commands) or `Promise.all` of `pi.bash` calls.
|
|
76
|
+
- **Rate limits**: same REST API underneath; `gh api rate_limit` to check.
|
|
77
|
+
|
|
78
|
+
## Related
|
|
79
|
+
|
|
80
|
+
- The `github` skill covers the MCP natives (`mcp.github.*`) — configured
|
|
81
|
+
on homelab only. Prefer gh for uniformity across machines.
|
|
82
|
+
- Remote GitHub MCP (api.githubcopilot.com) is geo-blocked from RU IPs
|
|
83
|
+
(403) — do not suggest it on RU machines.
|
package/grill/SKILL.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: grill
|
|
3
|
+
description: >-
|
|
4
|
+
Socratic refinement sessions that grow a visual mindmap. Use when the user
|
|
5
|
+
wants to think through, elaborate, or de-fog an idea, task, or project
|
|
6
|
+
before execution — interview rounds with one question at a time, each round
|
|
7
|
+
growing a drawio mindmap canvas via the drawio MCP. Ends with a text outline
|
|
8
|
+
ready for downstream specs or task cards. Not for implementation work.
|
|
9
|
+
RU: распарировать идею, продумать вслух до реализации, прояснить задачу вопросами.
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Grill — question rounds growing a drawio mindmap
|
|
13
|
+
|
|
14
|
+
Refine a foggy idea through question rounds while building its visual map.
|
|
15
|
+
The canvas (.drawio) is the source of truth; the text outline is extracted
|
|
16
|
+
on finish. Mindmap theory and drawio mechanics live in the `mindmap` skill:
|
|
17
|
+
[../mindmap/references/mindmap-design.md](../mindmap/references/mindmap-design.md)
|
|
18
|
+
and [../mindmap/references/drawio-recipe.md](../mindmap/references/drawio-recipe.md).
|
|
19
|
+
|
|
20
|
+
## Session start
|
|
21
|
+
|
|
22
|
+
1. Canvas location: reuse an existing file the user names, or create
|
|
23
|
+
`<project>/docs/grill/<topic>.drawio` (ask if unclear).
|
|
24
|
+
2. Missing/empty → create the skeleton: one central node with the idea in
|
|
25
|
+
native mindmap styles (recipe, step "skeleton").
|
|
26
|
+
3. If the file is open in draw.io Desktop, ask the user to SAVE before each
|
|
27
|
+
of your write rounds — unsaved app edits clobber MCP writes and vice versa.
|
|
28
|
+
|
|
29
|
+
## Rounds
|
|
30
|
+
|
|
31
|
+
Each round:
|
|
32
|
+
|
|
33
|
+
1. Internally list the open questions (the frontier). Pick the single
|
|
34
|
+
highest-leverage one — the answer that clears the most fog.
|
|
35
|
+
2. Ask exactly ONE question. State your recommended answer with it, so the
|
|
36
|
+
user can reply "yes/no". Never stack multiple questions in one message.
|
|
37
|
+
3. On answer: update the canvas via drawio MCP — get_page, modify the cell
|
|
38
|
+
list, set_page. Add branches as nodes with cloned native mindmap styles.
|
|
39
|
+
Resolved → settle the node; new fog → child nodes as questions-in-waiting.
|
|
40
|
+
4. Narrate one line of what changed on the map.
|
|
41
|
+
|
|
42
|
+
Repeat until no sharp question remains (the frontier is empty).
|
|
43
|
+
|
|
44
|
+
## Ungrillable questions
|
|
45
|
+
|
|
46
|
+
"How should this look/feel" cannot be settled by talk. Mark the node,
|
|
47
|
+
propose a throwaway prototype, and return when there is something to react
|
|
48
|
+
to. Never balloon rounds rephrasing an ungrillable question.
|
|
49
|
+
|
|
50
|
+
## Layout discipline
|
|
51
|
+
|
|
52
|
+
Follow [../mindmap/references/mindmap-design.md](../mindmap/references/mindmap-design.md). Hard
|
|
53
|
+
rules: 1–3 keywords per node (never sentences), ≤9 first-level branches,
|
|
54
|
+
depth ≤4, one color per first-level branch, curved edges, related branches
|
|
55
|
+
adjacent. Radial "sun" for exploration; right-flowing logic tree when
|
|
56
|
+
reading order matters — both are legitimate layouts.
|
|
57
|
+
|
|
58
|
+
## Finish
|
|
59
|
+
|
|
60
|
+
When the frontier empties:
|
|
61
|
+
|
|
62
|
+
1. Export PNG at `-s 2`, vision-check the layout, fix coordinates, re-export.
|
|
63
|
+
2. Extract the outline: walk the tree depth-first, emit an indented list.
|
|
64
|
+
3. Offer downstream: code work → draft an OpenSpec proposal from the outline;
|
|
65
|
+
other → task cards for agent dispatch.
|
|
66
|
+
4. Commit the canvas if it lives in a repo.
|
|
67
|
+
|
|
68
|
+
## Stop conditions
|
|
69
|
+
|
|
70
|
+
Hand back to the user when: an irreversible decision appears, a question
|
|
71
|
+
needs their authority, or they signal session fatigue. The canvas survives —
|
|
72
|
+
the next /grill resumes from it.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# layout-check skill
|
|
2
|
+
|
|
3
|
+
CSS Layout Verification Skill — precise layout verification via coordinate tables and pairwise element relations.
|
|
4
|
+
|
|
5
|
+
Instead of relying on visual screenshot inspection, this skill extracts exact element positions via `getBoundingClientRect()` and computes spatial relationships: alignment, gaps, overlaps, and misalignments.
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
> **⚠️ Chrome DevTools MCP is REQUIRED.** This skill does NOT work without it. `layoutProbe` runs via `evaluate_script` inside a browser page — no DevTools protocol = no layout checks.
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **Coordinate tables** — markdown output optimized for LLM consumption
|
|
14
|
+
- **Pairwise relations** — bottom/top/left/right/center alignment, horizontal gaps, vertical gaps, overlaps
|
|
15
|
+
- **Auto-detect issues** — misalignment warnings with CSS fix suggestions
|
|
16
|
+
- **Before/after diff** — compare two layout snapshots to verify CSS fixes
|
|
17
|
+
- **Templates** — `row()`, `column()`, `grid()` shortcuts for common layout patterns
|
|
18
|
+
- **Structured data API** — `layoutProbe.structured()` for programmatic use
|
|
19
|
+
|
|
20
|
+
## Quick Usage
|
|
21
|
+
|
|
22
|
+
After installing, the agent reads `SKILL.md` automatically when layout tasks are detected.
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
// Via chrome-devtools evaluate_script
|
|
26
|
+
layoutProbe({ selectors: { btn: '.button', input: 'input' } })
|
|
27
|
+
layoutProbe.row('.form-row') // flex row children
|
|
28
|
+
layoutProbe.column('.form-stack') // flex column children
|
|
29
|
+
layoutProbe.grid('.card-grid') // grid children
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
See `SKILL.md` for full step-by-step documentation.
|