diff --git a/plugins/gmail/skills/gmail/SKILL.md b/plugins/gmail/skills/gmail/SKILL.md index 3ba2b8fb..31ed88c4 100644 --- a/plugins/gmail/skills/gmail/SKILL.md +++ b/plugins/gmail/skills/gmail/SKILL.md @@ -1,6 +1,6 @@ --- name: gmail -description: Manage Gmail inbox triage, mailbox search, thread summaries, action extraction, reply drafting, and email forwarding through connected Gmail data. Use when the user wants to inspect a mailbox or thread, search email with Gmail query syntax, summarize messages, extract decisions and follow-ups, prepare replies or forwarded messages, or organize messages with explicit confirmation before send, archive, delete, or label actions. +description: Manage Gmail inbox triage, mailbox search, thread summaries, action extraction, reply drafting, and email forwarding through connected Gmail data. Use when the user wants to inspect a mailbox or thread, search email with Gmail query syntax, summarize messages, extract decisions and follow-ups, prepare replies or forwarded messages, or organize messages when they clearly ask for send, archive, delete, or label actions. --- # Gmail @@ -41,13 +41,14 @@ For mailbox analysis requests such as triage, follow-up detection, topic summari 5. Common system labels to use in `tags` include `INBOX`, `STARRED`, `TRASH`, `DRAFT`, `SENT`, `SPAM`, `UNREAD`, and `IMPORTANT`. For All Mail, prefer Gmail query syntax such as `in:anywhere` rather than guessing a tag value. 6. Use Gmail-native `batch_read_email` when you need the body of multiple shortlisted emails, and escalate to `read_email_thread` only when the surrounding conversation changes the answer. 7. Use `search_email_ids` only when the next tool specifically needs message IDs and the richer `search_emails` response would not help you decide what to do. -8. Summarize before writing when the request is ambiguous, and keep analysis separate from actions like send, archive, trash, or label changes unless the user explicitly asked for them. +8. Summarize before writing when the request is ambiguous, and keep analysis separate from actions like send, archive, trash, or label changes unless the user explicitly asked for them. A direct command in the current request, such as "label recruiter cold emails" or "delete emails related to calendar updates," is explicit user intent once the matching messages are reasonably identified. ## Write Safety - Preserve exact recipients, subject lines, quoted facts, dates, and links from the source thread unless the user asks to change them. - When drafting a reply, call out any assumptions, missing context, or information that still needs confirmation. -- Treat send, archive, trash, label, and move operations as explicit actions that require clear user intent. +- Treat send, archive, trash, label, and move operations as explicit actions that require clear user intent in the current request. When the user directly asks for the action and the target messages are reasonably identifiable, proceed after the needed search or inspection instead of asking for another confirmation. +- Ask a concise confirmation question before acting only when the target set is ambiguous, the match quality is low, the action would send externally with inferred content or recipients, or the user asked for analysis without asking for a mailbox change. - If a thread has multiple possible recipients or parallel conversations, identify the intended thread before drafting or acting. - When supporting context such as policy docs, CRM notes, or Slack history is unavailable, do not foreground that limitation unless it materially changes the recommendation. Prefer a draft grounded in the email thread itself, and mention missing internal context only as a brief confidence note when necessary. diff --git a/plugins/gmail/skills/gmail/references/label-actions.md b/plugins/gmail/skills/gmail/references/label-actions.md index 74fea2ff..26d7fdeb 100644 --- a/plugins/gmail/skills/gmail/references/label-actions.md +++ b/plugins/gmail/skills/gmail/references/label-actions.md @@ -4,6 +4,10 @@ Read this file when the user wants to apply labels, relabel matching mail, or do ## Tool Shapes +- `archive_emails` expects: + - `message_ids: list[str]` +- `delete_emails` expects: + - `message_ids: list[str]` - `apply_labels_to_emails` expects: - `message_ids: list[str]` - `add_label_names: list[str]` @@ -15,12 +19,21 @@ Read this file when the user wants to apply labels, relabel matching mail, or do - Prefer `bulk_label_matching_emails` when the task can be expressed as a clear Gmail query and the user wants to label all matching mail. - Prefer `apply_labels_to_emails` when you already inspected results and selected a specific shortlist of message IDs. +- Prefer `archive_emails` or `delete_emails` when the user directly asks to clean up, archive, delete, remove, or trash a selected set of messages. - Prefer Gmail search refinement before labeling. Tighten the query first rather than labeling a noisy result set and cleaning it up later. +## Confirmation Boundary + +- A direct cleanup instruction in the current request is enough approval to apply labels, archive, or move messages to Trash after the matching set is reasonably identified. +- For heuristic categories such as recruiter cold emails, inspect a sample or shortlist first, then act on high-confidence matches. Ask only if the remaining matches are uncertain enough that acting would likely surprise the user. +- For broad cleanup such as calendar updates, build a narrow Gmail query, inspect enough results to verify the pattern, then use the selected message IDs or a bulk label action. Do not ask for a second confirmation just because the action changes mailbox state. +- Ask before acting when the search scope is vague, many unrelated messages appear in the result set, the request could affect another mailbox, or the user asked for recommendations rather than an action. + ## Labeling Pattern 1. Build or refine a Gmail query that matches the intended set. 2. Inspect a small sample if the classification is heuristic or ambiguous. 3. Use `bulk_label_matching_emails` for broad backfills driven by query logic. 4. Use `apply_labels_to_emails` for hand-picked message lists, and always pass label names as arrays. -5. Keep label changes separate from analysis in the response, and make it clear what was labeled and why. +5. Use `archive_emails` or `delete_emails` for hand-picked cleanup lists. +6. Keep mailbox changes separate from analysis in the response, and make it clear what changed and why.