@qvac/skills 0.0.0 → 0.1.1

package/skills/word/SKILL.md

@@ -0,0 +1,141 @@
+---
+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.
+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."
+          }
+      }
+  }
+---
+
+# Word
+
+Build, edit, or read `.docx` documents by running python-docx through the
+`exec` tool with `language: "python"`. Declare a produced document in
+`outputs` and it comes back as a chat attachment the user can save. To answer
+_from_ a document 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 four 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 document** (no existing `.docx` involved; may embed
+  images): call the `skill` tool with `name: "word"` and
+  `file: "references/create.md"`.
+- **Changing some of the facts, points, bullets, items, or paragraphs** of an
+  existing `.docx` — "replace the first 10 facts", "change fact 3", "swap the
+  bullets for these", "reword paragraph 7": call the `skill` tool with
+  `name: "word"` and `file: "references/replace.md"`. This is the file even
+  when the user says edit, replace, change, update, or rewrite; it runs two
+  bundled scripts and no Python is written.
+- **Any other edit of an existing document** (extend it, trim it, rework a
+  whole section, resize the text, embed an image into it): call the `skill`
+  tool with `name: "word"` and `file: "references/edit.md"`.
+- **Reading a document to answer in chat** (a summary, a question answered,
+  content pulled out — no file delivered): call the `skill` tool with
+  `name: "word"` and `file: "references/read.md"`.
+- **A summary delivered as a 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 rules (exact version
+pins, attachment staging, run-level formatting, in-place replacement, the only
+working removal idiom) 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 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.
+
+## 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 edit
+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. 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.** Edits always save a new output name,
+derived from the document edited — `report.docx` becomes `report_revised.docx`,
+never a fresh name taken from the new content.
+
+**An edit changes the document in place.** `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 is a failed turn — the edit recipe carries the
+guards that catch it.

package/skills/word/references/create.md

@@ -0,0 +1,368 @@
+# Creating a Word Document (python-docx)
+
+Create a new `.docx` from scratch by running Python through the `exec` tool.
+A new document needs **no** `inputs` — do not invent attachment ids — unless
+it embeds an image (see Embedding Images). **Exactly one** `exec` call per
+user request when that call succeeds.
+
+**A document that already exists in this chat is never rebuilt here.** "Add a
+section", "reword this", "extend the doc" — any request that starts from an
+existing `.docx` is an EDIT: load `references/edit.md` and stage the document
+by its `attachmentId`. Building a fresh document for an edit request throws
+away everything the user already has.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["python-docx==1.2.0"],
+  "outputs": ["report.docx"],
+  "command": "..."
+}
+```
+
+- `language` — always `"python"`.
+- `packages` — `["python-docx==1.2.0"]` on every call. The PyPI package is
+  `python-docx` but the import is `docx`; never list `docx` as the package —
+  that resolves a different, abandoned library. Pin the version; an unpinned
+  install resolves a potentially different library version. This exact version
+  ships with the app and installs with no network; any other version has to be
+  downloaded, which fails on a device that is offline.
+- `outputs` — `["report.docx"]`. `save("report.docx")` must match the declared
+  output name. A file you write but do not declare here is discarded. A `.doc`
+  output name is rejected — name it `.docx`.
+- `command` — the multi-line Python source, with real newline characters.
+  Never collapse it to one line joined by `;` — a `for`/`if`/`with` after a
+  semicolon is a `SyntaxError`. Its first line is the first line of Python
+  that runs: there is no shell and no interpreter to invoke, and no
+  installer — packages are declared in `packages`.
+
+## Embedding Images
+
+Two kinds of image input, told apart by where the file came from:
+
+**Tool-produced images** (`generate_image` output): stage them with the exact
+`attachmentId` from the tool result — never placeholders like `att_image` or
+any id you made up.
+
+**Images the user uploaded** ("use this photo"): there is no id to copy — an
+uploaded image never shows one. Stage it with `path` only and **no
+`attachmentId` key**; the first id-less entry is the first image of the user's
+latest message, the second is its second image, and so on. Id-less entries
+resolve _images only_.
+
+```json
+{
+  "language": "python",
+  "packages": ["python-docx==1.2.0"],
+  "inputs": [{ "path": "photo.png" }],
+  "outputs": ["report.docx"],
+  "command": "..."
+}
+```
+
+Staged files land in the working directory under the bare `path` names —
+reference `doc.add_picture("photo.png", …)` by that name only. Paths must be
+unique bare filenames. `attachment … not found in this chat` means you
+invented an id or the file is not attached: re-copy the exact id from the tool
+result, or for a document with no image drop `inputs` entirely.
+
+If the image was staged in `inputs`, embed it in **that** single build with
+`doc.add_picture` — never deliver a document and then rebuild to add the
+image. Soft-failing (`try`/`except` around the picture) and saving without it
+is a failed turn, not a success.
+
+**Image URLs do not work — never download.** Your Python code has **no
+network access**: `requests`, `urllib`, and `socket` all fail with a network
+error, and `http_request` returns truncated text, never image bytes. When the
+user gives an image URL, do not try to fetch it from Python and do not retry
+through other tools — that is a dead end. Say the link cannot be downloaded
+and ask the user to attach the image itself, or offer `generate_image` for a
+similar visual. Then build the document with the staged attachment as above.
+
+## The Recipe
+
+Start from this. It is a complete, working document — a title, headings,
+paragraphs with bold and italic runs, a bulleted list, and a table — saved
+under the declared output name. Copy it and change the content; do not
+assemble a document from memory.
+
+**Keep the source multi-line.** A `for`/`if`/`with` after a semicolon is a
+`SyntaxError` — paste the block with real newlines, not `stmt; for x in y: …`.
+
+**Hold content in plain lists of strings, and walk them.** Every list of bullets
+is a flat `["…", "…"]`, and every table is a list of row lists. Do not reach for
+a dict, a tuple of mixed widths, or a nested comprehension to hold document
+content — those are where a `SyntaxError` or a
+`ValueError: too many values to unpack` comes from, and they buy nothing here.
+
+**Keep every underscore in API names.** `add_heading`, `add_paragraph`,
+`add_run`, `add_table`, `add_row`, `add_picture`, `add_page_break` — stripping
+them to `addheading` / `addparagraph` fails. Copy identifiers exactly as written
+below:
+
+```python
+from docx import Document
+from docx.shared import Inches, Pt, RGBColor   # one import line covers sizes, widths, colors
+
+doc = Document()
+
+doc.add_heading("Quarterly Report", level=0)
+doc.add_paragraph("Prepared by the finance team.")
+
+doc.add_heading("Summary", level=1)
+p = doc.add_paragraph("Revenue grew ")
+strong = p.add_run("18 percent")
+strong.bold = True
+p.add_run(" against a ")
+emphasis = p.add_run("flat")
+emphasis.italic = True
+p.add_run(" cost base.")
+
+doc.add_heading("Highlights", level=1)
+for point in [
+    "New retail partners in two regions",
+    "Churn down for the third quarter",
+    "Support backlog cleared",
+]:
+    doc.add_paragraph(point, style="List Bullet")
+
+doc.add_heading("Key Figures", level=1)
+figures = [
+    ["Metric", "Q3", "Q4"],              # first list is the header row
+    ["Revenue", "$1.2M", "$1.4M"],
+    ["Costs", "$0.9M", "$0.9M"],
+]
+table = doc.add_table(rows=1, cols=len(figures[0]))
+table.style = "Table Grid"
+for index, cells in enumerate(figures):
+    row = table.rows[0].cells if index == 0 else table.add_row().cells
+    for column, value in enumerate(cells):
+        row[column].text = value
+
+doc.save("report.docx")               # must match the declared output exactly
+print(f"{len(doc.paragraphs)} paragraphs, {len(doc.tables)} table(s)")
+```
+
+## Write a document, not markdown
+
+A `.docx` carries real styles, so the structure is the style — never the
+punctuation. Markdown written into text stays there verbatim and reads as a
+typo in the finished document:
+
+- **No markdown characters in any string.** `#`, `##`, `-`, `*`, `1.`, `**bold**`
+  and backticks all render literally. `add_heading("Security", level=2)` — never
+  `add_heading("- Security", level=2)` or `"## Security"`. A numbered list is
+  `style="List Number"`, which numbers itself; a typed `"1. "` prefix double-numbers.
+- **No typed rules or line breaks.** A row of dashes or underscores as a section
+  divider is just those characters on the page, and a leading `"\n"` is a blank
+  line inside the paragraph. Headings already separate sections.
+- **Every section title is a heading.** A first section called "Introduction" or
+  "Overview" goes through `add_heading(..., level=1)` like every other one; as a
+  plain `add_paragraph` it renders as body text and the document looks unstructured.
+- **No blank paragraphs for spacing.** `add_paragraph("")` leaves a visible gap —
+  the heading and body styles already carry their own space before and after.
+- **Bold is for a few words, not a sentence.** A fully bold paragraph reads as a
+  formatting mistake; bold the term, then continue in a normal run.
+
+## One paragraph, one string
+
+`add_paragraph` takes a single text string, optionally with `style=` — nothing
+else. Several sentences passed positionally raise
+`TypeError: Document.add_paragraph() takes from 1 to 3 positional arguments but 4
+were given`. Join them into one string, or open the paragraph with the first
+piece and add the rest as runs:
+
+```python
+p = doc.add_paragraph("As of 2026, Bitcoin is widely held. ")
+p.add_run("Adoption keeps growing.")
+```
+
+**The text you pass to `add_paragraph` is already the paragraph's first run.** A
+run added afterwards _appends_ — repeating any of those words writes them twice
+into the document (`"…finite supplyfinite supply"`). Each run carries the next
+words and only those, so give a mixed-format paragraph an empty start and add
+every piece as its own run:
+
+```python
+p = doc.add_paragraph()
+p.add_run("Digital scarcity ")
+tail = p.add_run("and a finite supply")
+tail.italic = True
+```
+
+## Bold and italic live on runs, never on paragraphs
+
+`paragraph.bold = True` raises no error and changes **nothing** in the file — a
+paragraph has no bold; the assignment lands on the Python object and is silently
+discarded on save. Formatting belongs to runs:
+
+```python
+p = doc.add_paragraph("normal, then ")
+strong = p.add_run("bold")
+strong.bold = True
+p.add_run(" and ")
+emphasis = p.add_run("italic")
+emphasis.italic = True
+```
+
+Two rules make that shape the only one to write:
+
+- **`add_run` takes the text and nothing else.** `p.add_run("x", bold=True)`
+  raises `TypeError: Paragraph.add_run() got an unexpected keyword argument
+'bold'` — create the run, then set the attribute.
+- **Never chain an attribute onto the `add_run(...)` call.** Name the run on one
+  line and format it on the next, as above. A run that needs no formatting is a
+  bare `p.add_run("plain text")` and the line ends there — a trailing `.` left
+  over from a half-written chain is `SyntaxError: invalid syntax`.
+- **Runs join with no gap between them.** The next run starts exactly where the
+  last one ended, so the separating space belongs inside one of the strings —
+  `"…without intermediaries. "` then `"It was invented"`, never
+  `"…intermediaries."` followed by `"It was invented"`.
+
+**`add_run` belongs to the paragraph, not to a run.** Keep the paragraph in a
+variable and call `p.add_run(...)` for every run in it — chaining a second run off
+the first raises `AttributeError: 'Run' object has no attribute 'add_run'`. A run
+owns `.text`, `.bold`, `.italic` and `.font`, and nothing else: it has no
+`add_run`, no `add_paragraph`, and no `.style`.
+
+A run is also not a string: `p.add_run(" ") * 2` raises
+`TypeError: unsupported operand type(s) for *: 'Run' and 'int'`. Put any repeated
+text inside the string itself — and reach for neither, since spacing is the
+style's job, not padding you type.
+
+Character detail goes through `run.font` — size, color:
+
+```python
+from docx.shared import Pt, RGBColor
+
+p = doc.add_paragraph()
+run = p.add_run("Key finding")
+run.font.size = Pt(14)
+run.font.color.rgb = RGBColor(0x1A, 0x73, 0xE8)   # RGB in all caps
+```
+
+`Pt`, `Inches`, and `RGBColor` all import from `docx.shared` — there is no
+`docx.util` and no `docx.dml.color`; those are python-pptx paths and fail here.
+
+## Styles must exist in the document
+
+`style="List Bullet"` names a style **inside the document**. A missing name
+raises `KeyError: "no style with name 'List Bullet'"` at `add_paragraph` time.
+
+A **new** `Document()` ships these styles — safe to use without checking:
+`Title`, `Heading 1` … `Heading 9`, `Normal`, `List Bullet` (+ ` 2`, ` 3`),
+`List Number` (+ ` 2`, ` 3`), `Intense Quote`, and the table style `Table Grid`.
+Do not invent other names for a new document. (An uploaded document carries
+only its own styles — when editing one, load `references/edit.md` for the
+guard.)
+
+## Headings and lists
+
+- `doc.add_heading(text, level=N)` — level `0` is the document title style,
+  `1`–`9` map to `Heading 1`–`Heading 9`. Any other level raises
+  `ValueError: level must be in range 0-9`.
+- Bullets: one `add_paragraph(point, style="List Bullet")` per point, over a flat
+  list of plain strings. Never pack several points into one paragraph with `\n` —
+  a `\n` is a soft line break inside the same list item, not a new bullet. A
+  bullet that needs a label and a detail is one string (`"Limited supply — 21
+million coins"`), never a dict entry or a tuple.
+- Numbered lists: `style="List Number"`. Indent a level with `List Bullet 2` /
+  `List Number 2`.
+
+## Tables
+
+Write the whole table as a list of row lists — header first — then let the code
+above derive everything from it. **Always `rows=1` and `cols=len(rows[0])`**:
+
+```python
+rows = [
+    ["Item", "Status"],                        # header
+    ["Search", "Shipped"],
+    ["Export", "In review"],
+]
+table = doc.add_table(rows=1, cols=len(rows[0]))
+table.style = "Table Grid"                     # borders; omit for invisible grid
+for index, cells in enumerate(rows):
+    row = table.rows[0].cells if index == 0 else table.add_row().cells
+    for column, value in enumerate(cells):
+        row[column].text = value
+```
+
+That shape exists because the two hand-written alternatives both fail:
+
+- **`rows=` is a count of blank rows created immediately, not a maximum.**
+  `add_table(rows=4, …)` followed by `add_row()` per entry leaves three empty
+  rows sitting between the header and the data, plainly visible in the finished
+  document. `rows=1` is the header; every other row comes from `add_row()`.
+- **Unpacking a row into fixed names breaks the moment a row is a different
+  width.** `for name, q3, q4 in data:` raises
+  `ValueError: too many values to unpack (expected 3, got 4)`, and hand-counting
+  `cols=` against the data is the same mistake one step earlier. Index the cells
+  instead, and take the column count from the header.
+
+Address cells as `table.cell(row, col)` or `table.rows[r].cells[c]` — they are
+the same cell. Rows only grow at the bottom: there is no insert-at.
+`table.rows[9]` on a 4-row table raises `IndexError`. Write text with
+`cell.text = "…"`; for formatting inside a cell go through `cell.paragraphs[0]`
+and its runs like any other paragraph.
+
+## Images and page breaks
+
+`doc.add_picture(name, width=…)` appends the image in its own paragraph. Pass
+only one of `width`/`height`; passing both distorts the picture.
+
+```python
+from docx.shared import Inches
+
+doc.add_picture("figure1.png", width=Inches(5.5))
+doc.add_page_break()
+```
+
+**Do not soft-fail images or imports.** Never wrap `add_picture` or an import in
+`try`/`except` that prints a warning and continues. A missing file must raise so
+you fix it and rerun — a document saved without the requested image is a failed
+turn, not a success.
+
+## Errors
+
+- `ModuleNotFoundError: No module named 'docx'` means `packages` was missing or
+  wrong — add `["python-docx==1.2.0"]` and rerun. Never try to install it, and
+  never "fix" it by importing `python_docx`; the import stays `docx`.
+- `TypeError: 'Table' object is not subscriptable` — a table was indexed
+  directly (`table[0]`). Cells are reached through `table.rows[r].cells[c]` or
+  `table.cell(r, c)`; a whole row of cells is `table.add_row().cells`.
+- `KeyError: "no style with name '…'"` — the style is not in this document. For
+  a new document use only the names listed under Styles.
+- `NameError: name 'RGBColor' is not defined` (or `Pt`, `Inches`) — the import
+  line is missing that name. Keep the sample's single
+  `from docx.shared import Inches, Pt, RGBColor` rather than importing one at a time.
+- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
+  collapsed — restore multi-line newlines from the sample and rerun. Underscores
+  in names (`add_paragraph`, not `addparagraph`) must stay. Do not switch to
+  `python -c` or change the package pin.
+- On an `AttributeError` from python-docx the API name is wrong; on a `TypeError`
+  about positional arguments the call passes the wrong number of them — usually
+  several strings where one is allowed. Fix either against this file's examples,
+  reading the line number in the traceback. Do not retry the same call, and do
+  not switch to a shell.
+- `attachment … not found in this chat` means `inputs` listed an id that is not
+  in this chat (often a copied placeholder like `att_doc`). For a new document,
+  omit `inputs` entirely and rerun. Only stage real ids from prior tool results.
+- Never print the document's bytes or base64 — stdout is capped and the file
+  travels through `outputs`. A build call prints exactly one line (e.g. `9
+paragraphs, 1 table(s)`).
+- Never pass an absolute path to `save()`.
+
+## Finish
+
+When `exitCode` is `0` and `attachments` lists the `.docx`, the document is
+done — the `exec` result carries
+`attachments: [{ attachmentId, fileName, byteLength }]` and the file is already
+attached to the chat for the user to open or save, exactly like a
+`generate_image` result. Stop tool use and reply with a single line: file name
+
+- the count line from stdout. Exactly one successful `exec` per request. If
+  the result has `missingOutputs` instead, the file was never written: check the
+  `save()` name matches the declared output and rerun once.