@qvac/skills 0.0.0 → 0.1.1

package/skills/google-docs/references/read.md

@@ -0,0 +1,49 @@
+# Reading and Finding Google Docs
+
+Every request is one `http_request` call with a structured object. For each request, set `auth.tokenCredentialKey` to `google_docs_access_token`.
+
+## Get a document
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents/{documentId}",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "GET"
+}
+```
+
+Returns the full document structure with all content, styling, and revisions.
+The text lives in `body.content[]` → `paragraph.elements[]` → `textRun.content`;
+walk that array and join the `content` strings to reconstruct the text. Present
+the text, not the JSON. A read-only question ("what does the doc say", "summarize
+it") ends here — do not follow a read with an edit.
+
+## List or search for documents
+
+Use the Google Drive API with a MIME type filter to find Google Docs by name.
+The `documentId` you need for a follow-up read or edit is the file `id`.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "GET",
+  "query": {
+    "q": "mimeType='application/vnd.google-apps.document' and name contains 'report'",
+    "pageSize": 10,
+    "fields": "files(id,name,modifiedTime,webViewLink)"
+  }
+}
+```
+
+To list recent documents without a name filter, drop the `and name contains …`
+clause and add `"orderBy": "modifiedTime desc"` to the query. Run the search
+ONCE; if it returns nothing, say so rather than retrying with variations.
+
+## Common Mistakes
+
+- Searching with the wrong MIME type — it must be
+  `application/vnd.google-apps.document`.
+- Echoing the raw JSON to the user instead of the extracted text.
+- Fetching the document through the Drive API — content comes only from the
+  Docs API `GET`.

package/skills/google-drive/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: google-drive
+description: Search, list, download metadata, and manage Google Drive files and folders via the Google Drive REST API.
+tools: [http_request, drive_create_folder, drive_trash]
+platform: [darwin, linux, win32]
+credentials: [google_drive_access_token]
+allow_list: [https://www.googleapis.com/drive/v3/]
+---
+
+# Google Drive
+
+Use `drive_create_folder` to create folders and `drive_trash` to trash files; use `http_request` for everything else (list, search, get, export, rename). For each `http_request`, set `auth.tokenCredentialKey` to `google_drive_access_token`.
+
+## Prerequisites
+
+Google Drive must be connected. Each Google skill is connected separately, with its
+own app and its own approval — connecting one grants nothing to the others. If
+credentials are missing, tell the user to connect Google Drive from Settings, or to
+set the `google_drive_access_token` credential.
+
+## Base URL
+
+`https://www.googleapis.com/drive/v3`
+
+Always pass a `fields` mask on list/get calls — default payloads are huge. Keep `pageSize` small (5–10) unless the user asks for more.
+
+## Common Operations
+
+### List recent files
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files",
+  "auth": { "tokenCredentialKey": "google_drive_access_token" },
+  "method": "GET",
+  "query": {
+    "pageSize": 5,
+    "orderBy": "modifiedTime desc",
+    "fields": "files(id,name,mimeType,modifiedTime,webViewLink),nextPageToken"
+  }
+}
+```
+
+### Search by name
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files",
+  "auth": { "tokenCredentialKey": "google_drive_access_token" },
+  "method": "GET",
+  "query": {
+    "q": "name contains 'roadmap' and trashed = false",
+    "pageSize": 5,
+    "fields": "files(id,name,mimeType,modifiedTime,webViewLink),nextPageToken"
+  }
+}
+```
+
+Other useful `q` recipes: folders only → `mimeType = 'application/vnd.google-apps.folder' and trashed = false`; inside a folder → `'{folderId}' in parents and trashed = false`.
+
+### Get file metadata
+
+Only when the `fileId` is known — list/search first instead of guessing ids.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files/{fileId}",
+  "auth": { "tokenCredentialKey": "google_drive_access_token" },
+  "method": "GET",
+  "query": {
+    "fields": "id,name,mimeType,size,modifiedTime,owners(displayName,emailAddress),webViewLink"
+  }
+}
+```
+
+### Export Google Doc as plain text
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files/{fileId}/export",
+  "auth": { "tokenCredentialKey": "google_drive_access_token" },
+  "method": "GET",
+  "query": { "mimeType": "text/plain" }
+}
+```
+
+### Rename or move a file to trash
+
+`PATCH` with only the fields to change.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files/{fileId}",
+  "auth": { "tokenCredentialKey": "google_drive_access_token" },
+  "method": "PATCH",
+  "body": { "trashed": true }
+}
+```
+
+## MIME Types Reference
+
+- Google Docs: `application/vnd.google-apps.document` — export as `text/plain`
+- Google Sheets: `application/vnd.google-apps.spreadsheet` — export as `text/csv`
+- Google Slides: `application/vnd.google-apps.presentation` — export as `text/plain`
+- Folder: `application/vnd.google-apps.folder`
+
+## Output Policy
+
+- For lists, show name, type, and last modified; limit to 5 files unless asked for more.
+- When `webViewLink` is available, render the file name as a Markdown link to it — `[name](webViewLink)`. Never present the URL bare or wrapped in backticks, or it won't be clickable.
+- Never attempt to download large binary files; export text content instead.
+- Confirm before trashing files; show the file name so the user can verify.
+
+## Common Mistakes
+
+- Calling `files.list` without a `fields` mask — payloads are huge by default.
+- Calling `files.get` with a guessed file id — list/search first.
+- Downloading binaries instead of exporting text.

package/skills/google-drive/operations.json

@@ -0,0 +1,40 @@
+{
+  "operations": [
+    {
+      "tool": "drive_create_folder",
+      "description": "Create a Google Drive folder, optionally inside a parent folder.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Folder name" },
+          "parentId": {
+            "type": "string",
+            "description": "Parent folder id; omit for the Drive root"
+          }
+        },
+        "required": ["name"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://www.googleapis.com/drive/v3/files",
+        "builder": "drive-create-folder"
+      }
+    },
+    {
+      "tool": "drive_trash",
+      "description": "Move a Google Drive file or folder to the trash. Confirm the file name with the user first; list or search for the id, never guess it.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "fileId": { "type": "string", "description": "File id from a previous files.list" }
+        },
+        "required": ["fileId"]
+      },
+      "request": {
+        "method": "PATCH",
+        "url": "https://www.googleapis.com/drive/v3/files/{fileId}",
+        "builder": "drive-trash"
+      }
+    }
+  ]
+}

package/skills/google-sheets/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: google-sheets
+description: Create, read, and update Google Sheets spreadsheets via the Google Sheets REST API.
+tools: [http_request, sheets_create, sheets_write_values, sheets_append_values]
+platform: [darwin, linux, win32]
+credentials: [google_sheets_access_token]
+allow_list:
+  [https://sheets.googleapis.com/v4/spreadsheets, https://www.googleapis.com/drive/v3/files]
+---
+
+# Google Sheets
+
+Use `sheets_create`, `sheets_write_values`, and `sheets_append_values` for
+creating and writing cells — they set `valueInputOption` for you. Use
+`http_request` for everything else (reads, `batchUpdate`, Drive search, trash).
+For each `http_request`, set `auth.tokenCredentialKey` to
+`google_sheets_access_token`. Call one tool per operation with one complete structured
+object; `body` and `values` are JSON values, never serialized strings.
+
+## Load the Recipe File First
+
+This file carries no requests. The working calls live in three reference
+files — load the one for the job with the `skill` tool BEFORE calling any tool,
+then copy its call and change only the values:
+
+Each load is a real `skill` tool call — printing the call as JSON or text in
+your reply loads nothing.
+
+- **Reading or finding spreadsheets** — "what's in the sheet", "show me the
+  values", "find / list my spreadsheets": call the `skill` tool with
+  `name: "google-sheets"` and `file: "references/read.md"`.
+- **Creating a new spreadsheet** (no existing spreadsheet involved; may fill
+  it with a first table): call the `skill` tool with `name: "google-sheets"`
+  and `file: "references/create.md"`.
+- **Changing an existing spreadsheet** — write or overwrite cells, append rows,
+  clear a range, add a sheet tab, other structural changes, move it to the
+  trash: call the `skill` tool with `name: "google-sheets"` and
+  `file: "references/edit.md"`.
+
+Never write a call from memory. The recipes carry the range rules and the
+exact request shapes that fail in non-obvious ways when improvised; loading
+the file is one cheap read-only call.
+
+## Prerequisites
+
+Google Sheets must be connected. Each Google skill is connected separately, with its
+own app and its own approval — connecting one grants nothing to the others. If
+credentials are missing, tell the user to connect Google Sheets from Settings, or to
+set the `google_sheets_access_token` credential.
+
+## Identifiers and Ranges
+
+Spreadsheets are identified by `spreadsheetId` — the alphanumeric string in the
+URL `docs.google.com/spreadsheets/d/{spreadsheetId}/...`, or the `id` of a
+`sheets_create` result or Drive search hit. Listing and searching use the
+Google Drive API, not the Sheets API.
+
+Ranges use A1 notation: `Sheet1!A1`, `Sheet1!A1:B10`, `Sheet1!A:A` (entire
+column), `Sheet1!1:1` (entire row); quote sheet names with spaces:
+`'My Sheet'!A1`. The first sheet of a spreadsheet is NOT always called
+`Sheet1` — Google names it in the account's language (`Página1`, `Feuille1`,
+`Tabellenblatt1`, …). A range with no sheet name (`A1:C3`) always targets the
+first sheet; the recipe files say when to use it.
+
+## Output Policy
+
+- For reads, present values in a table format with headers when available.
+- For writes, confirm the range and values with the user first unless they
+  already spelled them out.
+- Report success only when the response contains the `spreadsheetId` and the
+  updated range, and name the spreadsheet (title or link) in the answer.

package/skills/google-sheets/operations.json

@@ -0,0 +1,85 @@
+{
+  "operations": [
+    {
+      "tool": "sheets_create",
+      "description": "Create an empty Google Sheets spreadsheet. The response id is the spreadsheetId for later writes.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Spreadsheet name" }
+        },
+        "required": ["name"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://www.googleapis.com/drive/v3/files",
+        "builder": "sheets-create"
+      }
+    },
+    {
+      "tool": "sheets_write_values",
+      "description": "Overwrite cells in a range with a 2D array of rows. The range must match the data dimensions or be a single top-left cell. valueInputOption defaults to USER_ENTERED (formulas and dates are parsed).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "spreadsheetId": { "type": "string", "description": "Spreadsheet id" },
+          "range": {
+            "type": "string",
+            "description": "A1 notation. Omit the sheet name to target the first sheet whatever its language (e.g. A1); name a sheet only for another tab, quoted if it has spaces (e.g. 'My Sheet'!A1)"
+          },
+          "values": {
+            "type": "array",
+            "items": {
+              "type": "array",
+              "items": { "type": ["string", "number", "boolean", "null"] }
+            },
+            "description": "Rows of cell values"
+          },
+          "valueInputOption": {
+            "type": "string",
+            "enum": ["RAW", "USER_ENTERED"],
+            "description": "RAW inserts values as-is; USER_ENTERED parses formulas and dates"
+          }
+        },
+        "required": ["spreadsheetId", "range", "values"]
+      },
+      "request": {
+        "method": "PUT",
+        "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}",
+        "builder": "sheets-write-values"
+      }
+    },
+    {
+      "tool": "sheets_append_values",
+      "description": "Append rows after the last row of data in a range. valueInputOption defaults to USER_ENTERED.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "spreadsheetId": { "type": "string", "description": "Spreadsheet id" },
+          "range": {
+            "type": "string",
+            "description": "A1 notation of the table's columns to append to. Omit the sheet name for the first sheet (e.g. A:C); name a sheet only for another tab (e.g. 'My Sheet'!A:C)"
+          },
+          "values": {
+            "type": "array",
+            "items": {
+              "type": "array",
+              "items": { "type": ["string", "number", "boolean", "null"] }
+            },
+            "description": "Rows of cell values"
+          },
+          "valueInputOption": {
+            "type": "string",
+            "enum": ["RAW", "USER_ENTERED"]
+          }
+        },
+        "required": ["spreadsheetId", "range", "values"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append",
+        "builder": "sheets-append-values"
+      }
+    }
+  ]
+}

package/skills/google-sheets/references/create.md

@@ -0,0 +1,54 @@
+# Creating a Spreadsheet
+
+Two tool calls: `sheets_create` makes the file, `sheets_write_values` fills
+it. Typed tools select their own credential.
+
+## Create the spreadsheet
+
+```json
+{ "name": "My Spreadsheet" }
+```
+
+Call `sheets_create` with that object. The result's `id` is the
+`spreadsheetId`. Capture it and keep using it. Create exactly once — never
+follow a successful create with a Drive search or another create to rediscover
+the id.
+
+## Fill it with a first table
+
+Call `sheets_write_values`. `values` is an array of rows; every row is an array
+of cells. Use the range `A1` with NO sheet name: the new file's only sheet is
+named in the account's language (`Sheet1`, `Página1`, `Feuille1`, …), and a
+range without a sheet name always targets the first sheet, so the write cannot
+fail on the name.
+
+```json
+{
+  "spreadsheetId": "<id from sheets_create>",
+  "range": "A1",
+  "values": [
+    ["Name", "Age"],
+    ["Alice", 30],
+    ["Bob", 25]
+  ]
+}
+```
+
+`valueInputOption` defaults to `USER_ENTERED` (formulas, numbers and dates are
+parsed like typing them in); pass `"valueInputOption": "RAW"` only to store
+every value exactly as given. The response reports `updatedRange` and
+`updatedCells` — that is the confirmation.
+
+## Finishing
+
+Answer with the spreadsheet name and the link
+`https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit`. Do not read the
+values back to "confirm" a write that already reported `updatedCells`.
+
+## Common Mistakes
+
+- Writing to `Sheet1!A1` on a freshly created file — if the account's language
+  is not English the sheet is not called `Sheet1` and the write fails with
+  `Unable to parse range`. Use `A1` without a sheet name.
+- Creating through `http_request` — `sheets_create` is the supported path.
+- Passing `values` as a string, or rows that are not arrays.

package/skills/google-sheets/references/edit.md

@@ -0,0 +1,124 @@
+# Editing an Existing Spreadsheet
+
+Cell writes use the typed tools `sheets_write_values` (overwrite) and
+`sheets_append_values` (add rows) — they set `valueInputOption` for you.
+Everything else (clear, structural changes, trash) is one `http_request` with
+a structured object. For each `http_request`, set `auth.tokenCredentialKey` to `google_sheets_access_token`. Get the `spreadsheetId` from the URL the user gave, an earlier
+`sheets_create` result, or a Drive search (`references/read.md`).
+
+Ranges: a range with no sheet name (`A1`, `A2:B10`) targets the first sheet
+whatever its language. Name a sheet only for another tab, quoted if it has
+spaces (`'My Sheet'!A1`).
+
+## Overwrite cells
+
+Call `sheets_write_values`. The range is the top-left cell; the values block
+grows from there. `values` is an array of rows, each an array of cells.
+
+```json
+{
+  "spreadsheetId": "<id>",
+  "range": "A1",
+  "values": [
+    ["Name", "Age"],
+    ["Alice", 30],
+    ["Bob", 25]
+  ]
+}
+```
+
+To change one cell, use that cell as the range with a single-row, single-cell
+`values` array (`"range": "B2", "values": [["100"]]`). Pass
+`"valueInputOption": "RAW"` only to store values exactly as given; the default
+`USER_ENTERED` parses formulas, numbers and dates.
+
+## Append rows
+
+Call `sheets_append_values` with the range of the table the rows belong to
+(its columns, not the empty row you expect); the API finds the first empty row
+after that table.
+
+```json
+{
+  "spreadsheetId": "<id>",
+  "range": "A:B",
+  "values": [
+    ["Charlie", 28],
+    ["Diana", 32]
+  ]
+}
+```
+
+## Clear a range
+
+```json
+{
+  "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/A2:B10:clear",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "POST",
+  "body": {}
+}
+```
+
+## Structural changes (batchUpdate)
+
+Adding or removing sheets, resizing, formatting, and other structural
+operations use `batchUpdate`; its items are always wrapped in
+`{ "requests": [ … ] }`, and cell values never go through it:
+
+```json
+{
+  "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}:batchUpdate",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "POST",
+  "body": {
+    "requests": [
+      {
+        "addSheet": {
+          "properties": { "title": "New Sheet", "sheetType": "GRID" }
+        }
+      }
+    ]
+  }
+}
+```
+
+Requests that target a sheet by `sheetId` (delete, resize, format) need the
+numeric id from the metadata call in `references/read.md`, not the tab name.
+
+## Move a spreadsheet to the trash
+
+Trashing goes through the Drive API; the user can restore it from Drive's
+trash. Only do this when the user explicitly asks to delete or remove the
+spreadsheet.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files/{spreadsheetId}",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "PATCH",
+  "body": { "trashed": true }
+}
+```
+
+## If a range is rejected
+
+`400 Unable to parse range: Sheet1!A1` means the spreadsheet has no sheet
+called `Sheet1` — Google names the first sheet in the account's language. Do
+NOT retry the same range: drop the sheet name, or GET the metadata
+(`references/read.md`) for the real title.
+
+## Finishing
+
+A write is confirmed by `updatedRange`/`updatedCells` (or `updates` for
+append, `replies` for batchUpdate) in the response — do not read the values
+back to check. Name the spreadsheet in the answer.
+
+## Common Mistakes
+
+- Writing cell values with `http_request` PUT or with `batchUpdate` — use the
+  typed tools.
+- Naming a sheet that does not exist (`Sheet1!…` on a non-English account) —
+  leave the sheet name out for the first sheet.
+- Appending to an empty row range instead of the table's columns.
+- Passing `values` as a string, or rows that are not arrays.

package/skills/google-sheets/references/read.md

@@ -0,0 +1,74 @@
+# Reading and Finding Spreadsheets
+
+Reads go through `http_request` with a structured object. For each request, set `auth.tokenCredentialKey` to `google_sheets_access_token`.
+
+## Get values from a range
+
+Always specify `valueRenderOption`: `FORMATTED_VALUE` for displayed values
+(formulas evaluated) or `UNFORMATTED_VALUE` for raw cell content.
+
+```json
+{
+  "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/A1:C10",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "GET",
+  "query": { "valueRenderOption": "FORMATTED_VALUE" }
+}
+```
+
+A range with no sheet name (`A1:C10`) reads the first sheet whatever its
+language; add a sheet name only for another tab, quoted if it has spaces
+(`'My Sheet'!A1:C10`). The response contains a `values` array of rows; each row
+is an array of cell strings. Trailing empty cells are omitted, so rows can
+differ in length. To read everything on the first sheet, GET the spreadsheet
+metadata below for the tab title and use it alone as the range. Present the
+rows as a table with the first row as headers when it looks like one.
+
+## Get spreadsheet metadata (sheet names)
+
+When you need the tab names or their numeric ids before a follow-up call:
+
+```json
+{
+  "url": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "GET",
+  "query": { "fields": "spreadsheetId,properties.title,sheets.properties" }
+}
+```
+
+## List or search for spreadsheets
+
+Use the Google Drive API with a MIME type filter to find spreadsheets by name.
+The `spreadsheetId` you need for a follow-up call is the file `id`.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files",
+  "auth": { "tokenCredentialKey": "google_sheets_access_token" },
+  "method": "GET",
+  "query": {
+    "q": "mimeType='application/vnd.google-apps.spreadsheet' and name contains 'budget' and trashed = false",
+    "pageSize": 10,
+    "fields": "files(id,name,modifiedTime,webViewLink)"
+  }
+}
+```
+
+To list recent spreadsheets without a name filter, drop the `and name contains …`
+clause and add `"orderBy": "modifiedTime desc"`. Run the search ONCE; if it
+returns nothing, say so rather than retrying with variations.
+
+## If a range is rejected
+
+`400 Unable to parse range: Sheet1!A1` means the spreadsheet has no sheet
+called `Sheet1` — Google names the first sheet in the account's language. Do
+NOT retry the same range: drop the sheet name (`A1:C10`) or take the real title
+from the metadata call above.
+
+## Common Mistakes
+
+- Using the wrong MIME type when searching (should be
+  `application/vnd.google-apps.spreadsheet`).
+- Reading values through the Drive API — cell values come only from the Sheets
+  API `values` endpoint.

package/skills/image-generation/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: image-generation
+description: Generate images from text prompts with the local diffusion model.
+tools: [generate_image, edit_image]
+platform: [darwin, linux, win32]
+---
+
+# Image generation
+
+Call `generate_image` when the user asks for an image, picture, illustration,
+drawing, or logo. The generated image is saved as a chat attachment and shown
+to the user automatically — never describe pixels, paste data, or apologize
+about being text-only; just confirm what you generated.
+
+```json
+{ "prompt": "a watercolor cat on a windowsill, soft morning light" }
+```
+
+## Parameters
+
+- `prompt` (required) — describe subject, style, and mood in plain language.
+- `width` / `height` — pixels, multiples of 64, max 1024. Default 512×512;
+  only change them when the user asks for a specific shape (e.g. wide banner
+  → 1024×512).
+- `negative_prompt` — what to avoid (e.g. `blurry, low quality, watermark`).
+- `seed` — set only when the user wants a reproducible or slightly varied
+  retry of a previous result.
+- `steps` — leave unset unless the user asks for a faster draft (lower) or
+  higher quality (higher, max 100).
+
+## Editing an existing image
+
+Call `edit_image` when the user wants an image from this chat modified,
+restyled, or varied ("make it a watercolor", "same but at night"). It edits
+the most recent image by default; pass `attachment_id` (from an earlier
+result) to target another. `strength` 0..1 sets how far to move from the
+source: 0.3-0.5 for subtle changes, 0.7 (default) for restyling, 0.9 for
+loose reinterpretation. Output keeps the source dimensions.
+
+```json
+{ "prompt": "turn it into a watercolor painting", "strength": 0.7 }
+```
+
+## Notes
+
+- Generation takes a while; the result arrives as an attachment in this turn.
+- One generation or edit at a time — if the tool reports it is busy, wait and
+  retry instead of stacking calls.