@qvac/skills 0.0.0 → 0.1.0

package/skills/obsidian/cli.schema.json

@@ -0,0 +1,392 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {},
+      "x-effect": "read"
+    },
+    "vaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {},
+      "x-effect": "read"
+    },
+    "vault": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "list": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {},
+          "x-effect": "read"
+        },
+        "info": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        }
+      },
+      "x-effect": "read"
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "folder": {
+          "type": "string"
+        },
+        "ext": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "limit": {
+          "type": "string"
+        },
+        "total": {
+          "type": "boolean"
+        },
+        "counts": {
+          "type": "boolean"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "search": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "query"
+      ],
+      "properties": {
+        "query": {
+          "type": "string"
+        },
+        "limit": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "folder": {
+          "type": "string"
+        },
+        "verbose": {
+          "type": "boolean"
+        },
+        "total": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "read": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "create": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "file": {
+          "type": "string"
+        },
+        "content": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "template": {
+          "type": "string"
+        },
+        "silent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "append": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "content": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "silent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "prepend": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "content": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "silent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "backlinks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "format": {
+          "type": "string"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "vault": {
+          "type": "string"
+        },
+        "format": {
+          "type": "string"
+        },
+        "counts": {
+          "type": "boolean"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "tasks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "vault": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "folder": {
+          "type": "string"
+        },
+        "format": {
+          "type": "string"
+        },
+        "todo": {
+          "type": "boolean"
+        },
+        "done": {
+          "type": "boolean"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "daily:read": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "vault": {
+          "type": "string"
+        },
+        "verbose": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "daily:append": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "silent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "daily:prepend": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "silent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "rename": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "name": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        }
+      }
+    },
+    "move": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "to": {
+          "type": "string"
+        },
+        "vault": {
+          "type": "string"
+        }
+      }
+    },
+    "delete": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "vault": {
+          "type": "string"
+        },
+        "force": {
+          "type": "boolean"
+        }
+      }
+    },
+    "open": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?![/\\\\~]|[A-Za-z]:).+$",
+          "description": "vault-relative path (not absolute)"
+        },
+        "vault": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/skills/obsidian/references/read.md

@@ -0,0 +1,79 @@
+# Finding and Reading Notes
+
+One `obsidian` command per `exec` call, no chaining. Skip `vault info` unless
+the vault is ambiguous.
+
+| Request                                   | Command                                    |
+| ----------------------------------------- | ------------------------------------------ |
+| "what are my notes" / "list my notes"     | `obsidian files`                           |
+| "list notes in <folder>"                  | `obsidian files folder="<Folder>"`         |
+| "find / search notes about X"             | `obsidian search query="X"`                |
+| "read / open / summarize note X"          | `obsidian read file="X"` (name, no `.md`)  |
+| "what's in my daily note"                 | `obsidian daily:read`                      |
+| "list my tags"                            | `obsidian tags`                            |
+
+## List or search
+
+```bash
+obsidian files
+obsidian files folder="Projects" ext=md
+obsidian search query="release handoff" limit=10
+```
+
+`search` REQUIRES `query="..."`. Add `limit=` to keep results small; if they are
+still broad, ask a narrowing question or rerun with a tighter query.
+
+## Read
+
+Read by NAME (no `.md`) or by a VAULT-RELATIVE path — never an absolute
+filesystem path (`/Users/.../Vault/Note.md` fails with "File not found").
+Prefer `path=` when two notes may share a name.
+
+```bash
+obsidian read file="QVAC"
+obsidian read path="Projects/QVAC.md"
+obsidian daily:read
+```
+
+## Structured output
+
+For counts or machine-readable output add `total`, `counts`, or `format=json`:
+
+```bash
+obsidian files folder="Projects" ext=md total
+obsidian tags counts format=json
+```
+
+## Backlinks and tasks (CLI mode only)
+
+`backlinks` and `tasks` need the running Obsidian app; in vault-folder mode
+they fail with `not supported in vault file mode` — then say so instead of
+retrying or falling back to shell tools.
+
+```bash
+obsidian backlinks path="Projects/QVAC.md" format=json
+obsidian tasks todo verbose
+```
+
+## Vault checks (only when needed)
+
+```bash
+obsidian vaults
+obsidian vault info=name
+obsidian version
+```
+
+## Answering
+
+Give the note path and the exact line or excerpt that supports the answer. Do
+not dump whole notes or the whole vault unless asked. A read-only request ends
+after the read — never follow it with a write.
+
+## Common Mistakes
+
+- Shelling out with `cat`, `ls`, `find`, `grep`, or filesystem tools instead of
+  `obsidian` commands. Always use `obsidian`, even for a single note.
+- Passing an absolute filesystem path to `read`. Use `file="Name"` or a
+  vault-relative `path="Folder/Note.md"`.
+- Calling `search` without `query=`.
+- Running `obsidian vault info` before every request.

package/skills/obsidian/references/write.md

@@ -0,0 +1,67 @@
+# Creating and Changing Notes
+
+One `obsidian` command per `exec` call, no chaining. Writes must go through
+`obsidian` CLI commands — never direct filesystem writes.
+
+| Request                          | Command                                                   |
+| -------------------------------- | --------------------------------------------------------- |
+| "create a note"                  | `obsidian create name="Title" content="..."`              |
+| "create a note in <folder>"      | `obsidian create path="Folder/Title.md" content="..."`    |
+| "add to note X"                  | `obsidian append file="X" content="..."`                  |
+| "add to the top of note X"       | `obsidian prepend file="X" content="..."`                 |
+| "add to my daily note"           | `obsidian daily:append content="..."`                     |
+| "rename / move / delete note X"  | only when explicitly asked — see below                    |
+
+## Create
+
+Name new notes with `name="Title"` or an exact `path="Folder/Title.md"`. Never
+use `file=` with `create`: the official CLI ignores it and silently creates an
+"Untitled" note. `content=` is Markdown; write line breaks as `\n`.
+
+```bash
+obsidian create name="QVAC" content="# QVAC\n\nInitial note"
+obsidian create path="Projects/QVAC.md" content="# QVAC\n\nInitial note"
+```
+
+## Append and prepend
+
+Target by NAME (no `.md`) or by a VAULT-RELATIVE path — never an absolute
+filesystem path. Prefer `path=` when two notes may share a name.
+
+```bash
+obsidian append file="QVAC" content="- [ ] Follow up on QVAC notes"
+obsidian append path="Daily/2026-05-29.md" content="- [ ] Follow up on QVAC notes"
+obsidian prepend path="Projects/QVAC.md" content="> Updated 2026-05-29"
+obsidian daily:append content="- [ ] Review local Obsidian skill wiring"
+```
+
+To change existing text inside a note, read it first (`references/read.md`),
+then `append`/`prepend` the corrected content — there is no in-place replace.
+
+## Rename, move, delete
+
+Run these ONLY when the user explicitly asks for that exact side effect, and
+confirm the target path when the request is ambiguous.
+
+```bash
+obsidian rename path="Projects/QVAC.md" name="QVAC v2"
+obsidian move path="Projects/QVAC.md" to="Archive/QVAC.md"
+obsidian delete path="Archive/QVAC.md" force
+```
+
+Avoid `overwrite`, plugin commands, sync commands, and theme commands unless the
+user explicitly asks.
+
+## Answering
+
+Do not claim a note changed unless the `obsidian` command completed
+successfully. Confirm with the note path and what was written.
+
+## Common Mistakes
+
+- Using `create file="Title"` — the CLI ignores `file=` on create and makes an
+  "Untitled" note. Use `name="Title"` or `path=`.
+- Passing an absolute filesystem path to `create` or `append`.
+- Using `file=` when two notes may share the same name. Prefer exact `path=`.
+- Writing through `echo`, redirection, or file tools instead of `obsidian`.
+- Treating a failed command as success.

package/skills/pdf/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: pdf
+description: Create PDF documents with fpdf2 or transform existing ones with pypdf — merge, split, rotate, watermark, encrypt, decrypt, fill forms, extract text — and deliver them as chat attachments.
+tools: [exec(python)]
+platform: [darwin, linux, win32]
+metadata:
+  {
+    "openclaw":
+      {
+        "setup":
+          {
+            "summary": "Runs pypdf and fpdf2 in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
+          }
+      }
+  }
+---
+
+# PDF
+
+Build or transform `.pdf` files by running Python through the `exec` tool with
+`language: "python"`. Declare every produced file in `outputs` and it comes back
+as a chat attachment the user can save.
+
+Two libraries, split by job — pick by whether a PDF already exists:
+
+- **fpdf2** — create a new PDF from scratch: reports, letters, invoices, cheat
+  sheets, anything laid out page by page.
+- **pypdf** — transform a PDF that already exists: merge, split, reorder or
+  rotate pages, watermark, encrypt or decrypt, fill form fields, extract text.
+
+## Load the Recipe File First
+
+This file contains no Python. The working recipes live in two 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 PDF** (no existing PDF involved): call the `skill` tool with
+  `name: "pdf"` and `file: "references/create.md"`.
+- **Anything with an existing PDF** (merge, split, rotate, watermark, encrypt,
+  decrypt, fill forms, extract text): call the `skill` tool with
+  `name: "pdf"` and `file: "references/transform.md"`.
+- **Adding or changing words in an existing PDF** (add a paragraph or section,
+  reword, restyle): pypdf cannot edit page content — do not try. The job is a
+  REBUILD: load `references/create.md` and write the whole document again with
+  fpdf2 — every original section, unchanged, plus the requested change. When
+  the original text is not already in this chat, load
+  `references/transform.md` too and extract it first.
+- **Both in one flow** (build a page with fpdf2, then stamp it onto an existing
+  PDF): load both files.
+
+Never write the Python from memory. The recipes carry required arguments
+(`new_x`/`new_y`, exact version pins, attachment staging rules) 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 new `.pdf` document.
+- The user attached one or more PDFs and wants them merged, split, rotated,
+  watermarked, password-protected, unlocked, filled in, or their text pulled out.
+- A flow needs both: build a page with fpdf2, then stamp it onto an existing
+  PDF with pypdf — one `exec` call can use both libraries.
+
+## When NOT to Use
+
+- A `create_pdf` tool is available in this chat and the user only wants prose
+  you are writing turned into a downloadable document — call `create_pdf` with
+  the markdown instead; it is cheaper and handles layout itself. Reach for this
+  skill when that tool is absent on this device, when an existing PDF is
+  involved, or when the layout must be controlled page by page.
+- The user asks about an attached PDF — answer from the document text or
+  knowledge excerpts already in the chat. Run text extraction only when the
+  user wants the text itself delivered as a file.
+- The user wants a slide deck — use the presentations skill; a spreadsheet or
+  Word file — this skill cannot read or write Office formats.
+- The user wants a single image — call `generate_image` alone.
+
+## Rules for Every Job
+
+**You build it, not the user.** Deliver the file, never the recipe. Do NOT
+print the Python source in chat, do NOT tell the user to install pypdf, run a
+script, or open a terminal — they have no terminal in this chat and the code
+would not run there. The PDF exists only if an `exec` call with `outputs`
+succeeds and returns the attachment.
+
+**Success = stop.** When `exitCode` is `0` and the result's `attachments` lists
+the `.pdf`, the job is done. Do not call `exec` again for the same request —
+not to "confirm", not to "improve". Reply with a single line: file name + the
+page 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, re-read the
+traceback line-by-line before a third. An error is never a fault in pypdf,
+fpdf2, or the runtime — do not switch package versions, do not wrap source in
+`python -c` or shell, and do not "debug" with `os.listdir` or no-op scripts
+while `outputs` still lists the PDF.
+
+**The runtime is sealed.** There is no shell (`ls`, `cat` raise
+`SyntaxError` — the `command` is Python source) and no network — `requests`,
+`urllib`, and `socket` all fail, so a PDF behind a URL 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, and a file you
+write but do not declare in `outputs` is discarded.
+
+**Never overwrite a staged input.** Transforms always write a new output name.