@qvac/skills 0.1.11 → 0.1.12

package/skills/presentations/SKILL.md

@@ -1,118 +1,142 @@
 ---
 name: presentations
-description: Create, edit, or read PowerPoint (.pptx) decks with python-pptx — deliver decks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images the user attached to the chat as well as images generated in it.
-tools: [exec(python)]
-platform: [darwin, linux, win32]
-metadata:
-  {
-    "openclaw":
-      {
-        "setup":
-          {
-            "summary": "Runs python-pptx in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
-          }
-      }
-  }
+description: Create, edit, or read PowerPoint (.pptx) decks — deliver decks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images the user attached to the chat as well as images generated in it.
+tools: [pptx]
+platform: [darwin, linux, win32, ios, android]
 ---
 
 # Presentations
 
-Build, edit, or read `.pptx` decks by running python-pptx through the `exec`
-tool with `language: "python"`. Declare a produced deck in `outputs` and it
-comes back as a chat attachment the user can save — exactly like a
-`generate_image` result, the `exec` result carries
-`attachments: [{ attachmentId, fileName, byteLength }]`. To answer *from* a
-deck instead of building one, run a read call alone — 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.
-
-- **Building a new deck** (no existing deck involved; includes embedding
-  images generated or uploaded in this chat): call the `skill` tool with
-  `name: "presentations"` and `file: "references/create.md"`.
-- **Editing a deck already in this chat** (retitle, recolor, add or revise
-  slides on a deck the user attached or a prior call built): call the `skill`
-  tool with `name: "presentations"` and `file: "references/edit.md"`.
-- **Answering from an attached deck** (a summary, a question answered,
-  content pulled into the chat — no file produced): call the `skill` tool
-  with `name: "presentations"` and `file: "references/read.md"`.
-- **A summary delivered as a new file** is a read followed by a build: load
-  both `references/read.md` and `references/create.md`.
-
-Never write the Python from memory. The recipes carry required rules (typed
-`Inches`/`Pt` lengths, layout reuse, the read-before-edit flow, exact version
-pins, attachment staging) 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 presentation, deck, slides, `.pptx`, PowerPoint, or Keynote-openable file.
-- The user attaches a `.pptx` and asks what it says — a summary, a question
-  answered, or content pulled out into the chat.
-- The user wants a slide deck that embeds images generated in this chat.
-- The user attaches an image — a photo, a logo, a screenshot — and wants it on a
-  slide. You can see the image, and you can also stage the file it came from:
-  load `references/create.md` (new deck) or `references/edit.md` (existing
-  deck). Generating a lookalike instead is a failed turn.
-
-## When NOT to Use
-
-- The user wants markdown or a document in the chat and no deck is involved —
-  just write it. Summarizing or answering from an attached `.pptx` **is** this
-  skill: load `references/read.md`.
-- The user wants a single image — call `generate_image` alone.
+Every deck job is one or two `pptx` tool calls. A call with `ops` saves a new
+file named `output` and attaches it to the chat; a call without `ops` changes
+nothing and returns what the deck holds.
+
+## Pick the Call
+
+| The user wants                                                           | The calls                                                                  |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| A new deck — "make slides about …", "a deck with this image"             | one call: `create` + `ops` + `output`                                       |
+| A mechanical edit — "make the title red", "retitle slide 1 to …"          | one call: `attachmentId` + `ops` + `output`                                 |
+| An edit whose words depend on the deck — "add a summary slide", "fix typos" | read (`attachmentId` alone), then one edit call                            |
+| An answer in the chat — "summarize this deck", "what does slide 3 say?"   | read (`attachmentId` alone), then reply in the chat — no second call        |
+| A summary of the deck as a new file                                      | read, then one `create` call written from what the read returned           |
+
+A deck already in this chat is never rebuilt with `create` — that throws away
+every slide the user has. Its `attachmentId` is in the tool result that
+produced it, or on the user's `[Attached file …]` line:
+
+```
+[Attached file "quarterly.pptx" (application/vnd.openxmlformats-officedocument.presentationml.presentation) — attachmentId: 4f9c2ab1]
+```
+
+Copy the id verbatim. Never make one up.
+
+## A New Deck
+
+```json
+{
+  "create": { "size": "16:9" },
+  "ops": [
+    { "op": "addSlide", "layout": "Title Slide", "title": "Why the Sky Is Blue", "body": "Rayleigh scattering, in four points" },
+    { "op": "addSlide", "title": "What Happens", "body": [
+      "Sunlight carries every visible wavelength",
+      "Air scatters short wavelengths hardest",
+      { "text": "Blue scatters far more than red", "level": 1 },
+      "So the sky reads blue in every direction"
+    ] },
+    { "op": "addSlide", "layout": "Title Only", "title": "By Wavelength" },
+    { "op": "addChart", "slide": 2, "type": "column", "title": "Scattered light",
+      "categories": ["Blue", "Green", "Red"], "series": [{ "name": "Relative", "values": [5.5, 3.1, 1] }] }
+  ],
+  "output": "sky.pptx"
+}
+```
+
+Layouts in a new deck: `Title Slide`, `Title and Content` (the default),
+`Section Header`, `Two Content`, `Title Only`, `Blank`. Each bullet is its own
+item in `body` — never type `-`, `•` or `1.` in front of it; the slide draws
+the bullet. Five bullets per slide at most; a sixth is a new slide titled
+`… (cont.)`.
+
+## Reading a Deck
+
+```json
+{ "attachmentId": "4f9c2ab1" }
+```
+
+It returns every slide with its index, layout and shapes — each shape's `id`,
+`name`, and its paragraphs or table rows — plus speaker notes. You cannot write
+a summary or a closing slide in the same call that reads, because the words
+are fixed before the deck is opened. Read, then write from what came back.
+
+## Editing a Deck
+
+```json
+{
+  "attachmentId": "4f9c2ab1",
+  "ops": [
+    { "op": "setText", "slide": 0, "shape": "title", "text": "Why the Sky Is Blue — Revised" },
+    { "op": "setStyle", "slide": 0, "shape": "title", "style": { "color": "C0392B", "bold": true } },
+    { "op": "addSlide", "title": "What Changed", "body": ["Retitled the cover", "Recoloured the title"] }
+  ],
+  "output": "quarterly-v2.pptx"
+}
+```
+
+Slides count from 0. A `shape` is `"title"`, `"subtitle"`, `"body"`, or the
+`id` a read returned.
+
+| The change                   | The op                                                                                     |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
+| Replace a shape's text       | `{ "op": "setText", "slide": 1, "shape": "body", "text": ["First", "Second"] }`             |
+| Replace one table cell       | `{ "op": "setCellText", "slide": 2, "shape": 4, "row": 1, "column": 1, "text": "450 nm" }` |
+| Size, colour, font, bold     | `{ "op": "setStyle", "slide": 0, "shape": "title", "style": { "size": 40, "font": "Georgia" } }` |
+| Add a slide like its neighbours | `{ "op": "addSlide", "title": "Next Steps", "body": ["Ship it"] }`                      |
+| Add a slide at a position    | `{ "op": "addSlide", "at": 1, "title": "Agenda", "body": ["Why", "How"] }`                 |
+| Delete a slide               | `{ "op": "deleteSlide", "slide": 3 }`                                                       |
+| Move a slide                 | `{ "op": "moveSlide", "from": 4, "to": 1 }`                                                 |
+| Add a picture                | `{ "op": "addPicture", "slide": 2, "image": { "attachmentId": "9be07c12" }, "width": 6 }`  |
+| Add a free text box          | `{ "op": "addTextBox", "slide": 5, "text": "Thanks", "style": { "size": 54, "align": "center" } }` |
+| Add a table                  | `{ "op": "addTable", "slide": 3, "rows": [["Band", "nm"], ["Blue", 450]], "header": true }` |
+| Change a chart's numbers     | `{ "op": "setChartData", "slide": 2, "shape": 4, "categories": ["Q1", "Q2"], "series": [{ "name": "2026", "values": [11, 13] }] }` |
+| Retitle a chart              | `{ "op": "setChartTitle", "slide": 2, "shape": 4, "title": "Revenue by quarter" }`          |
+| Solid background             | `{ "op": "setBackground", "slide": 5, "color": "101820" }`                                  |
+
+`addSlide` without `layout` copies the layout of the deck's last content slide,
+so the new slide matches its neighbours. Never pick `Blank` for an ordinary
+title-and-bullets slide on a deck the user gave you. Positions and sizes (`x`,
+`y`, `width`, `height`) are inches; give one of `width`/`height` and the
+picture keeps its shape. Colours are six hex digits, no `#`.
+
+Name the output after the deck you opened and bump a version: `quarterly.pptx`
+→ `quarterly-v2.pptx`, and an edit of that → `quarterly-v3.pptx`. Never the
+input's own name.
+
+## Images
+
+- An image this chat generated: `"image": { "attachmentId": "<id from the generate_image result>" }`.
+- An image the user attached to their latest message: `"image": {}` — an
+  uploaded image shows no id, and the empty form picks it up.
+- An image behind a URL cannot be downloaded. Say so, and ask the user to attach
+  it or offer `generate_image`.
 
 ## Rules for Every Job
 
-**You build it, not the user.** Deliver the deck, never the recipe. Do NOT
-print the python source in chat, do NOT tell the user to install python-pptx,
-run a script, or open a terminal — they have no terminal in this chat and the
-code would not run there. The deck exists only if an `exec` call with
-`outputs` succeeds and returns the attachment. Falling back to "here is the
-script, run it yourself" is a failed turn, and so is writing slides as
-markdown/chat text instead of the `.pptx` the user asked for — answering a
-*read* request as chat text is the read flow's finish, not this failure.
-
-**Success = stop.** When `exitCode` is `0` and `attachments` lists the
-`.pptx`, the deck is done. Do not call `exec` again for the same request —
-not to "confirm", not to "improve", not a second identical build; a second
-deck attach is rejected. Exactly one successful **build** `exec` per deck
-request — a no-`outputs` read delivers nothing and is not one of them: it
-belongs before the build on an edit, never after it, and on a read request it
-stands alone. Reply with a single line: file name + slide count from stdout.
-If the result has `missingOutputs` instead, the file was never written: 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, the fix from
-the first attempt did not land — re-read the traceback line-by-line before a
-third call; retrying the identical `command`, or a version with only cosmetic
-changes, is a loop, not a fix. An error in your code is never a fault in
-python-pptx or in the runtime: do not switch package pins or hunt a "more
-compatible" version — keep `packages: ["python-pptx==1.0.2"]` — do not wrap
-source in `python -c "…"`, `python3`, `pip`, or shell, and do not "debug" with
-`os.listdir`, `print`, or a non-deck script while `outputs` still lists the
-deck. Never search the web about an error; the answer is always in the result
-you already have.
-
-**The runtime is sealed.** There is no shell — `ls`, `cat` and `file` raise
-`SyntaxError`, because the `command` is Python source — and no filesystem to
-check outside the `exec` result. There is no network: `requests`, `urllib`,
-and `socket` all fail, and `http_request` returns truncated text, never image
-bytes — an image behind a URL cannot be downloaded; ask the user to attach it
-or offer `generate_image`. The working directory starts empty on every call:
-a file from an earlier call is gone unless staged again by its attachment id,
-and a file you write but do not declare in `outputs` is discarded.
-
-**Never overwrite a staged input.** An edit always saves under a new,
-version-bumped name — `deck.pptx` → `deck-v2.pptx` — and a corrected rebuild
-after a broken delivery goes out under the next version, never the name
-already attached this turn.
+**You build it, not the user.** The deck exists only when a `pptx` call with
+`ops` returns its attachment. Never write the slides as chat text instead, and
+never tell the user to run anything.
+
+**Success = stop.** When the result lists the attachment, reply with one line —
+the file name and the slide count — and call nothing else. Check `slides` in
+the result against the request first: one slide added to a 2-slide deck is
+`3`; `4` means an op ran twice, so fix the ops and send them again under the
+next version name.
+
+**Errors name the fix.** A failed call returns a message that says what exists
+— `slide 7 does not exist; the deck has 3 slides (0 to 2)`, or the shapes on
+the slide. Correct that one op and call again. Never repeat an identical call.
+
+## What This Cannot Do
+
+Say so instead of faking it: writing speaker notes, editing scatter, bubble or
+stock charts, SmartArt, and legacy `.ppt` files.

package/skills/sheet-music/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sheet-music
+description: Turn audio into sheet music. Transcribe a recording or a generated track into a score you can read, print, or open in any notation app.
+tools: [transcribe_music]
+platform: [darwin, linux, win32]
+---
+
+# Sheet music
+
+Call `transcribe_music` when the user wants notation for audio that already
+exists: sheet music, a score, the chords, the notes, the melody, "write this
+out". It reads an audio attachment from the chat and saves a `.musicxml` score,
+which the app shows as readable sheet music in the conversation with a PDF
+download; it also opens in MuseScore, Sibelius or Dorico.
+
+```json
+{ "title": "kitchen demo" }
+```
+
+**Do not invent an `attachmentId`.** An attached audio file never appears in the
+conversation with an id, so there is nothing to copy: leaving the field out is
+how you say "the track the user just attached".
+
+## When to Use
+
+- The user attached audio and wants it written out as notation.
+- A track was generated earlier in this chat and the user now asks for its sheet
+  music, chords, or notes.
+- The user asks what notes or chords are in a recording.
+
+## When NOT to Use
+
+- The user is asking for a *new* song — that is `generate_music`. If they want the
+  track and its sheet music together, call `generate_music` with
+  `sheetMusic: true` instead of making two calls.
+- The user wants spoken words written down — that is speech transcription, not
+  this.
+
+**If `transcribe_music` returns an error, report it and stop.** Never fall back to
+`generate_music`: that writes a brand new piece, and presenting it as the user's
+transcription is a lie about their own audio. The error text says what to change,
+usually to omit `attachmentId`, so read it and retry the same tool.
+
+## Parameters
+
+- `attachmentId` — **omit it** to transcribe the most recent audio in the chat,
+  which is what an attached track means. Pass one only to reach back to an older
+  track whose id a previous `generate_music` actually returned.
+- `title` — a short title, 2 to 5 words; it names the saved files.
+- `bpm` — pass it whenever the tempo is known. **If you generated the track in
+  this chat with a `bpm`, pass that same value here.** Tempo estimated from audio
+  is right about the beat but can land an octave off (60 where the track is 120),
+  and a known tempo removes that guess entirely.
+- `keyscale` — same idea for the key, e.g. `C minor`. Estimated when omitted.
+
+## What comes back
+
+The result names the score attachment and reports what was transcribed: `notes`,
+`bars`, `bpm`, `key`, how many artifacts were filtered out, and two flags worth
+reading before you reply:
+
+- `tempoFromRequest` — false means the tempo was estimated. Worth a word to the
+  user if the rhythm looks doubled or halved.
+- `melodyMissing` — nothing was found above middle C. Say so plainly: on a dense
+  mix the transcription captures the bass and the loudest lines, and the melody
+  is buried. Do not present that score as a full transcription.
+
+## Honesty about quality
+
+This is automatic transcription, not a human copyist, and the result depends
+almost entirely on how dense the audio is.
+
+- **A solo instrument or a small ensemble transcribes well.** Piano, guitar,
+  a single voice, a duo.
+- **A full band mix does not.** Distortion and cymbals mask everything in the
+  middle, so what survives is the bass line and whichever line is loudest.
+- Percussion is not pitched and is not transcribed.
+- Sustained notes are approximate: the score reads the right pitches with
+  quantized rhythm, not a performance-accurate transcription.
+
+Tell the user which of these they are getting rather than letting them discover
+it.
+
+## A track and its score together
+
+Sheet music never changes the track. Generate what the user asked for: their
+duration, their instrumentation, their genre.
+
+Dense or long material makes a crowded score, and that is worth saying. Before
+generating, when they have left the choice open, offer it: a sparse 30-60 second
+piece gives a score a person can actually read. After generating, say plainly
+what they got when the result comes back with `melodyMissing` or sixty-odd bars.
+Never quietly substitute something shorter or sparser than they asked for.