@qvac/skills 0.1.4 → 0.1.6

package/hash.js

@@ -1,2 +1,2 @@
 // Autogenerated by scripts/build.mjs from skills/. Do not edit.
-export const SKILLS_HASH = '0a22513646401785'
+export const SKILLS_HASH = 'ba65671970b03d38'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/skills",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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,54 @@ 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"
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
 ---
 
 # Asana

package/skills/gmail/SKILL.md

@@ -6,6 +6,57 @@ tools: [http_request, 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 \"Desktop app\" 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

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 \"Desktop app\" 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 \"Desktop app\" 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 \"Desktop app\" 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 \"Desktop app\" 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,51 +8,86 @@ 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"
+              ]
+            }
           }
+        ]
       }
+    }
   }
 ---
 
 # Spotify
 
-Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential is attached automatically to every `api.spotify.com` request — **never include an `auth` block**. Never invent track/album/artist URIs — search first and copy `uri` from the JSON response.
+Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential is attached automatically to every `api.spotify.com` request — **never include an `auth` block**.
 
-```json
-{
-  "url": "https://api.spotify.com/v1/search",
-  "method": "GET",
-  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
-}
-```
+## Playing a song takes two calls. Always two.
 
-## Hard rules
+"Play X" is not answered until **both** have run:
 
-- A bare song/artist/album/playlist name is enough — search immediately, take the top match, and tell the user what you picked. Do not ask "which one?" before searching.
-- Always search before playing by name. Play carries URIs only in the JSON `body` (`"uris": ["…"]`), never as query parameters.
-- A bare `PUT /me/player/play` with no body only resumes paused playback — it never plays a requested song. For an album/artist/playlist use `{ "context_uri": "<uri>" }` instead of `uris`.
-- Do not ask about tokens or setup up front. A **401** means Spotify isn't connected (tell the user to run `/connect spotify`). A **404** from `/me/player` means no active device (tell them to open Spotify).
+1. `GET /v1/search` — find the track.
+2. `PUT /v1/me/player/play` — start it.
 
-## Recipe: play a song by name
-
-1. Search:
+Search alone plays nothing. If you have searched and not yet called play, you are not finished: make the play call now.
 
 ```json
 {
   "url": "https://api.spotify.com/v1/search",
   "method": "GET",
-  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
+  "query": { "q": "Radiohead Creep", "type": "track", "limit": 3, "market": "from_token" }
 }
 ```
 
-2. Copy `tracks.items[0].uri` into the play body:
-
 ```json
 {
   "url": "https://api.spotify.com/v1/me/player/play",
@@ -61,6 +96,20 @@ Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential
 }
 ```
 
+Take `tracks.items[0].uri` from the search response and paste it into `uris`. A 204 means it started.
+
+## Hard rules
+
+- **`q` carries every word the user named — the title and the artist.** "play Creep by Radiohead" searches `q=Radiohead Creep`, never `q=Creep`. Drop the artist and the top hit is a different band's song with the same title.
+- **Before playing, check the item you picked.** Compare its `artists[0].name` with the artist the user named. If they do not match, take the first result that does. A title match under the wrong artist is the wrong song, and the user hears it immediately.
+- **Never write a URI, a JSON block, or "I'll play it now" to the user in place of calling play.** Describing the call is not making it.
+- **Every URI you send is one you copied from a search response in this turn.** Never type a `spotify:track:` id from memory or from an earlier turn. A well-formed id that is not real stops what was playing and starts nothing.
+- **A track goes in `uris`. Only `uris`.** `context_uri` takes an album, artist or playlist URI — a track URI there plays nothing. URIs go in the JSON `body`, never in query parameters.
+- **One call per intent.** A 204 means the call landed; do not send it again. Repeating a queue or play call burns the turn and changes nothing.
+- **Name what actually played, read back from the item you used** — its `name` and `artists[0].name`. A 204 says the call was accepted, not which song it was, so never report a title you did not read out of the response.
+- A bare song/artist/album/playlist name is enough — search immediately, take the top match, and tell the user what you picked. Do not ask "which one?" before searching.
+- Do not ask about tokens or setup up front. A **401** means Spotify isn't connected (tell the user to run `/connect spotify`). A **404** from `/me/player` means no active device (tell them to open Spotify).
+
 ## Other operations
 
 All paths are under `https://api.spotify.com/v1`.
@@ -69,17 +118,20 @@ All paths are under `https://api.spotify.com/v1`.
 | --------------- | ----------------------------------------------------------------------- |
 | What's playing? | `GET /me/player/currently-playing`                                      |
 | Pause           | `PUT /me/player/pause`                                                  |
-| Resume          | `PUT /me/player/play` (no body)                                         |
+| Resume          | `PUT /me/player/play` (no body — resumes only, never starts a new song) |
 | Next track      | `POST /me/player/next`                                                  |
 | Add to queue    | `POST /me/player/queue` with `query`: `{ "uri": "spotify:track:<id>" }` |
+| Play an album/artist/playlist | `PUT /me/player/play` with `body`: `{ "context_uri": "<uri>" }` |
 | My playlists    | `GET /me/playlists`                                                     |
 | Top tracks      | `GET /me/top/tracks` with `query`: `{ "time_range": "medium_term" }`    |
 | Recently played | `GET /me/player/recently-played`                                        |
 | List devices    | `GET /me/player/devices`                                                |
 
+Queueing is the same two calls as playing: search for the track, then `POST /me/player/queue` with the `uri` you just read. Queueing does not start playback.
+
 ## Notes
 
-- Keep responses small — they truncate past 8KB, and raw JSON burns tokens on small models. Keep `limit` at 5. On playlist/track endpoints request only what you need with `fields` (e.g. `query`: `{ "fields": "items(track(name,artists(name),uri))" }`). Read just the top item unless the user asked for a list.
+- Keep responses small — they truncate past 8KB, and raw JSON burns tokens on small models. Keep `limit` at 3 and **always pass `market`**: a search without it spends most of the budget on `available_markets`, and the results behind the first one are cut off before you can read them. `/search` has no `fields` param, so `market` is the only lever there. On playlist/track endpoints request only what you need with `fields` (e.g. `query`: `{ "fields": "items(track(name,artists(name),uri))" }`). Read just the top item unless the user asked for a list.
 - Present results as a short numbered list — track, artist, album, duration — and devices as `1. Name (active/idle)`. Never dump raw JSON to the user.
 - Playback commands return **204 No Content** on success (empty body). A **204** from currently-playing means nothing is playing.
 - **403** with `PREMIUM_REQUIRED` → user needs Spotify Premium. Other **403**s are usually app-scope/Development Mode limits — report and stop.