@qvac/skills 0.1.11 → 0.1.13

package/skills/word/SKILL.md

@@ -1,135 +1,155 @@
 ---
 name: word
-description: Create, edit, or read Word (.docx) documents with python-docx — deliver documents as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images generated in the chat. Opens in Pages and Google Docs too.
+description: Create, edit, or read Word (.docx) documents — deliver documents as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images generated in the chat. Opens in Pages and Google Docs too.
 aliases: [docx, word-document, memo]
 preload_on_name: false
-tools: [exec(python)]
-platform: [darwin, linux, win32]
-metadata:
-  {
-    "openclaw":
-      {
-        "setup":
-          {
-            "summary": "Runs python-docx in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
-          }
-      }
-  }
+tools: [docx]
+platform: [darwin, linux, win32, ios, android]
 ---
 
 # Word
 
-Build, change, or read `.docx` documents. This file holds no Python and no
-recipe: it only says which reference file to load. Load exactly one with the
-`skill` tool, then do what that file says.
-
-## Which File to Load
-
-Pick the row by **what the user wants done**, then make that exact `skill`
-call. "Edit", "update", "modify", "change", "replace", "rewrite" and "fix" all
-mean the same thing here — the verb never picks the row, the change does.
-
-| The user wants                                                                                                                                   | The `skill` call                                     |
-| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
-| A new document — "write a report", "make a doc with 30 fun facts about cats", "draft a letter"                                                   | `{"name": "word", "file": "references/create.md"}`     |
-| Some paragraphs of an existing document changed — "replace the first 10 facts with dog facts", "change fact 3", "reword paragraph 7", "swap these bullets for those" | `{"name": "word", "file": "references/paragraphs.md"}` |
-| Anything else done to an existing document — add a section, remove or rewrite a whole section, make the text bigger, put an image in it          | `{"name": "word", "file": "references/rework.md"}`     |
-| An answer in the chat from an attached document — "summarize this", "what does it say about X"                                                 | `{"name": "word", "file": "references/read.md"}`       |
-
-- A document that already exists in this chat is never rebuilt with
-  `create.md` — that throws away everything the user has. Its `attachmentId`
-  is in the `exec` result that produced it or on the `[Attached file …]` line.
-- A summary delivered as a file is `read.md` first, then `create.md`.
-- `paragraphs.md` runs two scripts bundled with this skill and contains no
-  Python. `rework.md` and `create.md` carry the python-docx recipes to copy.
-
-Each load is a real `skill` tool call — printing the call as JSON or text in
-your reply loads nothing. Never write the Python from memory: the recipes carry
-rules (exact version pins, attachment staging, the only working removal idiom)
-that fail in non-obvious ways when improvised, and loading the file is one
-cheap read-only call.
-
-## When to Use
-
-- The user asks for a document, report, letter, memo, `.docx`, or Word file.
-- The user attaches a `.docx` and wants its content changed, replaced in part,
-  extended, trimmed, or reworked.
-- The user attaches a `.docx` and asks what it says — a summary, a question
-  answered, or content pulled out into the chat.
-- The user wants a document that embeds images generated in this chat.
-
-## When NOT to Use
-
-- The user wants text in the chat and no document is involved — just write it.
-  Summarizing or answering from an attached `.docx` **is** this skill: load
-  `references/read.md`.
-- The user wants slides or a deck — that is the presentations skill.
-- The user wants a spreadsheet or a PDF — python-docx writes only `.docx`.
-
-## What This Skill Cannot Do
-
-Say so instead of faking these; a fake is worse than a clear "not supported":
-
-- **No table of contents.** A real TOC is a Word field that Word itself computes;
-  python-docx cannot insert one. Do not fake a TOC by typing headings and page
-  numbers — the page numbers would be wrong. Offer headings (`Heading 1..9`)
-  instead; Word can generate a TOC from them later.
-- **No tracked changes or comments.** There is no revisions API. Edits land as
-  plain content; say that when the user asks for a redline.
-- **No legacy `.doc`.** Only `.docx`. A `.doc` output name is rejected — name it
-  `.docx`.
-- **No PDF export and no rendering.** The runtime cannot convert or preview the
-  document; it can only write the file.
+Every document job is one or two `docx` 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 document holds.
+
+## Pick the Call
+
+"Edit", "update", "change", "rewrite" and "fix" all mean the same thing here —
+the change picks the row, never the verb.
+
+| The user wants                                                                  | The calls                                                            |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| A new document — "write a report", "30 fun facts about cats", "draft a letter"   | one call: `create` + `ops` + `output`                                 |
+| A change whose words depend on the document — "replace the first 10 facts", "reword paragraph 7", "rewrite section 2" | read (`attachmentId` alone), then one edit call |
+| A mechanical change — "make the text bigger", "add this image at the end"       | one call: `attachmentId` + `ops` + `output`                           |
+| An answer in the chat — "summarize this", "what does it say about X"            | read (`attachmentId` alone), then reply in the chat — no second call  |
+| A summary of the document as a new file                                         | read, then one `create` call written from what the read returned     |
+
+A document already in this chat is never rebuilt with `create` — that throws
+away everything the user has. Its `attachmentId` is in the tool result that
+produced it, or on the user's `[Attached file …]` line:
+
+```
+[Attached file "report.docx" (application/vnd.openxmlformats-officedocument.wordprocessingml.document) — attachmentId: 4f9c2ab1]
+```
+
+Copy the id verbatim. Never make one up.
+
+## A New Document
+
+```json
+{
+  "create": { "title": "Cat Facts" },
+  "ops": [
+    { "op": "appendParagraphs", "paragraphs": [
+      { "text": "Cat Facts", "style": "Title" },
+      { "text": "Senses", "style": "Heading 1" },
+      { "text": "A cat's hearing reaches 64 kHz.", "style": "List Bullet" },
+      { "text": "Cats have about 200 million scent receptors.", "style": "List Bullet" },
+      { "text": "Sleep", "style": "Heading 1" },
+      { "runs": ["Cats sleep ", { "text": "12 to 16 hours", "bold": true }, " a day."] }
+    ] },
+    { "op": "addTable", "at": 6, "header": true, "rows": [["Breed", "Weight (kg)"], ["Siamese", 4], ["Maine Coon", 8]] }
+  ],
+  "output": "cat_facts.docx"
+}
+```
+
+A new document has the styles `Normal`, `Title`, `Subtitle`, `Heading 1`–`3`,
+`List Bullet`, `List Number`, `Quote` and `Table Grid`. `create` also takes
+`"page": "a4"` (the default is `letter`). Each bullet is its own paragraph —
+never type `-`, `•` or `1.` in front of it; the style draws the bullet.
+
+## Reading a Document
+
+```json
+{ "attachmentId": "4f9c2ab1" }
+```
+
+It returns the body as numbered **blocks** — paragraphs and tables in document
+order, counted from 0 — each with its style, text, heading level, and whether
+it is a list item; tables come back as rows of cell text. You cannot write a
+summary or a replacement in the same call that reads, because the words are
+fixed before the document is opened. Read, then write from what came back.
+
+Only body paragraphs (`Normal`, `List Bullet`, `List Number`) are facts,
+points or bullets. "The first 10 facts" are the first 10 body blocks after the
+heading that introduces them — not blocks 0 to 9.
+
+## Editing a Document
+
+```json
+{
+  "attachmentId": "4f9c2ab1",
+  "ops": [
+    { "op": "setText", "index": 3, "text": "Dogs have about 1,700 taste buds." },
+    { "op": "setText", "index": 4, "text": "A dog's nose print is unique, like a fingerprint." }
+  ],
+  "output": "report_revised.docx"
+}
+```
+
+"Replace the first 10 facts" is 10 `setText` ops, each a different sentence.
+Every `index` is a block index from the read.
+
+| The change                          | The op                                                                                          |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Replace a paragraph's text          | `{ "op": "setText", "index": 3, "text": "New sentence." }`                                       |
+| Bold part of a paragraph            | `{ "op": "setText", "index": 3, "text": { "runs": ["Revenue grew ", { "text": "15%", "bold": true }] } }` |
+| Insert paragraphs before a block    | `{ "op": "insertParagraphs", "at": 6, "paragraphs": ["East opened", "West grew too"] }`          |
+| Add paragraphs at the end           | `{ "op": "appendParagraphs", "paragraphs": [{ "text": "Appendix", "style": "Heading 1" }, "Notes."] }` |
+| Rewrite a whole section             | `{ "op": "replaceSection", "index": 8, "title": "Spending", "body": ["Spending fell.", "Contracts ended."] }` |
+| Remove a whole section              | `{ "op": "deleteSection", "index": 11 }`                                                         |
+| Remove some blocks                  | `{ "op": "deleteBlocks", "index": 5, "count": 2 }`                                               |
+| Make all the text bigger            | `{ "op": "formatStyle", "name": "Normal", "format": { "size": 12 } }`                           |
+| Format one paragraph                | `{ "op": "formatParagraph", "index": 2, "format": { "italic": true, "align": "center" } }`      |
+| Change a table cell                 | `{ "op": "setCell", "index": 10, "row": 1, "column": 2, "text": "38%" }`                         |
+| Add a table row                     | `{ "op": "addRow", "index": 10, "values": ["Headcount", 120, 115] }`                             |
+| Add a picture                       | `{ "op": "addImage", "at": 12, "image": { "attachmentId": "9be07c12" }, "width": 5.5, "align": "center" }` |
+| Add a chart                         | `{ "op": "addChart", "at": 9, "type": "column", "categories": ["Q1", "Q2"], "series": [{ "name": "2026", "values": [11, 13] }] }` |
+
+A section is a heading and everything under it up to the next heading of the
+same or higher rank, tables included — `replaceSection` and `deleteSection`
+take the heading's block index. A plain string paragraph takes the formatting
+of the paragraph before it, so a new bullet after a bullet is a bullet. A
+`style` must be one the document has; the error lists the ones it does.
+`width` is inches; give it alone and the picture keeps its shape.
+
+Name the output after the document you opened: `report.docx` →
+`report_revised.docx`. Never the input's own name, and never a fresh name taken
+from the new content.
+
+## 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 document, never the recipe. Do NOT
-print the python source in chat, do NOT tell the user to install python-docx,
-run a script, or open a terminal — they have no terminal in this chat and the
-code would not run there. The document 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.
-
-**Success = stop.** When `exitCode` is `0` and the result's `attachments`
-lists the `.docx`, the document is done. Do not call `exec` again for the same
-request — not to "confirm", not to "improve", not to "add the image" after the
-fact. Exactly one successful _build_ `exec` per document 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 it. Reply with a single
-line: file name + the count line from stdout. If the result has
-`missingOutputs` instead, the file was never written: read stderr first — an
-`AssertionError` there means a guard stopped the save on purpose (see the
-rework recipe); 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.** An error in your code is
-never a fault in python-docx or in the runtime; fix the Python against the
-loaded reference file's recipes and Errors and call `exec` again. A bundled
-script that stops with a message is fixed by correcting its arguments and
-rerunning the same script — never by writing Python in its place. If two
-consecutive calls fail with the same error, re-read the traceback
-line-by-line before a third — retrying the identical `command`, or a version
-with only cosmetic changes, is a loop, not a fix. Do not switch package pins
-(keep `python-docx==1.2.0`), do not wrap source in `python -c` / `pip` /
-shell, do not "debug" with `os.listdir` or no-op scripts while `outputs`
-still lists the document, and do not write the document as markdown/chat text
-instead of a `.docx`. Never search the web about an error; the answer is
-always in the `exec` result you already have.
-
-**The runtime is sealed.** There is no shell — `ls`, `cat`, and `file` raise
-`SyntaxError` because `command` is Python source — and no network:
-`requests`, `urllib`, and `socket` all fail. The working directory starts
-empty on every call: a file from an earlier call is gone unless staged again,
-and a file you write but do not declare in `outputs` is discarded. The `exec`
-result is the only account of what happened — there is no filesystem to check
-and no shell to check it with.
-
-**Never overwrite a staged input.** Changes always save a new output name,
-derived from the document changed — `report.docx` becomes `report_revised.docx`,
-never a fresh name taken from the new content.
-
-**A change happens inside the document.** `add_paragraph` and `add_heading`
-append at the end and nowhere else, so replacing content that is already there
-means rewriting those paragraphs, not adding new ones. Delivering the original
-with the new version appended, or a fresh document holding only the new
-content, is a failed turn.
+**You build it, not the user.** The document exists only when a `docx` call
+with `ops` returns its attachment. Never write it 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 what changed — and call nothing else.
+
+**A change happens inside the document.** Replacing text that is already there
+is `setText` or `replaceSection` on those blocks, never new paragraphs appended
+at the end.
+
+**Errors name the fix.** A failed call returns a message that says what exists
+— the block count, the styles, the sections. Correct that one op and call
+again. Never repeat an identical call.
+
+## What This Cannot Do
+
+Say so instead of faking it:
+
+- **No table of contents.** Offer headings instead; Word can build one from them.
+- **No tracked changes or comments.** Edits land as plain content.
+- **No footnotes, and headers and footers can be read but not written.**
+- **No legacy `.doc`, and no PDF export.**