@qvac/skills 0.1.5 → 0.1.7

package/hash.js

@@ -1,2 +1,2 @@
 // Autogenerated by scripts/build.mjs from skills/. Do not edit.
-export const SKILLS_HASH = '8357531791b7cdb8'
+export const SKILLS_HASH = '8ce2fae4970bf369'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/skills",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Skills for the QV.AC app — the SKILL.md tree plus a content-addressed bundle of it.",
   "type": "module",
   "main": "index.js",

package/skills/apple-notes/SKILL.md

@@ -5,28 +5,28 @@ tools: [exec(osascript)]
 platform: [darwin]
 metadata:
   {
-    'openclaw':
-      {
-        'requires': { 'bins': ['osascript'] },
-        'setup':
+    "openclaw": {
+      "requires": {
+        "bins": [
+          "osascript"
+        ]
+      },
+      "setup": {
+        "summary": "Apple Notes works through macOS automation (osascript), which ships with macOS — nothing to install. The first command triggers a one-time permission prompt to let this app control Notes.",
+        "routes": [
           {
-            'summary': 'Apple Notes works through macOS automation (osascript), which ships with macOS — nothing to install. The first command triggers a one-time permission prompt to let this app control Notes.',
-            'routes':
-              [
-                {
-                  'kind': 'instructions',
-                  'label': 'Allow Notes automation',
-                  'description': "macOS asks once for permission to control Notes. Commands fail until it's granted.",
-                  'steps':
-                    [
-                      'Use the skill once — macOS shows a permission prompt to allow control of Notes.',
-                      'Click Allow.',
-                      'If it was denied, enable it under System Settings → Privacy & Security → Automation.'
-                    ]
-                }
-              ]
+            "kind": "instructions",
+            "label": "Allow Notes automation",
+            "description": "macOS asks once for permission to control Notes. Commands fail until it's granted.",
+            "steps": [
+              "Use the skill once — macOS shows a permission prompt to allow control of Notes.",
+              "Click Allow.",
+              "If it was denied, enable it under System Settings → Privacy & Security → Automation."
+            ]
           }
+        ]
       }
+    }
   }
 ---
 

package/skills/asana/SKILL.md

@@ -6,6 +6,69 @@ platform: [darwin, linux, win32]
 credentials: [asana_mcp_access_token]
 allow_list: [https://mcp.asana.com/v2/mcp]
 mcp_reads: [get_task, get_tasks, get_my_tasks, get_projects, search_tasks, search_objects]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Asana",
+            "provider": "asana",
+            "credentialKey": "asana_mcp_access_token",
+            "description": "Tasks, projects, and comments",
+            "helpUrl": "https://app.asana.com/0/my-apps",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to the Asana workspace you allow."
+            ],
+            "configSteps": [
+              "[Open the Asana developer console](https://app.asana.com/0/my-apps) and create an MCP app",
+              "In OAuth settings, add the exact redirect URI shown below",
+              "In \"Manage distribution\", allow the workspace you want this connection to access"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "asana_oauth",
+              "authUrl": "https://app.asana.com/-/oauth_authorize",
+              "tokenUrl": "https://app.asana.com/-/oauth_token",
+              "tokenAuth": "secret-in-body",
+              "port": 18981,
+              "scopes": [],
+              "extraAuthParams": {
+                "resource": "https://mcp.asana.com/v2"
+              },
+              "verify": {
+                "url": "https://mcp.asana.com/v2/mcp",
+                "method": "POST",
+                "body": {
+                  "jsonrpc": "2.0",
+                  "id": 1,
+                  "method": "initialize",
+                  "params": {
+                    "protocolVersion": "2025-03-26",
+                    "capabilities": {},
+                    "clientInfo": { "name": "qvac", "version": "1.0.0" }
+                  }
+                },
+                "reject": [{ "status": [401, 403], "error": "asana_not_mcp_app" }]
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Asana

package/skills/gmail/SKILL.md

@@ -2,15 +2,66 @@
 name: gmail
 description: Read, search, send, and manage Gmail messages and labels via the Gmail REST API.
 aliases: [inbox, email+send, email+draft, email+reply, email+forward]
-tools: [http_request, gmail_send, gmail_draft]
+tools: [http_request, gmail_get, gmail_send, gmail_draft]
 platform: [darwin, linux, win32]
 credentials: [gmail_access_token]
 allow_list: [https://gmail.googleapis.com/gmail/v1/users/me/]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Gmail",
+            "provider": "google",
+            "credentialKey": "gmail_access_token",
+            "description": "Read, search, send, and manage Gmail messages and labels",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to your Gmail only.",
+              "Each Google skill is connected separately, with its own app and its own approval."
+            ],
+            "configSteps": [
+              "[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com) to enable the Gmail API",
+              "[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose \"Web application\" as the type",
+              "[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "gmail_oauth",
+              "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+              "tokenUrl": "https://oauth2.googleapis.com/token",
+              "tokenAuth": "secret-in-body",
+              "port": 18978,
+              "scopes": [
+                "https://www.googleapis.com/auth/gmail.modify"
+              ],
+              "extraAuthParams": {
+                "access_type": "offline",
+                "prompt": "consent"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Gmail
 
-Use `gmail_send` to send, `gmail_draft` to draft, and `http_request` for everything else (list, search, get, labels, trash). The Gmail credential is attached automatically to every `gmail.googleapis.com` request — **never include an `auth` block**.
+Read with `gmail_get`, send with `gmail_send`, draft with `gmail_draft`. `http_request` is only for list/search, labels and trash. The Gmail credential is attached automatically to every `gmail.googleapis.com` request — **never include an `auth` block**. Never run code.
 
 ## Prerequisites
 
@@ -25,11 +76,13 @@ set the `gmail_access_token` credential.
 
 The host is `gmail.googleapis.com` — not `www.googleapis.com`. Send is at `/messages/send`, never `/send`.
 
-## Common Operations
+## Read messages
 
-### List or search messages
+1. List with `http_request`. Use `q` for Gmail search (`from:`, `subject:`, `is:unread`, `newer_than:7d`, `has:attachment`, `label:work`). Keep `maxResults` ≤ 10. The result is ids only.
+2. Call `gmail_get` with each `id`. It returns `headers` (From, To, Subject, Date), `snippet` and, with `format: "full"`, `text`.
+3. Answer from those fields. Never run code.
 
-`messages.list` returns `{id, threadId}` pairs only — no subjects, no snippets. To summarize you need a follow-up `messages.get` per id. Use `q` for Gmail search syntax (`from:`, `subject:`, `is:unread`, `newer_than:7d`, `has:attachment`, `label:work`). Keep `maxResults` ≤ 10.
+`http_request` to list:
 
 ```json
 {
@@ -39,32 +92,15 @@ The host is `gmail.googleapis.com` — not `www.googleapis.com`. Send is at `/me
 }
 ```
 
-### Get a message (metadata)
-
-For lists and summaries always use `format=metadata` — it skips the body and is far cheaper than `full`.
+`gmail_get` for each id:
 
 ```json
-{
-  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}",
-  "method": "GET",
-  "query": {
-    "format": "metadata",
-    "metadataHeaders": "Subject,From,To,Date,Message-ID,References"
-  }
-}
+{ "id": "1a0c420faf8b68fe" }
 ```
 
-### Get a message (full body)
+Use `format: "full"` only when the user asks what a message says.
 
-Only when the user needs the content. The body is base64url-encoded in `payload.parts[].body.data` (or `payload.body.data`); decode it before presenting. Prefer the `text/plain` part over `text/html`.
-
-```json
-{
-  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}",
-  "method": "GET",
-  "query": { "format": "full" }
-}
-```
+## Common Operations
 
 ### Send a message
 
@@ -90,7 +126,7 @@ Use `gmail_draft` with the same envelope as `gmail_send`.
 
 A reply is `gmail_send` with the original's `threadId`, `inReplyTo`, and `references`. Without these Gmail starts a new thread.
 
-1. Get the original with `format=metadata` and headers `Message-ID,References,Subject,From,Reply-To`; capture its `threadId`.
+1. `gmail_get` the original; capture its `threadId` and its `Message-ID` and `References` headers.
 2. Send with `to` <- original From (or Reply-To), `subject` <- `Re: ` + original (don't double-prefix), `inReplyTo` <- original Message-ID, `references` <- original References then that Message-ID. Keep angle brackets.
 
 ```json
@@ -127,15 +163,15 @@ System labels: `INBOX`, `UNREAD`, `STARRED`, `IMPORTANT`, `SPAM`, `TRASH`. Mark
 
 ## Output Policy
 
-- Lists: up to 5 entries with subject, sender, and a human-readable date. Fetch full bodies only when asked.
-- Decode base64 message bodies before presenting; never include raw base64 blobs.
+- Lists: up to 5 entries with subject, sender, and a human-readable date. Fetch `text` only when asked.
 - Modify/trash: state the user-facing effect ("marked 3 messages as read"), not the label diff.
 - Confirm destructive or outgoing actions (send, reply, trash) with the user first.
 
 ## Common Mistakes
 
 - Using `www.googleapis.com` for Gmail, or building send/draft/reply through `http_request` instead of `gmail_send`/`gmail_draft`.
-- Treating `messages.list` results as if they had subjects — they need a follow-up `messages.get`.
+- Treating `messages.list` results as if they had subjects — call `gmail_get` for each id.
+- Reading a message through `http_request` or code instead of `gmail_get`.
 - Replying without `threadId` + `inReplyTo`/`references` — Gmail starts a new thread.
 - Sending a placeholder (`<RECIPIENT_EMAIL>`, `recipient@example.com`) — the runtime refuses these.
 - Inventing an address. The runtime refuses any recipient absent from the conversation and from earlier tool results; search Gmail or ask the user.

package/skills/gmail/operations.json

@@ -66,6 +66,29 @@
         "url": "https://gmail.googleapis.com/gmail/v1/users/me/drafts",
         "builder": "gmail-draft"
       }
+    },
+    {
+      "tool": "gmail_get",
+      "description": "Read one Gmail message by id: sender, recipients, subject, date, snippet and, with format \"full\", the message text. Call it for each id that messages.list returned. Never read a message with http_request or code.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "description": "Message id from messages.list" },
+          "format": {
+            "type": "string",
+            "enum": ["metadata", "full"],
+            "description": "metadata (default) for lists and summaries; full only when the user needs the message text"
+          }
+        },
+        "required": ["id"]
+      },
+      "request": {
+        "method": "GET",
+        "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}",
+        "query": { "metadataHeaders": "Subject,From,To,Date,Message-ID,References" },
+        "builder": "gmail-get"
+      },
+      "response": { "decode": "gmail-message" }
     }
   ]
 }

package/skills/google-calendar/SKILL.md

@@ -6,6 +6,57 @@ 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/]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Google Calendar",
+            "provider": "google",
+            "credentialKey": "google_calendar_access_token",
+            "description": "List, create, update, and delete Google Calendar events",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to your calendars only.",
+              "Each Google skill is connected separately, with its own app and its own approval."
+            ],
+            "configSteps": [
+              "[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com) to enable the Google Calendar API",
+              "[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose \"Web application\" as the type",
+              "[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "google_calendar_oauth",
+              "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+              "tokenUrl": "https://oauth2.googleapis.com/token",
+              "tokenAuth": "secret-in-body",
+              "port": 18978,
+              "scopes": [
+                "https://www.googleapis.com/auth/calendar"
+              ],
+              "extraAuthParams": {
+                "access_type": "offline",
+                "prompt": "consent"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Google Calendar

package/skills/google-docs/SKILL.md

@@ -5,6 +5,58 @@ 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]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Google Docs",
+            "provider": "google",
+            "credentialKey": "google_docs_access_token",
+            "description": "Create, read, and edit Google Docs documents",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to your documents and Drive files only.",
+              "Each Google skill is connected separately, with its own app and its own approval."
+            ],
+            "configSteps": [
+              "[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=docs.googleapis.com,drive.googleapis.com) to enable the Google Docs API",
+              "[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose \"Web application\" as the type",
+              "[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "google_docs_oauth",
+              "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+              "tokenUrl": "https://oauth2.googleapis.com/token",
+              "tokenAuth": "secret-in-body",
+              "port": 18978,
+              "scopes": [
+                "https://www.googleapis.com/auth/documents",
+                "https://www.googleapis.com/auth/drive"
+              ],
+              "extraAuthParams": {
+                "access_type": "offline",
+                "prompt": "consent"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Google Docs

package/skills/google-drive/SKILL.md

@@ -5,6 +5,57 @@ 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/]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Google Drive",
+            "provider": "google",
+            "credentialKey": "google_drive_access_token",
+            "description": "Search, list, and manage Google Drive files and folders",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to your Drive files only.",
+              "Each Google skill is connected separately, with its own app and its own approval."
+            ],
+            "configSteps": [
+              "[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com) to enable the Google Drive API",
+              "[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose \"Web application\" as the type",
+              "[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "google_drive_oauth",
+              "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+              "tokenUrl": "https://oauth2.googleapis.com/token",
+              "tokenAuth": "secret-in-body",
+              "port": 18978,
+              "scopes": [
+                "https://www.googleapis.com/auth/drive"
+              ],
+              "extraAuthParams": {
+                "access_type": "offline",
+                "prompt": "consent"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Google Drive

package/skills/google-sheets/SKILL.md

@@ -6,6 +6,58 @@ platform: [darwin, linux, win32]
 credentials: [google_sheets_access_token]
 allow_list:
   [https://sheets.googleapis.com/v4/spreadsheets, https://www.googleapis.com/drive/v3/files]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Google Sheets",
+            "provider": "google",
+            "credentialKey": "google_sheets_access_token",
+            "description": "Create, read, and update Google Sheets spreadsheets",
+            "steps": [
+              "Click Connect and approve access in the browser. Approving grants access to your spreadsheets and Drive files only.",
+              "Each Google skill is connected separately, with its own app and its own approval."
+            ],
+            "configSteps": [
+              "[Open Google Cloud Console](https://console.cloud.google.com/flows/enableapi?apiid=sheets.googleapis.com,drive.googleapis.com) to enable the Google Sheets API",
+              "[Open OAuth clients](https://console.cloud.google.com/auth/clients) to create an OAuth client — choose \"Web application\" as the type",
+              "[Open OAuth audience](https://console.cloud.google.com/auth/audience) and add your Google account as a test user"
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "OAuth client ID from your app"
+              },
+              {
+                "key": "clientSecret",
+                "label": "Client Secret",
+                "secret": true
+              }
+            ],
+            "oauth": {
+              "stateKey": "google_sheets_oauth",
+              "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
+              "tokenUrl": "https://oauth2.googleapis.com/token",
+              "tokenAuth": "secret-in-body",
+              "port": 18978,
+              "scopes": [
+                "https://www.googleapis.com/auth/spreadsheets",
+                "https://www.googleapis.com/auth/drive"
+              ],
+              "extraAuthParams": {
+                "access_type": "offline",
+                "prompt": "consent"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Google Sheets

package/skills/notion/SKILL.md

@@ -15,6 +15,35 @@ mcp_reads:
     notion-get-async-task,
     notion-query-data-sources
   ]
+metadata:
+  {
+    "openclaw": {
+      "setup": {
+        "routes": [
+          {
+            "kind": "oauth",
+            "label": "Notion",
+            "provider": "notion",
+            "credentialKey": "notion_mcp_access_token",
+            "description": "Pages, databases, and blocks",
+            "steps": [
+              "Click Connect and approve access in the browser — Workbench uses Notion's hosted MCP OAuth, so no app credentials are needed."
+            ],
+            "oauth": {
+              "stateKey": "notion_oauth",
+              "authUrl": "https://mcp.notion.com/authorize",
+              "tokenUrl": "https://mcp.notion.com/token",
+              "tokenAuth": "pkce-only",
+              "port": 18982,
+              "registrationEndpoint": "https://mcp.notion.com/register",
+              "sharedIosSession": true,
+              "scopes": []
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Notion

package/skills/spotify/SKILL.md

@@ -8,15 +8,62 @@ credentials: [spotify_access_token]
 allow_list: [https://api.spotify.com/v1/]
 metadata:
   {
-    "openclaw":
-      {
-        "requires":
+    "openclaw": {
+      "requires": {
+        "credentials": [
+          "spotify_access_token"
+        ],
+        "credentialChecks": {
+          "spotify_access_token": {
+            "url": "https://api.spotify.com/v1/me"
+          }
+        }
+      },
+      "setup": {
+        "routes": [
           {
-            "credentials": ["spotify_access_token"],
-            "credentialChecks":
-              { "spotify_access_token": { "url": "https://api.spotify.com/v1/me" } }
+            "kind": "oauth",
+            "label": "Spotify",
+            "provider": "spotify",
+            "credentialKey": "spotify_access_token",
+            "description": "Search, library, and playback control — playback requires Spotify Premium",
+            "helpUrl": "https://developer.spotify.com/dashboard",
+            "steps": [
+              "Search and library browsing work with any Spotify account; controlling playback (play, pause, skip) requires Spotify Premium and an open Spotify app on a device.",
+              "Create your own app at https://developer.spotify.com/dashboard (Spotify requires the app owner to hold a Premium subscription).",
+              "In the app settings, add these exact Redirect URIs: http://127.0.0.1:18974/callback (desktop) and, for mobile, the Redirect URI shown in this connect form (the scheme varies per build, e.g. qvac://oauth-callback or qvac-dev://oauth-callback).",
+              "Paste the Client ID above and click Connect, then approve access in the browser. No Client Secret is needed — Workbench uses PKCE."
+            ],
+            "fields": [
+              {
+                "key": "clientId",
+                "label": "Client ID",
+                "placeholder": "From your app at developer.spotify.com"
+              }
+            ],
+            "oauth": {
+              "stateKey": "spotify_oauth",
+              "authUrl": "https://accounts.spotify.com/authorize",
+              "tokenUrl": "https://accounts.spotify.com/api/token",
+              "tokenAuth": "pkce-only",
+              "port": 18974,
+              "sharedIosSession": true,
+              "scopes": [
+                "user-read-private",
+                "user-read-playback-state",
+                "user-modify-playback-state",
+                "user-read-currently-playing",
+                "playlist-read-private",
+                "playlist-read-collaborative",
+                "user-library-read",
+                "user-top-read",
+                "user-read-recently-played"
+              ]
+            }
           }
+        ]
       }
+    }
   }
 ---