@qvac/skills 0.0.0 → 0.1.1

package/skills/diagrams/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: diagrams
+description: Draw diagrams in the chat - flowcharts, sequence, state and ER diagrams, Gantt charts, pie charts, mindmaps and timelines - written as Mermaid code blocks the app renders. Use when the user asks to draw, diagram, sketch, chart, plan, visualize, or map a process, flow, schedule, architecture, or relationship.
+aliases: [diagram, mermaid, flowchart, mindmap]
+platform: [darwin, linux, win32, ios, android]
+---
+
+# Diagrams
+
+Draw a diagram by writing one ```mermaid code block. The app renders it as a
+picture automatically - never describe the rendering, never apologize about
+being text-only, never paste ASCII art. A diagram, chart, or plan is ONLY a
+Mermaid block in your reply: never run `exec`, Python, matplotlib, or fpdf2,
+never call an image tool, and never deliver it as a PDF or image file.
+
+Your reply STARTS with the fence. No preamble, no plan, no "I'll create a
+diagram showing..." - never announce or describe a diagram instead of drawing
+it. Decide the type silently, load its recipe, write the code block, close its
+fence, then add one short sentence saying what it shows - after the closing
+fence, never inside it. A complete reply looks like this:
+
+```mermaid
+flowchart TD
+  A["User sends a message"] --> B{"Needs a tool?"}
+  B -->|yes| C["Run the tool"]
+  B -->|no| D["Answer directly"]
+```
+
+Flow of a message through the assistant.
+
+## Pick the Type, Then Load Its Recipe
+
+Each type's syntax lives in its own reference file, named by the Mermaid
+keyword. Pick the type from the ask, then call the `skill` tool with
+`name: "diagrams"` and `file: "references/<type>.md"` in the SAME turn you
+draw, BEFORE writing the fence - even when you drew another diagram earlier in
+this chat. Copy the recipe's syntax exactly; a diagram written from memory is
+the usual cause of a parse error. Each load is a real `skill` tool call -
+printing the call as JSON or text in your reply loads nothing. After the load,
+reply with the fenced block directly: no further tool calls of any kind.
+
+| The ask                                              | Type                | File                        |
+| ---------------------------------------------------- | ------------------- | --------------------------- |
+| steps, decisions, a process, "map / structure this"  | `flowchart TD`      | `references/flowchart.md`   |
+| a pipeline left to right                             | `flowchart LR`      | `references/flowchart.md`   |
+| a family tree, org chart, reporting lines            | `flowchart TD`      | `references/flowchart.md`   |
+| who calls whom over time, requests and replies       | `sequenceDiagram`   | `references/sequence.md`    |
+| modes and transitions                                | `stateDiagram-v2`   | `references/state.md`       |
+| tables and their relations                           | `erDiagram`         | `references/er.md`          |
+| code types, classes, inheritance                     | `classDiagram`      | `references/class.md`       |
+| a schedule or plan with durations                    | `gantt`             | `references/gantt.md`       |
+| dated events in order                                | `timeline`          | `references/timeline.md`    |
+| shares of a whole, percentages                       | `pie`               | `references/pie.md`         |
+| a brainstorm, idea tree, "mindmap"                   | `mindmap`           | `references/mindmap.md`     |
+
+Use `gitGraph` ONLY when the user names it. Never use experimental or beta
+diagram types, and never invent a keyword a recipe does not show.
+
+## Hard Rules (every type)
+
+- One diagram per code block, and the fence language is exactly `mermaid`. The
+  first line inside the fence is the type keyword from the table. Default to
+  ONE block; use two only when the recipe's budget forces an overview plus one
+  detail. Never more than two.
+- Except in mindmaps, node ids are letters, digits, and underscores, starting
+  with a letter, never reused. Mindmap nodes have no ids.
+- Except in mindmaps, every label with a space, punctuation, or brackets goes
+  in double quotes: `A["Send request (HTTP)"]`. Never leave bare `()[]{}` `:`
+  `;` inside a label. Mindmap labels are unquoted text.
+- Never write lowercase `end` as a node or label - write `"End"`. Line breaks
+  inside a label are `<br/>`, never `\n`.
+- No `%%{init}%%` directives, no `%%` comments, no `classDef` or `style`
+  lines. The app themes the diagram itself.
+- Keep every label at 40 characters or fewer, one node per concept, with its
+  attributes inside that node's label. Dates, roles, counts, and statuses are
+  never standalone nodes.
+- Syntax in one line per type, so a skimmed recipe still lands: flowchart
+  `A["x"] --> B{"y?"}` with `-->|yes|` labels; sequence `A->>B: msg` and
+  `B-->>A: reply`; state `[*] --> Idle` and `Idle --> Run : start`; pie
+  `"Sleep" : 8` (quoted label, plain number); gantt `Name :id, 2026-09-01, 5d`
+  or `after id`; timeline `2024 : Event`; mindmap `root[Topic]` then every
+  other line indented deeper than the root, unquoted, no ids (a line at the
+  root's indentation is a second root and fails).
+
+## When NOT to use
+
+- Images, scenes, logos, or anything artistic - use the `image-generation`
+  skill instead.
+- Plots of numeric data - use `pie` for shares, otherwise a markdown table.
+- Family trees, org charts, and reporting lines - `flowchart TD`, not
+  `mindmap`; a mindmap is for ideas around a topic, not people in a hierarchy.
+
+## If the diagram fails
+
+When a diagram cannot render, the app sends its parse error back to you once
+on its own, and the user may send it again. Re-load the type's recipe and fix
+by rewriting the ENTIRE code block, never a partial patch.
+
+| Error contains | Fix |
+| --- | --- |
+| `Lexical error` / `Unrecognized text` | Remove every backslash in front of a quote and rewrite the block |
+| `Expecting 'taskData'` | A gantt line is neither a header keyword nor a complete `Name :id, start, Nd` task - fix it or delete it |
+| `Expecting ...` at a flowchart or sequence label | Put the whole label in double quotes |
+| `got 'end'` | Rename the node label to `"End"` |
+| `Maximum text size` or edge limit | Shrink the diagram or split it in two |
+| `No diagram type detected` | Start the fence with one type keyword from the table |
+| `Duplicate id` | Give every node a fresh unique id |

package/skills/diagrams/references/class.md

@@ -0,0 +1,29 @@
+# Class Diagram
+
+For code types: classes, their members, inheritance.
+
+Budget: 7 classes.
+
+```mermaid
+classDiagram
+  class Animal {
+    +String name
+    +speak()
+  }
+  Animal <|-- Dog
+```
+
+Rules:
+
+- Members go inside `class Name { }`, one per line, `+` public and `-`
+  private, methods end with `()`.
+- Inheritance is `Parent <|-- Child`; composition `Whole *-- Part`;
+  association `A --> B`.
+- Class names are single tokens; no quotes, no `classDef` lines.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/er.md

@@ -0,0 +1,27 @@
+# ER Diagram
+
+For tables and their relations.
+
+Budget: 8 entities.
+
+```mermaid
+erDiagram
+  USER ||--o{ ORDER : "places"
+  ORDER ||--|{ LINE_ITEM : "contains"
+```
+
+Rules:
+
+- Entities are UPPER_CASE single tokens.
+- `||--o{` reads "one to zero-or-many"; `||--|{` "one to one-or-many";
+  `||--||` "one to one".
+- The relationship label follows the colon in plain double quotes typed directly (no backslash in front).
+- Attributes are optional; if used, list them inside `ENTITY { string name }`
+  blocks with one `type name` per line.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/flowchart.md

@@ -0,0 +1,33 @@
+# Flowchart
+
+For steps, decisions, processes, pipelines, and any "map this / structure
+this" ask - also family trees, org charts, and reporting lines. `flowchart TD`
+reads top-down; `flowchart LR` left-to-right for a pipeline.
+
+Budget: 12 nodes and 16 edges. Over budget, simplify; if the detail is
+essential, one overview block plus one detail block, never more.
+
+```mermaid
+flowchart LR
+  A["Request"] --> B{"Valid?"}
+  B -->|yes| C["Process"]
+  B -->|no| D["Reject with error"]
+  C --> E["Respond"]
+```
+
+Rules:
+
+- Nodes are `id["Label"]`; decisions are `id{"Question?"}` diamonds.
+- Arrows are always `-->`; the label form is `-->|yes|`. Never `->>` here.
+- Ids: letters, digits, underscores, starting with a letter, never reused.
+- Every label goes in plain double quotes `"`, 40 characters or
+  fewer, `<br/>` for a line break. Never write lowercase `end` - use `"End"`.
+- One node per person or concept, details inside its label; no separate nodes
+  for dates, roles, counts, or statuses.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/gantt.md

@@ -0,0 +1,38 @@
+# Gantt Chart
+
+For a schedule or plan with durations.
+
+Budget: 12 tasks across 4 sections.
+
+```mermaid
+gantt
+  title MVP delivery
+  dateFormat YYYY-MM-DD
+  excludes weekends
+  section Planning
+    Requirements      :a1, 2026-09-01, 5d
+    Design            :a2, after a1, 7d
+  section Build
+    Core platform     :b1, after a2, 21d
+    API               :b2, after a2, 17d
+  section Launch
+    Release           :c1, after b1, 2d
+```
+
+Rules:
+
+- The only header lines are `title`, `dateFormat YYYY-MM-DD`, `axisFormat`,
+  `excludes weekends`, and `section Name`. Nothing else is a header.
+- EVERY other line is a task and must be `Name :id, start, duration` - start
+  is a date or `after otherId`, duration is like `5d` or `2w`. A line that is
+  not one of these fails with `Expecting 'taskData'`.
+- No colons inside task names, no quotes, no arrows.
+- Ids are unique short tokens (`a1`, `b2`); `after` may name several ids
+  separated by spaces.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/mindmap.md

@@ -0,0 +1,35 @@
+# Mindmap
+
+For a brainstorm or idea tree around one topic. Not for people in a hierarchy
+- that is a `flowchart TD`.
+
+Budget: 3 levels, 10 nodes, 2-4 balanced top-level branches.
+
+```mermaid
+mindmap
+  root[Launch plan]
+    Marketing
+      Blog post
+      Social campaign
+    Engineering
+      Release build
+      Monitoring
+```
+
+Rules:
+
+- The first line is `mindmap`; the second is the rectangular `root[Topic]`.
+- One node per line, two more spaces of indentation per level; the tree shape
+  comes only from indentation. Every line after `root[...]` is indented deeper
+  than the root - a line at the root's indentation is a second root and fails
+  with `There can be only one root`.
+- Labels are unquoted plain text with no ids, no quotes, no arrows,
+  no brackets except the `root[...]` form.
+- One node per item with its details in that node; no attribute leaves.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/pie.md

@@ -0,0 +1,27 @@
+# Pie Chart
+
+For shares of a whole: hours in a day, budget split, percentages.
+
+Budget: 8 slices; combine the remainder as `"Other"`.
+
+```mermaid
+pie title Time spent
+  "Coding" : 60
+  "Review" : 25
+  "Meetings" : 15
+```
+
+Rules:
+
+- The first line is `pie title Your title` (or just `pie`).
+- Every slice is `"Label" : number` - the label in plain double quotes typed
+  directly (never unquoted, never with a backslash in front), then a
+  space-colon-space, then a plain number with no unit or `%` sign.
+- One slice per line; values need not add up to 100.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/sequence.md

@@ -0,0 +1,32 @@
+# Sequence Diagram
+
+For who calls whom over time: requests and replies between an app, a server,
+a browser, a service.
+
+Budget: 5 participants and 12 messages.
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Server
+  App->>Server: POST /login
+  Server-->>App: 200 with token
+  Note over App: stores the token
+```
+
+Rules:
+
+- Declare every `participant` first, as a bare name without quotes.
+- A call is `A->>B: message`; a reply is `B-->>A: message`. Never use the
+  flowchart `-->` arrow here.
+- A note is `Note over A: text` (or `Note over A,B: text`).
+- Message text follows the colon unquoted; keep it short. No backslashes anywhere.
+- No ids, no brackets, no `end` except to close a Mermaid `loop`/`alt` block
+  you opened.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/state.md

@@ -0,0 +1,30 @@
+# State Diagram
+
+For modes and transitions: a device, a job, a session moving between states.
+
+Budget: 8 states.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running : start
+  Running --> Idle : stop
+  Running --> [*] : shutdown
+```
+
+Rules:
+
+- The first line is exactly `stateDiagram-v2`.
+- `[*]` is both the start and the end marker.
+- A transition is `From --> To : label`; the label is optional and follows a
+  colon, unquoted.
+- State names are single words or `snake_case`; for a spaced display name use
+  `state "Waiting for input" as Waiting` once, then `Waiting` everywhere.
+- No backslashes, no `classDef`, no `%%` lines.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/diagrams/references/timeline.md

@@ -0,0 +1,28 @@
+# Timeline
+
+For dated events in order: a history, a roadmap already dated.
+
+Budget: 8 events.
+
+```mermaid
+timeline
+  title Product history
+  2024 : Prototype
+  2025 : Public beta : First paying customers
+  2026 : Version 1.0
+```
+
+Rules:
+
+- `title` first, then one line per period as `period : event`, with another
+  ` : event` for each extra event in the same period.
+- Periods are years, dates, or short phase names; events are short unquoted
+  text.
+- No arrows, no ids, no quotes.
+
+## Now draw
+
+This recipe is all you need. Your next output is the reply itself: one fenced
+Mermaid code block (fence language `mermaid`), then one sentence. Do not call
+any tool - not `exec`, not `skill` again, not an image tool. A tool call here
+means the diagram was never drawn.

package/skills/excel/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: excel
+description: Create, edit, or read Excel spreadsheets (.xlsx) with openpyxl — deliver workbooks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Computes values in Python; can also write live formulas and embed images. Opens in Numbers and Google Sheets too.
+aliases: [xlsx, spreadsheet, workbook]
+tools: [exec(python)]
+platform: [darwin, linux, win32]
+metadata:
+  {
+    "openclaw":
+      {
+        "setup":
+          {
+            "summary": "Runs openpyxl in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
+          }
+      }
+  }
+---
+
+# Excel
+
+Build or edit an `.xlsx` workbook by running openpyxl through the `exec` tool with
+`language: "python"`. Declare the workbook in `outputs` and it comes back as a chat
+attachment the user can save. To answer *from* a workbook instead of building one,
+run a read call — no `outputs` — and reply in the chat.
+
+## Load the Recipe File First
+
+This file contains no Python. The working recipes live in three reference files —
+load the one for the job with the `skill` tool BEFORE writing any Python, then
+copy its recipe and change the content:
+
+Each load is a real `skill` tool call — printing the call as JSON or text in
+your reply loads nothing.
+
+- **Creating a new workbook** (no existing file involved, including one that embeds
+  an image): call the `skill` tool with `name: "excel"` and
+  `file: "references/create.md"`.
+- **Editing an attached workbook** (change cells, add/insert/delete rows, columns or
+  sheets, or embed an image into one that already exists): call the `skill` tool with
+  `name: "excel"` and `file: "references/edit.md"`.
+- **Answering from an attached workbook** (a summary, a question answered,
+  values pulled into the chat — the deliverable is your reply, not a file): call
+  the `skill` tool with `name: "excel"` and `file: "references/read.md"`.
+- **Read then build** (e.g. "summarize this workbook into a new file"): load
+  `references/read.md` and the create or edit file — the read call runs first.
+
+Never write the Python from memory. The recipes carry required patterns (the
+fill-in template, staging rules, guard asserts) that fail in non-obvious ways
+when improvised; loading the file is one cheap read-only call.
+
+## When to Use
+
+- The user asks for a spreadsheet, workbook, `.xlsx`, Excel, or Numbers/Sheets-openable file.
+- The user attaches a spreadsheet and wants cells changed, rows/columns/sheets added or removed, or data extracted from it.
+- The user attaches a spreadsheet and asks what it holds — a summary, a question
+  answered, or values pulled out into the chat.
+- The user wants a workbook that embeds an image — one generated in this chat or
+  one they uploaded. Both recipe files carry it.
+
+## When NOT to Use
+
+- The user wants a table in the chat built from content already in the
+  conversation — no workbook involved — write a markdown table. Answering or
+  summarizing from an attached workbook **is** this skill: load
+  `references/read.md`.
+- The user wants a comma-separated text file only — write the `.csv` directly with Python's `csv` module (`.csv` is an allowed output), no openpyxl needed.
+
+## Values vs Formulas — decide before writing
+
+This runtime has no spreadsheet engine: openpyxl writes a formula as text and
+computes nothing. A formula cell has **no value** until the user opens the file
+in a spreadsheet app and it recalculates. So pick the mode from what the user
+wants:
+
+- **They want numbers** (a report, totals, statistics, cleaned data): compute in
+  Python and write **literal values**. This is the default.
+- **They want a live spreadsheet** (totals that update when they edit cells):
+  write formulas — and say so in the reply, because the formula cells look empty
+  in the chat preview: "the total is a live formula, so it shows up once you
+  open the file in Excel, Numbers, or Sheets."
+- Never write a formula and then read it back expecting a number, and never
+  "verify" a formula by reloading the file — there is nothing to verify.
+
+Writing both is fine: literal values everywhere, plus a `=SUM(...)` total row if
+the user wants it to stay live.
+
+## Rules for Every Job
+
+**You build it, not the user.** Deliver the workbook, never the recipe. Do NOT
+print the python source in chat, do NOT tell the user to install openpyxl, run
+a script, or open a terminal — they have no terminal in this chat and the code
+would not run there. The workbook exists only if an `exec` call with `outputs`
+succeeds and returns the attachment.
+
+**Success = stop.** When `exitCode` is `0` and `attachments` lists the `.xlsx`,
+the workbook is done — do not call `exec` again, not to "confirm", not to
+"improve", not to reload the file to "check the formulas". Exactly one
+successful *build* call per request (a no-`outputs` read that precedes a build
+delivers nothing and is not one of them, but it belongs before the build, never
+after). Reply with a single line: file name + the sheet/row summary from stdout.
+If the result has `missingOutputs`, read stderr first: an `AssertionError` there
+means a guard stopped the save on purpose and its message names what to fix;
+only when stderr is clean check the `save()` name matches the declared output
+and rerun once.
+
+**Failures are fixed in the code, not around it.** If a run fails, fix the
+Python against the loaded reference file's recipes and Errors table and call
+`exec` again. If two consecutive calls fail with the same error, re-read the
+traceback line-by-line before a third. An error is never a fault in openpyxl or
+the runtime — keep `packages: ["openpyxl==3.1.5"]`, never wrap source in
+`python -c` or shell, never "debug" with `os.listdir` or no-op scripts.
+
+**The runtime is sealed.** No shell (`ls`, `cat` raise `SyntaxError` — the
+`command` is Python source) and no network (`requests` and `urllib` fail — a
+URL to a spreadsheet cannot be downloaded; ask the user to attach the file).
+The working directory starts empty on every call: a file from an earlier call
+is gone unless staged again via `inputs`, and a file you write but do not
+declare in `outputs` is discarded.
+
+**Never overwrite a staged input.** Edits always save under a new output name.