672
Al
alfred / files
alfred / skills / gws-google-assistant-cookbook / SKILL.md
4.4 KB
1--- 2name: gws-google-assistant-cookbook 3description: Use when the user wants help with Gmail, Google Drive, Calendar, or general Google Workspace tasks via the gws CLI in this repository. Covers auth checks, safe inbox inspection, Drive listing/search, message/thread retrieval, and practical command recipes. 4--- 5 6You are working in a repository where `gws` is the preferred interface for Google Workspace. 7 8## Goal 9 10Help the user manage Gmail, Drive, and Calendar through `gws` with minimal friction. Prefer executing `gws` commands and summarizing results over giving generic advice. 11 12## Before starting 13 141. Check authentication first: 15 16```bash 17gws auth status 18``` 19 202. If not authenticated or token is invalid, stop and tell the user to run: 21 22```bash 23gws auth login --services drive,gmail,calendar 24``` 25 263. Do not expose secrets or decrypted credentials. 27 - Never run `gws auth export` unless the user explicitly asks. 28 - Never print `client_secret.json`, refresh tokens, or raw authorization headers. 29 30## Working style 31 32- Use `gws` commands directly. 33- Prefer small, verifiable reads before broad operations. 34- When inspecting email, start with metadata (`list`, then `get` with metadata or snippets) before fetching full raw content. 35- When the user asks for "recent emails", default to inbox messages for `userId=me`. 36- When the user asks for Drive files, start with `files list` and a small `pageSize`. 37- Summarize findings clearly and briefly. 38 39## Gmail cookbook 40 41### Recent inbox messages 42 43```bash 44gws gmail users messages list --params '{"userId":"me","maxResults":10,"labelIds":["INBOX"]}' 45``` 46 47Then fetch metadata for selected message IDs: 48 49```bash 50gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID","format":"metadata","metadataHeaders":["From","To","Subject","Date"]}' 51``` 52 53Useful fields: 54- `payload.headers` 55- `snippet` 56- `labelIds` 57- `internalDate` 58 59### Search mail 60 61Examples: 62 63```bash 64gws gmail users messages list --params '{"userId":"me","maxResults":10,"q":"from:noreply@github.com newer_than:7d"}' 65``` 66 67```bash 68gws gmail users messages list --params '{"userId":"me","maxResults":20,"q":"is:unread in:inbox"}' 69``` 70 71### Read a thread 72 73```bash 74gws gmail users threads get --params '{"userId":"me","id":"THREAD_ID"}' 75``` 76 77### Mark messages read 78 79```bash 80gws gmail users messages modify \ 81 --params '{"userId":"me","id":"MESSAGE_ID"}' \ 82 --json '{"removeLabelIds":["UNREAD"]}' 83``` 84 85### Add a star 86 87```bash 88gws gmail users messages modify \ 89 --params '{"userId":"me","id":"MESSAGE_ID"}' \ 90 --json '{"addLabelIds":["STARRED"]}' 91``` 92 93### Trash a message 94 95```bash 96gws gmail users messages trash --params '{"userId":"me","id":"MESSAGE_ID"}' 97``` 98 99Use destructive mail actions only when the user clearly asks. 100 101## Drive cookbook 102 103### List recent files 104 105```bash 106gws drive files list --params '{"pageSize":10,"fields":"files(id,name,mimeType,modifiedTime,webViewLink)"}' 107``` 108 109### Search Drive 110 111```bash 112gws drive files list --params '{"pageSize":10,"q":"name contains \"invoice\" and trashed = false","fields":"files(id,name,mimeType,modifiedTime,webViewLink)"}' 113``` 114 115### Get file details 116 117```bash 118gws drive files get --params '{"fileId":"FILE_ID","fields":"id,name,mimeType,owners,modifiedTime,webViewLink,size"}' 119``` 120 121### Export a Google Doc 122 123```bash 124gws drive files export --params '{"fileId":"FILE_ID","mimeType":"text/plain"}' --output ./document.txt 125``` 126 127### Upload a local file 128 129```bash 130gws drive files create \ 131 --params '{"uploadType":"multipart"}' \ 132 --json '{"name":"example.txt"}' \ 133 --upload ./example.txt 134``` 135 136## Calendar cookbook 137 138### List upcoming events on primary calendar 139 140```bash 141gws calendar events list --params '{"calendarId":"primary","maxResults":10,"singleEvents":true,"orderBy":"startTime","timeMin":"2026-01-01T00:00:00Z"}' 142``` 143 144For "upcoming events", set `timeMin` to the current timestamp. 145 146## Troubleshooting 147 148### Inspect auth state 149 150```bash 151gws auth status 152``` 153 154### Re-login with required services 155 156```bash 157gws auth login --services drive,gmail,calendar 158``` 159 160### Read-only login 161 162```bash 163gws auth login --services drive,gmail,calendar --readonly 164``` 165 166## Response guidelines 167 168- Prefer executing the command and reporting the result. 169- Include the exact `gws` command when it helps the user repeat the action. 170- Do not dump large JSON unless asked; extract the fields the user cares about. 171- If an operation may modify or delete user data, confirm intent unless the user explicitly requested that exact action.