@qvac/skills 0.0.0 → 0.1.1

package/skills/gmail/operations.json

@@ -0,0 +1,71 @@
+{
+  "operations": [
+    {
+      "tool": "gmail_send",
+      "description": "Send an email through Gmail, or reply in a thread when threadId and inReplyTo are given. Pass the message as plain fields — never build the RFC 2822 message or base64 yourself. Confirm the recipient and body with the user before sending.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "to": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Recipient email addresses"
+          },
+          "subject": { "type": "string", "description": "Subject line" },
+          "text": { "type": "string", "description": "Plain-text body" },
+          "html": { "type": "string", "description": "HTML body, used when text is absent" },
+          "cc": { "type": "array", "items": { "type": "string" } },
+          "bcc": { "type": "array", "items": { "type": "string" } },
+          "replyTo": { "type": "string" },
+          "threadId": {
+            "type": "string",
+            "description": "Thread to reply in, from a previous messages.list or messages.get"
+          },
+          "inReplyTo": {
+            "type": "string",
+            "description": "Message-ID header of the message being replied to"
+          },
+          "references": { "type": "string", "description": "References header of the thread" }
+        },
+        "required": ["to", "subject"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/send",
+        "builder": "gmail-send"
+      }
+    },
+    {
+      "tool": "gmail_draft",
+      "description": "Create a Gmail draft without sending it. Pass the message as plain fields — never build the RFC 2822 message or base64 yourself.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "to": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Recipient email addresses"
+          },
+          "subject": { "type": "string", "description": "Subject line" },
+          "text": { "type": "string", "description": "Plain-text body" },
+          "html": { "type": "string", "description": "HTML body, used when text is absent" },
+          "cc": { "type": "array", "items": { "type": "string" } },
+          "bcc": { "type": "array", "items": { "type": "string" } },
+          "replyTo": { "type": "string" },
+          "threadId": { "type": "string", "description": "Thread the draft replies in" },
+          "inReplyTo": {
+            "type": "string",
+            "description": "Message-ID header of the message being replied to"
+          },
+          "references": { "type": "string", "description": "References header of the thread" }
+        },
+        "required": ["to", "subject"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
+        "builder": "gmail-draft"
+      }
+    }
+  ]
+}

package/skills/google-calendar/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: google-calendar
+description: List, create, update, and delete Google Calendar events via the Google Calendar REST API.
+aliases: [calendar, meeting+create, meeting+schedule, meeting+book, meeting+move, meeting+cancel, event+create]
+tools: [http_request, calendar_create_meet_event, calendar_add_meet]
+platform: [darwin, linux, win32]
+credentials: [google_calendar_access_token]
+allow_list: [https://www.googleapis.com/calendar/v3/]
+---
+
+# Google Calendar
+
+Use `calendar_create_meet_event` and `calendar_add_meet` for Google Meet links, and `http_request` for everything else (list, plain create/update/delete, free/busy). The Google Calendar credential is attached automatically to every `www.googleapis.com/calendar/v3/` request — **never include an `auth` block**.
+
+## Prerequisites
+
+Google Calendar 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 Calendar from Settings, or to
+set the `google_calendar_access_token` credential.
+
+## Base URL
+
+`https://www.googleapis.com/calendar/v3` — default `calendarId` is `primary` unless the user names another calendar.
+
+## Temporal Accuracy (Critical)
+
+- Resolve relative dates ("today", "tomorrow", "next week", "in 2 hours") to absolute ISO 8601 timestamps **with timezone offset** before calling the API.
+- Never infer "now" from memory when building `timeMin`, `timeMax`, or event start/end values.
+- If the date or time is ambiguous, ask the user instead of guessing.
+
+Example: annotation `[Current local time: 2026-08-12 14:00:00 (UTC-03:00)]`, user asks "in 30 minutes for 1 hour" -> `start.dateTime` = `2026-08-12T14:30:00-03:00`, `end.dateTime` = `2026-08-12T15:30:00-03:00`.
+
+## Common Operations
+
+### List upcoming events
+
+Always use `singleEvents=true` and `orderBy=startTime` so recurring events expand and sort correctly.
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "method": "GET",
+  "query": {
+    "timeMin": "<resolved ISO 8601 with offset>",
+    "maxResults": 10,
+    "singleEvents": true,
+    "orderBy": "startTime"
+  }
+}
+```
+
+### Create an event
+
+Ask for missing required fields (summary, start, end) before creating.
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "method": "POST",
+  "body": {
+    "summary": "Design review",
+    "start": { "dateTime": "2026-06-10T14:00:00-03:00" },
+    "end": { "dateTime": "2026-06-10T15:00:00-03:00" },
+    "attendees": [{ "email": "colleague@example.com" }]
+  }
+}
+```
+
+### Create an event with a Google Meet link
+
+Use `calendar_create_meet_event` with `summary`, `start`, `end` (ISO 8601 with offset), and optionally `timeZone`, `description`, `location`, `attendees`, `calendarId`.
+
+```json
+{
+  "summary": "Sync call",
+  "start": "2026-06-10T14:00:00-03:00",
+  "end": "2026-06-10T14:30:00-03:00"
+}
+```
+
+To add a Meet link to an event that already exists, use `calendar_add_meet` with `eventId` (and `calendarId` if not `primary`).
+
+### Update an event
+
+`PATCH` with only the fields to change.
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}",
+  "method": "PATCH",
+  "body": { "summary": "Updated title" }
+}
+```
+
+### Delete an event
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}",
+  "method": "DELETE"
+}
+```
+
+### Free/busy query
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/freeBusy",
+  "method": "POST",
+  "body": {
+    "timeMin": "2026-06-10T00:00:00Z",
+    "timeMax": "2026-06-11T00:00:00Z",
+    "items": [{ "id": "primary" }]
+  }
+}
+```
+
+### List calendars
+
+```json
+{
+  "url": "https://www.googleapis.com/calendar/v3/users/me/calendarList",
+  "method": "GET"
+}
+```
+
+## Output Policy
+
+- Present events with title, date/time (with timezone), location, and attendees when available.
+- For create/update, report the event `id`, start/end time, and `htmlLink` rendered as a Markdown link — e.g. `[event title](htmlLink)`. Never present the URL bare or wrapped in backticks, or it won't be clickable.
+- Confirm before deleting events; show the event title and time so the user can verify.
+
+## Common Mistakes
+
+- Sending natural-language dates instead of absolute ISO 8601 with timezone offset.
+- Listing without `singleEvents=true` — recurring events come back collapsed and unsorted.
+- Calling get/patch/delete without a real `eventId` — list/search first.
+- Including an `auth` block by hand — credentials attach automatically; a mistyped key breaks the request.

package/skills/google-calendar/operations.json

@@ -0,0 +1,62 @@
+{
+  "operations": [
+    {
+      "tool": "calendar_create_meet_event",
+      "description": "Create a Google Calendar event that has a Google Meet link. Use this whenever the user asks for a meeting with a video call; a plain event without a call stays on http_request.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "summary": { "type": "string", "description": "Event title" },
+          "start": {
+            "type": "string",
+            "description": "Start time, ISO 8601 with a UTC offset, e.g. 2026-03-04T15:00:00-03:00"
+          },
+          "end": {
+            "type": "string",
+            "description": "End time, ISO 8601 with a UTC offset"
+          },
+          "timeZone": {
+            "type": "string",
+            "description": "IANA time zone, e.g. America/Sao_Paulo"
+          },
+          "description": { "type": "string" },
+          "location": { "type": "string" },
+          "attendees": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Attendee email addresses"
+          },
+          "calendarId": { "type": "string", "description": "Defaults to primary" }
+        },
+        "required": ["summary", "start", "end"]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events",
+        "urlDefaults": { "calendarId": "primary" },
+        "builder": "calendar-meet-event"
+      }
+    },
+    {
+      "tool": "calendar_add_meet",
+      "description": "Add a Google Meet link to an existing Google Calendar event.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "eventId": {
+            "type": "string",
+            "description": "Event id, from a previous events.list or events.insert"
+          },
+          "calendarId": { "type": "string", "description": "Defaults to primary" }
+        },
+        "required": ["eventId"]
+      },
+      "request": {
+        "method": "PATCH",
+        "url": "https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/{eventId}",
+        "urlDefaults": { "calendarId": "primary" },
+        "builder": "calendar-add-meet"
+      }
+    }
+  ]
+}

package/skills/google-docs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: google-docs
+description: Create, read, and edit Google Docs documents via the Google Docs REST API.
+tools: [http_request, docs_create, docs_append_text]
+platform: [darwin, linux, win32]
+credentials: [google_docs_access_token]
+allow_list: [https://docs.googleapis.com/v1/documents, https://www.googleapis.com/drive/v3/files]
+---
+
+# Google Docs
+
+Use `docs_create` to create a document and `docs_append_text` to add text or
+pages to it; use `http_request` for everything else (get, replace, insert at a
+position, delete ranges, Drive search, trash). For each `http_request`, set
+`auth.tokenCredentialKey` to `google_docs_access_token`.
+
+Never use `exec`, Python, curl, shell flags such as `-H`/`-d`, or a JSON string
+to make a Google Docs request. Call one tool per operation with one complete
+structured object. In particular, `body` must be an object, not a serialized
+JSON string; the tool JSON-encodes it and sets `Content-Type: application/json`
+automatically.
+
+## Load the Recipe File First
+
+This file carries no requests. The working request shapes live in three
+reference files — load the one for the job with the `skill` tool BEFORE calling
+`http_request`, then copy its request 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 documents** — "what does document X say", "summarize
+  my doc", "find / list my documents": call the `skill` tool with
+  `name: "google-docs"` and `file: "references/read.md"`.
+- **Creating a new document** (no existing document involved; one page or
+  many): call the `skill` tool with `name: "google-docs"` and
+  `file: "references/create.md"` — it covers `docs_create` and filling the
+  document with `docs_append_text`.
+- **Changing an existing document** — append or insert text, find and
+  replace, delete a passage, move it to the trash: call the `skill` tool with
+  `name: "google-docs"` and `file: "references/edit.md"`.
+
+Never write a request from memory. The recipes carry the exact request shapes
+(`batchUpdate` request names, index rules, page limits) that fail in
+non-obvious ways when improvised; loading the file is one cheap read-only call.
+
+## Prerequisites
+
+Google Docs 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 Docs from Settings, or to
+set the `google_docs_access_token` credential.
+
+If Google returns `403 PERMISSION_DENIED` with reason `SERVICE_DISABLED`, the
+credential is working but the OAuth client's Google Cloud project has not
+enabled the Google Docs API. Do not ask the user to reconnect. Tell the project
+owner to open the response's `activationUrl`, enable the API, and retry after
+propagation.
+
+## Identifiers
+
+Documents are identified by `documentId` — the alphanumeric string in the URL
+`docs.google.com/document/d/{documentId}/...`, and the `documentId` field of a
+create response. Listing and searching documents go through the Google Drive
+API (`references/read.md`), never the Docs API.
+
+## Output Policy
+
+- For document reads, extract and present the text content clearly — do not
+  echo the raw JSON structure.
+- For edits, confirm the change with the user first (what text is being
+  inserted, replaced, or deleted) unless they already spelled it out.
+- Report success only when the `batchUpdate` response contains `replies` with
+  no errors, and name the document (title or link) in the answer.

package/skills/google-docs/operations.json

@@ -0,0 +1,61 @@
+{
+  "operations": [
+    {
+      "tool": "docs_create",
+      "description": "Create an empty Google Doc with a title. Call it exactly once per requested document, then append content with docs_append_text using the returned documentId.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Document title"
+          }
+        },
+        "required": [
+          "title"
+        ]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://docs.googleapis.com/v1/documents",
+        "builder": "docs-create"
+      },
+      "response": {
+        "pick": [
+          "documentId",
+          "title"
+        ]
+      }
+    },
+    {
+      "tool": "docs_append_text",
+      "description": "Append text to the end of a Google Doc, optionally followed by a page break. One page (80 words or fewer) per call; set pageBreak on every page except the last. Never compute indexes yourself.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "documentId": {
+            "type": "string",
+            "description": "Document id, from docs_create or the docs.google.com/document/d/{id} URL"
+          },
+          "text": {
+            "type": "string",
+            "description": "Text to append; end it with a newline"
+          },
+          "pageBreak": {
+            "type": "boolean",
+            "description": "Insert a page break after the text"
+          }
+        },
+        "required": [
+          "documentId",
+          "text"
+        ]
+      },
+      "request": {
+        "method": "POST",
+        "url": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
+        "builder": "docs-append-text"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,97 @@
+# Creating a Google Doc
+
+Two typed tools do the whole job: `docs_create` makes the document,
+`docs_append_text` fills it. Typed tools select their own credential. For each fallback `http_request`,
+set `auth.tokenCredentialKey` to `google_docs_access_token`.
+
+## Create the document
+
+Call `docs_create` with the title:
+
+```json
+{ "title": "My Document" }
+```
+
+The result contains the `documentId`. Capture it and keep using it.
+Create the document exactly once. Do not follow a successful create with a
+Drive search, a GET, or another create just to rediscover the ID. If the result has no
+`documentId`, stop and report that response problem; never append without the
+ID.
+
+## Add the content
+
+Call `docs_append_text` once per page. Put the document title as the first
+line of the first page instead of spending a call on a heading, end the text
+with a newline, and keep each call at 80 words or fewer. The 80-word limit
+applies even when the user asks for only one page. Never expand a one-page
+request into a long list in one call.
+
+```json
+{
+  "documentId": "<id from docs_create>",
+  "text": "My Document\n\nConcise content.\n",
+  "pageBreak": false
+}
+```
+
+## Multi-page documents
+
+One requested page per `docs_append_text` call, in order, each 80 words or
+fewer, with `"pageBreak": true` on every page except the last — five requested
+pages therefore take five append calls. Wait for a successful result before
+appending the next page. Do not place several pages of text in one call: if
+the tool reports the arguments are not valid JSON, the call was too large or
+incomplete, so retry only that page with shorter text.
+
+## Finishing
+
+Report success only when every append result came back without an error.
+Answer with the document title and the link
+`https://docs.google.com/document/d/{documentId}/edit`; do not read the
+document back to "confirm".
+
+## Without the typed tools
+
+The typed tools wrap these two Docs API requests; use them only if the typed
+tools are missing from this chat:
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "POST",
+  "body": { "title": "My Document" }
+}
+```
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "POST",
+  "body": {
+    "requests": [
+      {
+        "insertText": {
+          "endOfSegmentLocation": {},
+          "text": "Page heading\n\nConcise page content.\n"
+        }
+      },
+      { "insertPageBreak": { "endOfSegmentLocation": {} } }
+    ]
+  }
+}
+```
+
+Then it is one requested page per `batchUpdate` call, the same 80-word limit,
+and the `insertPageBreak` request omitted on the last page;
+never call `/v1/documents:batchUpdate` without the ID.
+
+## Common Mistakes
+
+- Recreating or searching for a document after a successful create instead of
+  using the returned `documentId` — this produces duplicates and wastes rounds.
+- Sending a whole multi-page document in one call — one page of at most 80
+  words per call, `pageBreak` on every page except the last.
+- Computing indexes yourself — `docs_append_text` and `endOfSegmentLocation`
+  never need one.

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

@@ -0,0 +1,146 @@
+# Editing an Existing Google Doc
+
+Every request is one `http_request` call with a structured object. For each request, set `auth.tokenCredentialKey` to `google_docs_access_token`. All content edits go through
+`batchUpdate` — there is no PATCH endpoint for document body changes.
+
+Get the `documentId` from the URL the user gave, from an earlier create
+response, or from a Drive search (`references/read.md`).
+
+Every `http_request` edit is ONE `POST …:batchUpdate` whose body is `{ "requests": [ … ] }` —
+a bare request object without the `requests` array is rejected with 400. Copy
+the request shapes below exactly: the field names are fixed by Google, and any
+other name (`searchText`, `replacementText`, `find`, `replace`, `newText`) fails
+with `Unknown name`. One edit per user request — an edit never needs a
+preceding insert of text that is already in the document.
+
+## Append text
+
+Call `docs_append_text` — it appends at the end of the document with no index
+arithmetic and no preliminary GET. End the text with a newline; keep it at 80
+words or fewer per call.
+
+```json
+{
+  "documentId": "<documentId>",
+  "text": "\nNew paragraph.\n",
+  "pageBreak": false
+}
+```
+
+The raw equivalent, for when the typed tool is missing from this chat, is a
+`batchUpdate` with `"insertText": { "endOfSegmentLocation": {}, "text": "…" }`.
+
+## Insert text at a position
+
+Use an explicit `location.index` only when editing at a known position. A new
+blank document's first valid insertion point is index 1; index 2 is outside its
+empty paragraph. Indexes count UTF-16 code units and change with every edit, so
+`GET` the document first when you need one.
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "POST",
+  "body": {
+    "requests": [
+      {
+        "insertText": {
+          "location": { "index": 1 },
+          "text": "Hello, World!"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Replace all text matching a pattern
+
+Use `replaceAllText` to find and replace — exactly these keys:
+`containsText` (with `text` and optional `matchCase`) and `replaceText`.
+`containsText.text` is a regex — escape special characters (`.`, `*`, `+`,
+`?`, `[`, `]`, `(`, `)`, `{`, `}`, `^`, `$`, `|`, `\`). No `GET` is needed
+first, and no `insertText` belongs in the same request.
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "POST",
+  "body": {
+    "requests": [
+      {
+        "replaceAllText": {
+          "containsText": { "text": "old text", "matchCase": true },
+          "replaceText": "new text"
+        }
+      }
+    ]
+  }
+}
+```
+
+The reply's `occurrencesChanged` says how many matches were replaced; `0` means
+the text was not found — tell the user instead of retrying with guesses.
+
+## Delete a range of text
+
+Fetch the document first, then specify the start and exclusive end index.
+
+```json
+{
+  "url": "https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "POST",
+  "body": {
+    "requests": [
+      {
+        "deleteContentRange": {
+          "range": { "startIndex": 10, "endIndex": 20 }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Move a document 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
+document.
+
+```json
+{
+  "url": "https://www.googleapis.com/drive/v3/files/{documentId}",
+  "auth": { "tokenCredentialKey": "google_docs_access_token" },
+  "method": "PATCH",
+  "body": { "trashed": true }
+}
+```
+
+## Finishing
+
+Report success only when the `batchUpdate` response contains `replies` with no
+errors. Do not read the document back to confirm an edit.
+
+## Common Mistakes
+
+- Using PATCH on the document body instead of `batchUpdate` — PATCH only
+  updates metadata like title, not content.
+- Treating indexes like array offsets — they count UTF-16 code units, range
+  ends are exclusive, and a blank document's first usable body index is 1.
+- Using `insertionIndex` or placing `location.index` directly under
+  `insertText` — the supported shape is `insertText.location.index`; for
+  appends, prefer `insertText.endOfSegmentLocation`.
+- Attempting a numeric-position edit without fetching the document first — you
+  won't know the current indexes.
+- Not escaping regex special characters in `containsText` patterns.
+- Renaming the fields — `searchText`, `replacementText`, `replacement`, `find`
+  all return 400 `Unknown name`; only `containsText` + `replaceText` exist.
+- Sending a request object without the `{ "requests": [ … ] }` wrapper.
+- Inserting text that is already in the document before an edit — a replace or
+  delete works on the existing content directly.
+- Passing curl/Python text or serialized JSON to `http_request` instead of one
+  structured tool-call object.