@e4779/skills 0.0.0-stage → 0.1.1

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.
Files changed (57) hide show
  1. package/chrome-devtools/README.md +76 -0
  2. package/chrome-devtools/SKILL.md +277 -0
  3. package/chrome-devtools/references/recipes.md +379 -0
  4. package/chrome-devtools/references/setup.md +138 -0
  5. package/drawio/SKILL.md +395 -0
  6. package/gh-cli/SKILL.md +83 -0
  7. package/grill/SKILL.md +72 -0
  8. package/layout-check/README.md +32 -0
  9. package/layout-check/SKILL.md +416 -0
  10. package/layout-check/scripts/layoutProbe.mjs +539 -0
  11. package/mcpls/SKILL.md +261 -0
  12. package/mcpls/references/configuration.md +131 -0
  13. package/mcpls/references/install.md +13 -0
  14. package/mcporter/SKILL.md +90 -0
  15. package/mindmap/SKILL.md +46 -0
  16. package/mindmap/references/drawio-recipe.md +60 -0
  17. package/mindmap/references/mindmap-design.md +63 -0
  18. package/opensource-contribution/SKILL.md +119 -0
  19. package/package.json +33 -5
  20. package/shell-taste/.shellcheckrc +16 -0
  21. package/shell-taste/SKILL.md +95 -0
  22. package/shell-taste/references/handbook/dialects.md +168 -0
  23. package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
  24. package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
  25. package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
  26. package/shell-taste/references/handbook/dom/04-network.md +384 -0
  27. package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
  28. package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
  29. package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
  30. package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
  31. package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
  32. package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
  33. package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
  34. package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
  35. package/shell-taste/references/handbook/dom/13-containers.md +13 -0
  36. package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
  37. package/shell-taste/references/handbook/family-index.md +230 -0
  38. package/shell-taste/references/handbook/index.md +41 -0
  39. package/skill-author/SKILL.md +86 -0
  40. package/sobesednik/SKILL.md +98 -0
  41. package/sobesednik/card-template.md +23 -0
  42. package/sobesednik/personas/advocate.md +27 -0
  43. package/sobesednik/personas/analyst.md +29 -0
  44. package/sobesednik/personas/chat.md +42 -0
  45. package/sobesednik/personas/ifs.md +32 -0
  46. package/sobesednik/personas/journal/README.md +6 -0
  47. package/sobesednik/personas/nasreddin.md +29 -0
  48. package/sobesednik/personas/premortem.md +29 -0
  49. package/sobesednik/personas/rogers.md +27 -0
  50. package/sobesednik/personas/socratic.md +29 -0
  51. package/sobesednik/personas/stoic.md +27 -0
  52. package/sobesednik/references/persona-design.md +41 -0
  53. package/zai-mcp/README.md +63 -0
  54. package/zai-mcp/SKILL.md +160 -0
  55. package/zai-mcp/references/recipes.md +273 -0
  56. package/zai-mcp/references/tools.md +266 -0
  57. package/README.md +0 -3
@@ -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: `&amp;`, `&lt;`, `&gt;`, `&quot;`
395
+ - Always use unique `id` values for each `mxCell`
@@ -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.