xonecas.io
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.