@acedatacloud/skills 2026.504.4 → 2026.504.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.504.4",
+  "version": "2026.504.5",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/google-calendar/SKILL.md

@@ -1,38 +1,48 @@
 ---
 name: google-calendar
-description: Read Google Calendar events / agenda / free-busy / invitations via the Calendar v3 REST API. Use when the user mentions Google Calendar events, today's agenda, this week's meetings, finding conflicts, listing invitations, or checking free time on a specific calendar.
+description: Read and manage Google Calendar events / agenda / free-busy / invitations via the Calendar v3 REST API. Use when the user mentions Google Calendar events, today's agenda, this week's meetings, finding conflicts, listing invitations, checking free time, or scheduling / rescheduling / cancelling a meeting.
 when_to_use: |
-  Trigger when the user wants to read events from their Google
-  Calendar — list / search / inspect events, build today's or this
-  week's agenda, check free / busy windows, or pull invite details
-  for a specific meeting. The installed connector grants read-only
-  scope (`calendar.readonly`); creating / updating / cancelling
-  events is out of scope.
+  Trigger when the user wants to read or manage events on their
+  Google Calendar — list / search / inspect events, build today's
+  or this week's agenda, check free / busy windows, pull invite
+  details, or have the AI create / update / cancel events on their
+  behalf and email invites to attendees. The installed connector
+  always grants `calendar.readonly`; the user opts in to the
+  broader `calendar` scope (full read + write) at install — confirm
+  before destructive writes.
 connections: [google/calendar]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
 Drive Google Calendar via `curl + jq`. The user's OAuth bearer token
 is in `$GOOGLE_CALENDAR_TOKEN`; every call needs it as
-`Authorization: Bearer $GOOGLE_CALENDAR_TOKEN`. The token already
-carries the `calendar.readonly` scope the user agreed to at install
-plus the identity scopes (`openid email profile`).
+`Authorization: Bearer $GOOGLE_CALENDAR_TOKEN`. At minimum the token
+carries `calendar.readonly` plus the identity scopes
+(`openid email profile`); if the user opted in to write at install
+time it also carries the broader `calendar` scope (read + write).
 
 The Calendar API returns standard JSON; failures surface as
 `{"error": {"code": 401|403|..., "message": "..."}}` — show that
 error verbatim. `401` means the token expired (re-install). `403
-insufficientPermissions` means the user is asking for a write this
-connector cannot satisfy — say so.
+insufficientPermissions` on a write means the user only granted
+`calendar.readonly` — ask them to re-install the connector with the
+read+write box checked.
 
 **Always start with `users/me/calendarList`** to learn which calendars
 the account can see (the user's primary plus any subscribed / shared
 ones), AND with `users/me/settings/timezone` so you render times in
 the user's local zone instead of UTC.
 
+**Before any destructive write** (creating, moving, or cancelling an
+event that has attendees) show the exact event details and ask the
+user to confirm. When attendees are involved, also confirm whether
+they want Google to email the attendees — that's controlled by the
+`sendUpdates` query parameter.
+
 ## Recipes
 
 ### Verify auth + discover calendars (always run first)
@@ -182,14 +192,150 @@ while : ; do
 done
 ```
 
+## Write recipes
+
+These all need the broader `calendar` scope. If the user only granted
+`calendar.readonly` you'll get `403 insufficientPermissions` —
+surface that and ask them to re-install with the read+write box
+checked. **Always echo the event summary, time and attendee list
+back to the user before creating or cancelling anything.**
+
+### Create a single event (with optional attendees + Google Meet link)
+
+```sh
+TZ=$(curl -sS -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  "https://www.googleapis.com/calendar/v3/users/me/settings/timezone" | jq -r .value)
+
+cat > /tmp/_cal_event.json <<JSON
+{
+  "summary": "Sync — Q2 OKR review",
+  "location": "Online",
+  "description": "Drafted by AceDataCloud.",
+  "start": {"dateTime": "2026-05-12T10:00:00", "timeZone": "$TZ"},
+  "end":   {"dateTime": "2026-05-12T10:30:00", "timeZone": "$TZ"},
+  "attendees": [
+    {"email": "alice@example.com"},
+    {"email": "bob@example.com"}
+  ],
+  "reminders": {"useDefault": true},
+  "conferenceData": {
+    "createRequest": {
+      "requestId": "meet-$(date +%s)",
+      "conferenceSolutionKey": {"type": "hangoutsMeet"}
+    }
+  }
+}
+JSON
+
+# sendUpdates: 'all' = email all attendees; 'externalOnly' = only non-org; 'none' = silent
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data @/tmp/_cal_event.json \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events?conferenceDataVersion=1&sendUpdates=all" \
+  | jq '{id, htmlLink, hangoutLink, summary, start, end, attendees}'
+```
+
+Drop the `conferenceData` block if the user didn't ask for a Meet
+link — it'll fall back to a plain event.
+
+### Create a recurring event
+
+```sh
+TZ=$(curl -sS -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  "https://www.googleapis.com/calendar/v3/users/me/settings/timezone" | jq -r .value)
+cat > /tmp/_cal_recur.json <<JSON
+{
+  "summary": "Weekly 1:1",
+  "start": {"dateTime": "2026-05-12T15:00:00", "timeZone": "$TZ"},
+  "end":   {"dateTime": "2026-05-12T15:30:00", "timeZone": "$TZ"},
+  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=TU;COUNT=12"]
+}
+JSON
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data @/tmp/_cal_recur.json \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
+  | jq '{id, recurrence, summary}'
+```
+
+RRULE follows RFC 5545. Common patterns: `FREQ=DAILY`, `FREQ=WEEKLY;BYDAY=MO,WE,FR`,
+`FREQ=MONTHLY;BYMONTHDAY=15`. Add `UNTIL=20261231T235959Z` or `COUNT=12`
+for a hard stop.
+
+### Update an existing event (PATCH — partial update)
+
+```sh
+EVENT_ID='abc123def4567890ghijklmnop'
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"location":"Conference Room 4","description":"Now in-person."}' \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events/$EVENT_ID?sendUpdates=all" \
+  | jq '{id, summary, location, description}'
+```
+
+`PATCH` only changes the fields you send; `PUT` replaces the entire
+event payload. Prefer `PATCH`.
+
+### Reschedule an event
+
+```sh
+EVENT_ID='abc123def4567890ghijklmnop'
+TZ=$(curl -sS -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  "https://www.googleapis.com/calendar/v3/users/me/settings/timezone" | jq -r .value)
+cat > /tmp/_cal_resched.json <<JSON
+{
+  "start": {"dateTime": "2026-05-12T14:00:00", "timeZone": "$TZ"},
+  "end":   {"dateTime": "2026-05-12T14:30:00", "timeZone": "$TZ"}
+}
+JSON
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data @/tmp/_cal_resched.json \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events/$EVENT_ID?sendUpdates=all" \
+  | jq '{id, summary, start, end}'
+```
+
+### Add or change attendees
+
+Google requires you to send the **complete** attendee list when
+patching attendees — fetch the current list, mutate, send back:
+
+```sh
+EVENT_ID='abc123def4567890ghijklmnop'
+CURRENT=$(curl -sS -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events/$EVENT_ID?fields=attendees" \
+  | jq '.attendees // []')
+NEW=$(echo "$CURRENT" | jq '. + [{"email":"carol@example.com"}]')
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"attendees\": $NEW}" \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events/$EVENT_ID?sendUpdates=all" \
+  | jq '{id, attendees}'
+```
+
+### Cancel / delete an event
+
+```sh
+EVENT_ID='abc123def4567890ghijklmnop'
+curl -sS -X DELETE -H "Authorization: Bearer $GOOGLE_CALENDAR_TOKEN" \
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events/$EVENT_ID?sendUpdates=all" \
+  -o /dev/null -w 'HTTP %{http_code}\n'
+```
+
+`204` = success. To cancel one occurrence of a recurring event, fetch
+the instance with `events.instances` first, then `DELETE` the
+specific instance id (it has a longer `EVENT_ID_YYYYMMDDTHHMMSSZ`
+shape).
+
 ## Common error codes
 
 | HTTP | meaning | what to tell the user |
 |---|---|---|
 | `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Google Calendar connector on the Connections page." |
-| `403 insufficientPermissions` | scope missing | "This connector is read-only — creating or modifying events isn't possible." |
+| `403 insufficientPermissions` | write scope missing | "This action needs the Calendar read+write scope, but only `calendar.readonly` was granted. Re-install the connector with the read+write box checked." |
 | `403 forbidden` | calendar id not visible to this account | check `calendarList` first; if it's a shared calendar, the owner needs to share it. |
 | `404 notFound` | wrong event / calendar id | double-check the id and try `calendarList` to confirm the calendar exists. |
+| `409 conflict` | recurring event id collision | append a UUID to your `requestId` and retry. |
 | `429 quotaExceeded` | quota / throttling | back off ~5s, then retry once. |
 
 Never log or echo `$GOOGLE_CALENDAR_TOKEN` — treat it as a secret.

package/skills/google-drive/SKILL.md

@@ -1,32 +1,40 @@
 ---
 name: google-drive
-description: Read and search Google Drive files / folders / shared content via the Drive v3 REST API. Use when the user mentions Drive files, "my drive", shared documents, Google Docs / Sheets / Slides, exporting / downloading a Drive file, or searching by name / owner / folder.
+description: Read, search, upload, rename, move and delete Google Drive files / folders / shared content via the Drive v3 REST API. Use when the user mentions Drive files, "my drive", shared documents, Google Docs / Sheets / Slides, exporting / downloading a Drive file, searching by name / owner / folder, uploading a new file, renaming or moving files, or organising folders.
 when_to_use: |
-  Trigger when the user wants to list, search, read or download files
-  in their Google Drive — including Google-native docs (Docs / Sheets /
-  Slides) which need a special "export" call to get plain content. The
-  installed connector grants read-only scope (`drive.readonly`); writes
-  are out of scope.
+  Trigger when the user wants to list, search, read, download or
+  modify files in their Google Drive — including Google-native docs
+  (Docs / Sheets / Slides) which need a special "export" call to get
+  plain content, as well as uploads, renames, folder moves, and
+  trashing files. The installed connector always grants `drive.readonly`;
+  the user opts in to the broader `drive` scope (full read + write)
+  at install time — confirm before performing destructive writes.
 connections: [google/drive]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
 Drive Google Drive via `curl + jq`. The user's OAuth bearer token is
 in `$GOOGLE_DRIVE_TOKEN`; every call needs it as
-`Authorization: Bearer $GOOGLE_DRIVE_TOKEN`. The token already carries
-the `drive.readonly` scope the user agreed to at install plus the
-identity scopes (`openid email profile`).
+`Authorization: Bearer $GOOGLE_DRIVE_TOKEN`. At minimum the token
+carries `drive.readonly` plus the identity scopes
+(`openid email profile`); if the user opted in to write at install
+time it also carries the broader `drive` scope (full read + write).
 
 The Drive API returns standard JSON; failures surface as
 `{"error": {"code": 401|403|..., "message": "..."}}` — show that
 error verbatim to the user. `401` means the token expired and the
 user must re-install the connector. `403 insufficientPermissions`
-means the connector grants only `drive.readonly` and the user is
-asking for a write — say so explicitly.
+on a write means the user did not grant the `drive` scope at install
+— ask them to re-install with the read+write box checked.
+
+**Before any destructive write** (renaming, moving, trashing, or
+bulk-mutating files) show the exact target list and ask the user to
+confirm. Never trash by guessing an id — always echo back the file
+name + path you're about to touch.
 
 **Always start with `/about?fields=user`** to confirm the connection
 works AND learn which Google account you're operating against.
@@ -188,14 +196,153 @@ while : ; do
 done
 ```
 
+## Write recipes
+
+These all need the broader `drive` scope. If the user only granted
+`drive.readonly` you'll get `403 insufficientPermissions` — surface
+that and suggest re-installing with the read+write box checked.
+**Always echo the target name + path back to the user before
+trashing or bulk-moving anything.**
+
+### Rename a file
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+NEW_NAME='2026 Q2 OKR (final).gdoc'
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"name\":$(jq -nr --arg n "$NEW_NAME" '$n')}" \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?fields=id,name"
+```
+
+### Move a file to a different folder
+
+Drive's folder model is parent-id based. Move = remove old parent,
+add new parent:
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+NEW_PARENT='1XYZnewFolderId'
+
+# Read existing parents (so we can pass them in removeParents)
+OLD_PARENTS=$(curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?fields=parents" \
+  | jq -r '.parents | join(",")')
+
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --data '' \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?addParents=$NEW_PARENT&removeParents=$OLD_PARENTS&fields=id,name,parents"
+```
+
+### Create a new folder
+
+```sh
+PARENT_ID='1XYZparentFolderId'  # or 'root' for My Drive root
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"name\":\"Reports / 2026Q2\",\"mimeType\":\"application/vnd.google-apps.folder\",\"parents\":[\"$PARENT_ID\"]}" \
+  "https://www.googleapis.com/drive/v3/files?fields=id,name,webViewLink" \
+  | jq
+```
+
+### Upload a file (multipart so metadata + bytes go in one request)
+
+```sh
+LOCAL=/tmp/report.pdf
+NAME='Q2 report.pdf'
+PARENT_ID='1XYZparentFolderId'
+MIME='application/pdf'
+
+BOUNDARY='aceDataBoundary'
+META=$(jq -nc --arg n "$NAME" --arg p "$PARENT_ID" '{name:$n, parents:[$p]}')
+{
+  printf -- '--%s\r\n' "$BOUNDARY"
+  printf 'Content-Type: application/json; charset=UTF-8\r\n\r\n'
+  printf '%s\r\n' "$META"
+  printf -- '--%s\r\n' "$BOUNDARY"
+  printf 'Content-Type: %s\r\n\r\n' "$MIME"
+  cat "$LOCAL"
+  printf '\r\n--%s--\r\n' "$BOUNDARY"
+} > /tmp/_drive_upload.bin
+
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H "Content-Type: multipart/related; boundary=$BOUNDARY" \
+  --data-binary @/tmp/_drive_upload.bin \
+  "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart&fields=id,name,webViewLink" \
+  | jq
+```
+
+For a **media-only** upload (no metadata) use `uploadType=media`; for
+files >5 MB use `uploadType=resumable` (covered in [Drive's docs]
+(https://developers.google.com/drive/api/guides/manage-uploads#resumable)).
+
+### Replace the contents of an existing file
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+LOCAL=/tmp/report-v2.pdf
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H 'Content-Type: application/pdf' \
+  --data-binary @"$LOCAL" \
+  "https://www.googleapis.com/upload/drive/v3/files/$FILE_ID?uploadType=media&fields=id,name,modifiedTime"
+```
+
+Metadata stays the same (id / parents / name) — only the bytes are
+replaced and Drive bumps `modifiedTime`.
+
+### Trash a file (or restore one)
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"trashed":true}' \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?fields=id,name,trashed"
+
+# Restore:
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"trashed":false}' \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?fields=id,name,trashed"
+```
+
+Prefer `trashed:true` over `DELETE` — `DELETE` is permanent and the
+user can't undo it. Only use `DELETE` when they explicitly say
+"permanently delete".
+
+### Bulk "move every PDF in the root to /Documents/PDF" (confirmation pattern)
+
+```sh
+# 1. List candidates and show the user before doing anything
+DST_FOLDER_ID='1XYZdocsPdfFolder'
+ROOT_ID='root'
+
+CANDS=$(curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --get "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode "q='$ROOT_ID' in parents and mimeType='application/pdf' and trashed=false" \
+  --data-urlencode 'fields=files(id,name,webViewLink)' \
+  | jq '.files')
+echo "$CANDS" | jq -r '.[] | "- \(.name)"'
+
+# 2. (after user confirms) actually move
+echo "$CANDS" | jq -r '.[] | .id' | while read FID; do
+  curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+    --data '' \
+    "https://www.googleapis.com/drive/v3/files/$FID?addParents=$DST_FOLDER_ID&removeParents=$ROOT_ID&fields=id,name,parents" \
+    | jq -c '{id, name, parents}'
+done
+```
+
 ## Common error codes
 
 | HTTP | meaning | what to tell the user |
 |---|---|---|
 | `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Google Drive connector on the Connections page." |
-| `403 insufficientPermissions` | scope missing | "Your installed connector only grants read access — this action needs a write scope we don't have." |
+| `403 insufficientPermissions` | write scope missing | "This action needs the Drive read+write scope, but only `drive.readonly` was granted at install. Re-install the connector and check the read+write box." |
 | `403 userRateLimitExceeded` | quota | retry once after 5–10s; if it persists, tell the user. |
 | `404 notFound` | wrong file id OR file isn't visible to this account | double-check the id; if shared, use `sharedWithMe` query above. |
 | `400 invalidQuery` | malformed `q` | print the `q` you sent + the error message back to the user. |
 
 Never log or echo `$GOOGLE_DRIVE_TOKEN` — treat it as a secret.
+
+Never log or echo `$GOOGLE_DRIVE_TOKEN` — treat it as a secret.

package/skills/google-gmail/SKILL.md

@@ -1,31 +1,44 @@
 ---
 name: google-gmail
-description: Read, search and triage Gmail mail / threads / labels / attachments via the Gmail v1 REST API. Use when the user mentions Gmail, "my inbox", unread mail, recent emails from someone, summarising a thread, downloading an attachment, or finding mail by label / query.
+description: Read, search, triage, label, archive and send Gmail mail / threads / labels / attachments via the Gmail v1 REST API. Use when the user mentions Gmail, "my inbox", unread mail, recent emails from someone, summarising a thread, downloading an attachment, finding mail by label / query, archiving or labelling a thread, or drafting and sending a reply / new message.
 when_to_use: |
-  Trigger when the user wants to read, list, search, summarise or
-  inspect Gmail mail — including triaging the inbox, surfacing unread,
-  pulling a single thread for review, or downloading an attachment.
-  The installed connector grants read-only scope (`gmail.readonly`);
-  sending / replying / archiving / labelling are out of scope.
+  Trigger when the user wants to read, list, search, summarise,
+  inspect, modify or send Gmail mail — including triaging the inbox,
+  surfacing unread, pulling a single thread, downloading an
+  attachment, archiving / labelling / trashing messages, or having
+  the AI draft and send a reply or new message on their behalf.
+  The installed connector always grants `gmail.readonly`; the user
+  also opts in to `gmail.modify` (label / archive / trash) and
+  `gmail.send` (compose + send) at install time — confirm the action
+  is in scope before issuing it.
 connections: [google/gmail]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
 Drive Gmail via `curl + jq`. The user's OAuth bearer token is in
 `$GOOGLE_GMAIL_TOKEN`; every call needs it as
-`Authorization: Bearer $GOOGLE_GMAIL_TOKEN`. The token already
-carries the `gmail.readonly` scope the user agreed to at install plus
-the identity scopes (`openid email profile`).
+`Authorization: Bearer $GOOGLE_GMAIL_TOKEN`. At minimum the token
+carries `gmail.readonly` plus the identity scopes
+(`openid email profile`); if the user opted in to write at install
+time it also carries `gmail.modify` (label / archive / trash) and/or
+`gmail.send` (compose + send). Always assume the narrowest scope
+until a write actually fails — don't ask Google for new scopes from
+here.
 
 The Gmail API returns standard JSON; failures surface as
 `{"error": {"code": 401|403|..., "message": "..."}}` — show that
-error verbatim. `401` means the token expired (re-install). `403`
-or `400 insufficientPermissions` means the user is asking for a write
-this connector cannot satisfy — say so.
+error verbatim. `401` means the token expired (re-install). `403
+insufficientPermissions` means the user didn't grant the write scope
+this call needs — explain which scope is missing and suggest
+re-installing the connector with the matching write box checked.
+
+**Before any destructive write** (trashing a thread, sending an email)
+show the user the exact target / draft and ask them to confirm. Don't
+fan out across many messages without an explicit go-ahead.
 
 **Always start with `users/me/profile`** to confirm the connection works
 AND learn which Gmail account you're operating against. Mailbox payloads
@@ -201,12 +214,169 @@ while : ; do
 done
 ```
 
+## Write recipes
+
+These all need `gmail.modify` (label / archive / trash) or
+`gmail.send` (compose + send). If the user only granted
+`gmail.readonly` at install you'll get `403 insufficientPermissions`
+— surface that and ask them to re-install with the write boxes
+checked.
+
+### Mark a message read / unread, star it, archive it (gmail.modify)
+
+```sh
+MSG_ID='18f1a2b3c4d5e6f0'
+
+# Mark as read = remove the UNREAD label
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"removeLabelIds":["UNREAD"]}' \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/modify"
+
+# Star it = add the STARRED label
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"addLabelIds":["STARRED"]}' \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/modify"
+
+# Archive = remove from INBOX (keeps in All Mail)
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"removeLabelIds":["INBOX"]}' \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/modify"
+```
+
+The `modify` endpoint takes `addLabelIds` and `removeLabelIds`
+together — useful for atomic "archive + label" moves. Use the same
+shape on `/threads/$THREAD_ID/modify` to apply across a whole thread.
+
+### Apply a custom label
+
+```sh
+# 1. find or remember the label id from labels.list
+LABEL_ID='Label_4'
+MSG_ID='18f1a2b3c4d5e6f0'
+
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"addLabelIds\":[\"$LABEL_ID\"]}" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/modify"
+```
+
+Creating a brand-new label needs the same scope:
+
+```sh
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"name":"Follow up","messageListVisibility":"show","labelListVisibility":"labelShow"}' \
+  "https://gmail.googleapis.com/gmail/v1/users/me/labels" \
+  | jq '{id, name}'
+```
+
+### Trash a message or thread
+
+```sh
+MSG_ID='18f1a2b3c4d5e6f0'
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/trash"
+
+# Whole thread:
+THREAD_ID='18f1a2b3c4d5e6f0'
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/threads/$THREAD_ID/trash"
+```
+
+Use `/untrash` (same shape) to restore. **Never** use
+`messages.delete` — it permanently deletes and needs a higher scope
+that we don't request.
+
+### Send a brand-new email (gmail.send)
+
+Gmail wants the message as a base64url-encoded RFC 2822 string.
+
+```sh
+# Compose the message
+TO='alice@example.com'
+SUBJECT='Quick hello'
+BODY='Hi Alice,
+
+Just a quick test note from the AceDataCloud Gmail connector.
+
+Best,
+Qingcai'
+
+# Multi-line subject lines need MIME encoded-word for non-ASCII; ASCII is fine raw.
+RAW=$(printf 'To: %s\r\nSubject: %s\r\nContent-Type: text/plain; charset=UTF-8\r\nMIME-Version: 1.0\r\n\r\n%s' \
+  "$TO" "$SUBJECT" "$BODY" \
+  | base64 | tr -d '\n' | tr '+/' '-_' | tr -d '=')
+
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"raw\":\"$RAW\"}" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \
+  | jq '{id, threadId, labelIds}'
+```
+
+For non-ASCII subjects (Chinese / emoji), use MIME encoded-word:
+
+```sh
+SUBJECT_RAW='你好，季度复盘草稿'
+SUBJECT_ENCODED="=?UTF-8?B?$(printf %s "$SUBJECT_RAW" | base64)?="
+```
+
+### Reply in-thread (keeps the thread together)
+
+Reply by setting the `In-Reply-To` and `References` headers to the
+Message-Id of the message you're replying to, **and** pass the
+Gmail thread id in the API body:
+
+```sh
+ORIG_MSG_ID='18f1a2b3c4d5e6f0'
+ORIG=$(curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages/$ORIG_MSG_ID" \
+  --data-urlencode 'format=metadata' \
+  --data-urlencode 'metadataHeaders=Message-ID' \
+  --data-urlencode 'metadataHeaders=Subject' \
+  --data-urlencode 'metadataHeaders=From')
+MID=$(echo "$ORIG" | jq -r '.payload.headers | from_entries | .["Message-ID"] // .["Message-Id"]')
+FROM=$(echo "$ORIG" | jq -r '.payload.headers | from_entries | .From')
+SUBJ=$(echo "$ORIG" | jq -r '.payload.headers | from_entries | .Subject')
+TID=$(echo "$ORIG" | jq -r .threadId)
+
+RAW=$(printf 'To: %s\r\nSubject: Re: %s\r\nIn-Reply-To: %s\r\nReferences: %s\r\nContent-Type: text/plain; charset=UTF-8\r\nMIME-Version: 1.0\r\n\r\n%s' \
+  "$FROM" "$SUBJ" "$MID" "$MID" \
+  'Replying inline — will follow up later today.' \
+  | base64 | tr -d '\n' | tr '+/' '-_' | tr -d '=')
+
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"raw\":\"$RAW\",\"threadId\":\"$TID\"}" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" \
+  | jq '{id, threadId}'
+```
+
+Without the `threadId` in the body Gmail starts a brand-new thread
+even with the right `In-Reply-To` headers.
+
+### Save a draft instead of sending
+
+Same `raw` payload, different endpoint — still costs `gmail.send`
+(`drafts` shares the send scope under the hood for write):
+
+```sh
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"message\":{\"raw\":\"$RAW\"}}" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/drafts" \
+  | jq '{id, message: {id: .message.id, threadId: .message.threadId}}'
+```
+
 ## Common error codes
 
 | HTTP | meaning | what to tell the user |
 |---|---|---|
 | `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Gmail connector on the Connections page." |
-| `403 insufficientPermissions` | scope missing | "This connector grants only read access — modifying mail isn't possible." |
+| `403 insufficientPermissions` | scope missing | identify which scope (`gmail.modify` for label/archive/trash, `gmail.send` for sending) and suggest re-installing the connector with that box checked. |
 | `403 userRateLimitExceeded` / `429` | quota / throttling | back off ~5s, then retry once. |
 | `404 notFound` | wrong message / thread / attachment id | double-check the id, or fall back to `messages.list` with the right query. |
 | `400 invalidQuery` | malformed `q` | print the `q` you sent + the error back to the user. |

package/skills/google-tasks/SKILL.md

@@ -1,36 +1,43 @@
 ---
 name: google-tasks
-description: Read Google Tasks task lists and individual tasks via the Tasks v1 REST API. Use when the user mentions Google Tasks, todo / pending / overdue tasks, weekly task recap, or grouping todos by list.
+description: Read and manage Google Tasks task lists and individual tasks via the Tasks v1 REST API. Use when the user mentions Google Tasks, todo / pending / overdue tasks, weekly task recap, grouping todos by list, adding or completing a task, or moving / deleting tasks.
 when_to_use: |
-  Trigger when the user wants to inspect their Google Tasks — list
-  task lists, surface pending items, group by due date, or pull
-  details for one task. The installed connector grants read-only
-  scope (`tasks.readonly`); creating / updating / deleting tasks is
-  out of scope.
+  Trigger when the user wants to inspect or manage their Google
+  Tasks — list task lists, surface pending items, group by due date,
+  pull details for one task, add new todos, mark items complete,
+  re-order or delete tasks. The installed connector always grants
+  `tasks.readonly`; the user opts in to the broader `tasks` scope
+  (full read + write) at install — confirm before destructive writes.
 connections: [google/tasks]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
 Drive Google Tasks via `curl + jq`. The user's OAuth bearer token is
 in `$GOOGLE_TASKS_TOKEN`; every call needs it as
-`Authorization: Bearer $GOOGLE_TASKS_TOKEN`. The token already
-carries the `tasks.readonly` scope the user agreed to at install plus
-the identity scopes (`openid email profile`).
+`Authorization: Bearer $GOOGLE_TASKS_TOKEN`. At minimum the token
+carries `tasks.readonly` plus the identity scopes
+(`openid email profile`); if the user opted in to write at install
+time it also carries the broader `tasks` scope (read + write).
 
 The Tasks API returns standard JSON; failures surface as
 `{"error": {"code": 401|403|..., "message": "..."}}` — show that
 error verbatim. `401` means the token expired (re-install). `403
-insufficientPermissions` means the user is asking for a write this
-connector cannot satisfy — say so.
+insufficientPermissions` on a write means the user only granted
+`tasks.readonly` — ask them to re-install with the read+write box
+checked.
 
 **Always start with `users/@me/lists`** to discover which task lists
 the account has — the user's default plus any extras they created on
 calendar.google.com or in the Tasks app.
 
+**Before bulk creates / completions / deletes** echo the exact
+titles back to the user and ask them to confirm. Don't trash a
+task by guessing an id.
+
 ## Recipes
 
 ### Verify auth + list all task lists (always run first)
@@ -173,12 +180,115 @@ while : ; do
 done
 ```
 
+## Write recipes
+
+These all need the broader `tasks` scope. If the user only granted
+`tasks.readonly` you'll get `403 insufficientPermissions` — surface
+that and ask them to re-install with the read+write box checked.
+
+### Add a new task
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"title":"Draft Q2 plan","notes":"Outline + risks + asks.","due":"2026-05-15T00:00:00.000Z"}' \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+  | jq '{id, title, due, status}'
+```
+
+Google stores `due` as midnight UTC of the chosen day — the time of
+day is ignored in the UI. To insert at the very top of the list,
+add `?previous=` (no value) to the URL.
+
+### Bulk add three tasks under user confirmation
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+DUE='2026-05-12T00:00:00.000Z'
+for T in 'Reply to Alice' 'Review PR #404' 'Send meeting recap'; do
+  curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+    -H 'Content-Type: application/json' \
+    --data "{\"title\":$(jq -nr --arg t "$T" '$t'),\"due\":\"$DUE\"}" \
+    "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+    | jq -c '{id, title, due}'
+done
+```
+
+Always list the titles you're about to create and ask for the user's
+go-ahead before running this loop — there is no atomic batch endpoint.
+
+### Mark a task complete
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+TASK_ID='dGFza0lkRXhhbXBsZQ'
+NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data "{\"status\":\"completed\",\"completed\":\"$NOW\"}" \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
+  | jq '{id, title, status, completed}'
+```
+
+Reverse with `{"status":"needsAction","completed":null}`.
+
+### Edit a task's title / notes / due date
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+TASK_ID='dGFza0lkRXhhbXBsZQ'
+curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"title":"Draft Q2 plan (rev2)","notes":"Cover risks + asks + budget.","due":"2026-05-20T00:00:00.000Z"}' \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
+  | jq '{id, title, due, notes}'
+```
+
+### Delete a task
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+TASK_ID='dGFza0lkRXhhbXBsZQ'
+curl -sS -X DELETE -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
+  -o /dev/null -w 'HTTP %{http_code}\n'
+```
+
+`204` = success. There is no soft-delete — once gone the task is
+gone. Echo the title back before deleting.
+
+### Re-order: move a task to a position
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+TASK_ID='dGFza0lkRXhhbXBsZQ'
+PREV='dGFza0lkUHJldg'  # task id this one should appear AFTER; omit to move to top
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  --data '' \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID/move?previous=$PREV" \
+  | jq '{id, title, parent, position}'
+```
+
+Use `?parent=...` instead of `?previous=...` to nest a task under
+another task as a sub-task.
+
+### Create a brand-new task list
+
+```sh
+curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data '{"title":"Q2 follow-ups"}' \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq '{id, title}'
+```
+
 ## Common error codes
 
 | HTTP | meaning | what to tell the user |
 |---|---|---|
 | `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Google Tasks connector on the Connections page." |
-| `403 insufficientPermissions` | scope missing | "This connector is read-only — adding or completing tasks isn't possible." |
+| `403 insufficientPermissions` | write scope missing | "This action needs the Tasks read+write scope, but only `tasks.readonly` was granted. Re-install the connector with the read+write box checked." |
 | `404 notFound` | wrong list / task id | re-list with `users/@me/lists` to find the right id. |
 | `429 quotaExceeded` | quota / throttling | back off ~5s, then retry once. |