@vellumai/assistant 0.4.43 → 0.4.45

package/src/config/bundled-skills/messaging/SKILL.md

@@ -2,11 +2,18 @@
 name: messaging
 description: Read, search, send, and manage messages across Slack, Gmail, Telegram, and other platforms
 compatibility: "Designed for Vellum personal assistants"
-metadata: {"emoji":"💬","vellum":{"display-name":"Messaging","user-invocable":true}}
+metadata:
+  emoji: "\U0001F4AC"
+  vellum:
+    display-name: "Messaging"
+    user-invocable: true
+    feature-flag: "messaging"
 ---
 
 You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
 
+For Gmail management (archive, label, triage, declutter), load the **gmail** skill. For email sequences, load the **sequences** skill.
+
 ## Email Routing Priority
 
 When the user mentions "email" — sending, reading, checking, decluttering, drafting, or anything else — **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
@@ -107,8 +114,7 @@ When a messaging tool fails with a token or authorization error:
 - **List Conversations**: Show channels, inboxes, DMs with unread counts
 - **Read Messages**: Read message history from a conversation
 - **Search**: Search messages with platform-appropriate query syntax
-- **Send**: Send a message (high risk — requires user approval)
-- **Reply**: Reply in a thread (medium risk)
+- **Send / Reply**: Send a message or reply in a thread (via `thread_id`). High risk — requires user approval.
 - **Mark Read**: Mark conversation as read
 
 ### Telegram
@@ -138,45 +144,6 @@ Telegram is supported as a messaging provider with limited capabilities compared
 
 When sending a Slack message, retain the `ts` (message timestamp) from the send response — it is needed to edit or delete that message later. Only messages sent by the assistant's bot can be edited or deleted.
 
-### Gmail-specific
-
-- **Archive**: Remove message from inbox
-- **Label**: Add/remove labels
-- **Trash**: Move to trash
-- **Unsubscribe**: Unsubscribe via List-Unsubscribe header
-- **Draft (native)**: Create a draft in Gmail's Drafts folder
-
-### Attachments (Gmail)
-
-- **List Attachments**: `gmail_list_attachments` — list all attachments on a message with filename, MIME type, size, and attachment ID
-- **Download Attachment**: `gmail_download_attachment` — download an attachment to the working directory by message ID + attachment ID
-- **Send with Attachments**: `gmail_send_with_attachments` — send an email with file attachments (reads files from disk, builds multipart MIME)
-
-Workflow: use `gmail_list_attachments` to discover attachments, then `gmail_download_attachment` to save them locally.
-
-### Forward & Thread Operations (Gmail)
-
-- **Forward**: `gmail_forward` — forward a message to another recipient, preserving all attachments. Optionally prepend your own text
-- **Summarize Thread**: `gmail_summarize_thread` — LLM-powered thread summary with participants, decisions, open questions, and sentiment
-- **Follow-up Tracking**: `gmail_follow_up` — track/untrack messages for follow-up using a dedicated "Follow-up" label, or list all tracked messages
-
-### Smart Triage (Gmail)
-
-- **Triage**: `gmail_triage` — LLM-powered inbox classification of unread emails into categories: `needs_reply`, `fyi_only`, `can_archive`, `urgent`, `newsletter`, `promotional`
-  - Returns grouped report with reasoning and suggested actions per email
-  - Set `auto_apply: true` to auto-archive `can_archive` emails and label `needs_reply` as "Follow-up"
-  - Custom query support (default: `is:unread in:inbox`)
-
-### Inbox Automation (Gmail)
-
-- **Filters**: `gmail_filters` — list, create, or delete Gmail filters. Filter criteria include from, to, subject, query, has_attachment. Actions include adding/removing labels and forwarding
-- **Vacation Responder**: `gmail_vacation` — get, enable, or disable the vacation auto-responder with custom message, date range, and domain/contact restrictions
-
-### Google Contacts
-
-- **Contacts**: `google_contacts` — list or search Google Contacts by name or email. Returns name, email, phone, and organization
-  - Requires the `contacts.readonly` scope — users may need to re-authorize Gmail to grant this additional permission
-
 ## Slack Search Syntax
 
 When searching Slack, the query is passed directly to Slack's search API:
@@ -191,52 +158,6 @@ When searching Slack, the query is passed directly to Slack's search API:
 | `has:reaction` | `has:reaction`      | Messages with reactions        |
 | `has:star`     | `has:star`          | Starred messages               |
 
-## Gmail Search Syntax
-
-When searching Gmail, the query uses Gmail's search operators:
-
-| Operator         | Example                  | What it finds                       |
-| ---------------- | ------------------------ | ----------------------------------- |
-| `from:`          | `from:alice@example.com` | Messages from a specific sender     |
-| `to:`            | `to:bob@example.com`     | Messages sent to a recipient        |
-| `subject:`       | `subject:meeting`        | Messages with a word in the subject |
-| `newer_than:`    | `newer_than:7d`          | Messages from the last 7 days       |
-| `older_than:`    | `older_than:30d`         | Messages older than 30 days         |
-| `is:unread`      | `is:unread`              | Unread messages                     |
-| `has:attachment` | `has:attachment`         | Messages with attachments           |
-| `label:`         | `label:work`             | Messages with a specific label      |
-
-## Drafting vs Sending (Gmail)
-
-Gmail uses a **draft-first workflow**. All compose and reply tools create Gmail drafts automatically:
-
-- `messaging_send` (Gmail) → creates a draft in Gmail Drafts
-- `messaging_reply` (Gmail) → creates a threaded draft with reply-all recipients
-- `gmail_draft` → creates a draft
-- `gmail_send_with_attachments` → creates a draft with attachments
-- `gmail_forward` → creates a forward draft
-
-**To actually send**: Use `gmail_send_draft` with the draft ID after the user has reviewed it. Only call `gmail_send_draft` when the user explicitly says "send it" or equivalent.
-
-**Reply-all**: `messaging_reply` for Gmail automatically builds the reply-all recipient list from the thread. You do not need to manually look up recipients.
-
-Non-Gmail platforms (Slack, Telegram) send directly via `messaging_send` / `messaging_reply`.
-
-## Email Threading (Gmail)
-
-When replying to or continuing an email thread:
-
-- Use `messaging_reply` with the thread's `thread_id` — it automatically handles threading, reply-all recipients, and subject lines.
-- The `in_reply_to` field on `gmail_draft` requires the **RFC 822 Message-ID header** (looks like `<CABx...@mail.gmail.com>`), NOT the Gmail message ID (which looks like `18e4a5b2c3d4e5f6`). Get it by reading the thread messages and extracting the `Message-ID` header.
-
-## Date Verification
-
-Before composing any email that references a date or time:
-
-1. Check the `<temporal_context>` block in the current turn for today's date and upcoming dates
-2. Verify that "tomorrow" means the day after today's date, "next week" means the upcoming Monday–Friday, etc.
-3. If the email references a date from another message, cross-check it against the temporal context to ensure it's in the future
-
 ## Notifications vs Messages
 
 - `send_notification` is provided by the **notifications** skill (always active) -- use it when the user asks for an alert/notification (for example "send this as a desktop notification").
@@ -260,63 +181,26 @@ Medium and high risk tools require a confidence score between 0 and 1:
 - **0.5-0.6**: Reasonable inference but some ambiguity
 - **Below 0.5**: Ask the user to confirm before proceeding
 
-## Activity Analysis
-
-Use `messaging_analyze_activity` to classify channels or conversations by activity level (high, medium, low, dead). Useful for decluttering — suggest leaving dead channels or archiving old emails.
-
 ## Email Decluttering
 
-When a user asks to declutter, clean up, or organize their email — start scanning immediately. Don't ask what kind of cleanup they want or request permission to read their inbox. Go straight to scanning — but once results are ready, always show them via `ui_show` and let the user choose actions before archiving or unsubscribing.
+When a user asks to declutter, clean up, or organize their email:
 
-**CRITICAL**: Never call `gmail_batch_archive`, `gmail_archive_by_query`, `gmail_unsubscribe`, or `messaging_archive_by_sender` unless the user has clicked an action button on the table for that specific batch. Each batch of results requires its own explicit user confirmation via the table UI. If the user says "keep going" or "keep decluttering," that means scan and present a new table — NOT auto-archive. Previous batch approvals do not carry forward, but **deselections DO carry forward**: when the user deselects senders from a cleanup table, the system records those deselections as user preferences. Before building the next cleanup table, check `<dynamic-user-profile>` for previously deselected senders and exclude them from future cleanup tables — the user already indicated they want to keep those.
-
-### Provider Selection
-
-- **Gmail connected**: Use the Gmail-specific tools (`gmail_sender_digest`, `gmail_batch_archive`, `gmail_unsubscribe`, `gmail_filters`) — they have richer features like unsubscribe support and filter creation.
+- **Gmail connected**: Load the **gmail** skill, which has the full decluttering workflow with `gmail_sender_digest`, `gmail_archive`, `gmail_unsubscribe`, and `gmail_filters`.
 - **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) — they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
 - **Nothing connected**: Ask which email provider they use. If it's Gmail, go straight into the Gmail connection flow. For other providers, let the user know only Gmail is supported right now and offer to set up Gmail instead. Don't present a menu of options or explain what OAuth is.
 
-### Workflow
+### Non-Gmail Decluttering Workflow
 
-1. **Scan**: Call `gmail_sender_digest` (or `messaging_sender_digest` for non-Gmail). Default query targets promotions from the last 90 days.
+1. **Scan**: Call `messaging_sender_digest`. Default query targets promotions from the last 90 days.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
-   - **Gmail columns (exactly 3)**: Sender, Emails Found, Unsub?
-     - **Unsub? cell values**: Use rich cell format: `{ "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" }` when `has_unsubscribe` is true, `{ "text": "No", "icon": "minus.circle", "iconColor": "muted" }` when false.
-   - **Non-Gmail columns (exactly 2)**: Sender, Emails Found (omit the Unsub? column — unsubscribe is not available)
+   - **Columns (exactly 2)**: Sender, Emails Found
    - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
-   - **Caption**: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) for Gmail tables only, the Unsub? column legend: "Unsub? — \"Yes\" means these emails contain an unsubscribe link, so I can opt you out automatically. \"No\" means no unsubscribe link was found — these will be archived but you may continue receiving them."
-   - **Gmail action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
-   - **Non-Gmail action button (exactly 1)**: "Archive Selected" (primary). Do not offer an unsubscribe button — it is Gmail-specific. **NEVER offer Delete, Trash, or any destructive action.**
-3. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button:
-   - **Dismiss the table immediately** with `ui_dismiss` — it collapses to a completion chip
-   - **Show a `task_progress` card** with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step from `in_progress` → `completed` as each phase finishes.
-   - When all senders are processed, set the progress card's `status: "completed"`.
-4. **Act on selection** — batch, don't loop:
-   - **Archive all at once**: Call `gmail_batch_archive` (or `messaging_archive_by_sender` for non-Gmail) **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the Gmail API calls internally — never loop sender-by-sender.
-   - **Unsubscribe in bulk**: If Gmail and the action is "Archive & Unsubscribe", call `gmail_unsubscribe` for each sender that has `has_unsubscribe: true` — but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
-5. **Accurate summary**: The scan counts are exact — the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders." For Gmail, append: "Unsubscribed from [unsub_count]."
-6. **Ongoing protection offer (Gmail only)**: After reporting results, offer auto-archive filters:
-   - "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"
-   - If yes, call `gmail_filters` with `action: "create"` for each sender with `from` set to the sender's email and `remove_label_ids: ["INBOX"]`.
-   - Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?" If yes, use `schedule_create` to set up a monthly declutter check.
-
-### Edge Cases
-
-- **Zero results**: Tell the user "No newsletter emails found" and suggest broadening the query (e.g. removing the category filter or extending the date range)
-- **Unsubscribe failures**: Report per-sender success/failure; the existing `gmail_unsubscribe` tool handles edge cases
-- **Truncation handling**: The scan covers up to 5,000 messages by default (cap 10,000). If `truncated` is true, the top senders are still captured — don't offer to scan more. Tell the user: "Scanned [N] messages — here are your top senders."
-- **Time budget exceeded**: If the scan returns `time_budget_exceeded: true`, present whatever results were collected. Do not retry or continue — the partial results are useful as-is.
-
-### Scan ID
-
-Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`, `messaging_sender_digest`) return a `scan_id` that references message IDs stored server-side. This keeps thousands of message IDs out of the conversation context.
-
-- Pass `scan_id` + `sender_ids` to `gmail_batch_archive` instead of `message_ids`
-- Scan results expire after **30 minutes** — if archiving fails with an expiration error, re-run the scan
-- Raw `message_ids` still work as a fallback for non-scan workflows
-
-## Batch Operations
-
-- Gmail batch tools (`gmail_batch_archive`, `gmail_batch_label`) support `scan_id` + `sender_ids` (preferred) or raw `message_ids`.
-- First scan to get a `scan_id`, then apply batch actions using it.
-- Always confirm with the user before batch operations on large numbers of messages.
+   - **Caption**: Data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep."
+   - **Action button (exactly 1)**: "Archive Selected" (primary). **NEVER offer Delete, Trash, or any destructive action.**
+3. **Wait for user action**: Stop and wait. Do NOT proceed until the user clicks the action button.
+4. **Act on selection**: For each selected sender, call `messaging_archive_by_sender` with a `query` built from the sender's email address (e.g., `from:newsletter@example.com category:promotions newer_than:90d`). Use the `search_query` field from the sender digest results if available, or construct a `from:<email>` query matching the original scan's scope.
+5. **Accurate summary**: Format: "Cleaned up [total_archived] emails from [sender_count] senders."
+
+### Query-Based Archiving
+
+Unlike Gmail's `gmail_archive` (which supports `scan_id` + `sender_ids`), `messaging_archive_by_sender` is query-based. Build `from:<email>` queries from the sender digest results to target specific senders. Include the same date/category filters used in the original scan to keep the scope consistent.