From e8b1a08ea58cd6032547b9ed8aa3a5bc433fcead Mon Sep 17 00:00:00 2001 From: Omri Ariav Date: Fri, 6 Feb 2026 06:15:38 +0200 Subject: [PATCH] docs(gmail): Add search tips and common gotchas to SKILL.md Learned from real usage session where email search was inefficient: - Document that `to:` only matches To header, not CC - Warn that `list` message_id is the latest in thread (may not be user's) - Add strategy for finding specific person's emails using thread view - Bump version to 1.1.0 Co-Authored-By: Claude Opus 4.6 --- skills/gmail/SKILL.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/skills/gmail/SKILL.md b/skills/gmail/SKILL.md index 3db44d0..b704f20 100644 --- a/skills/gmail/SKILL.md +++ b/skills/gmail/SKILL.md @@ -1,6 +1,6 @@ --- name: gws-gmail -version: 1.0.0 +version: 1.1.0 description: "Google Gmail CLI operations via gws. Use when users need to list emails, read messages, send email, manage labels, archive, or trash messages. Triggers: gmail, email, inbox, send email, mail, labels, archive, trash." metadata: short-description: Google Gmail CLI operations @@ -165,6 +165,9 @@ gws gmail list --format text # Human-readable text ## Tips for AI Agents +- `list` returns the latest `message_id` per thread — reading it may show someone else's reply. To find a specific person's message, use `gws gmail thread ` and scan all messages +- When searching for emails involving a person, use the bare email as a search term (`from:me user@domain.com`) rather than `to:user@domain.com` — the `to:` operator only matches the To header, not CC recipients +- If using employee lookup tools to get someone's email, use the exact returned address — don't guess the format (e.g., `lior.g@` not `lior.golan@`) - Always use `--format json` (the default) for programmatic parsing - Use `gws gmail list` to get IDs: `message_id` for `read`/`label`/`archive`/`trash`, `thread_id` for `thread` - Use `gws gmail thread ` to view full conversations with all messages