# Google > Manage Gmail and Google Calendar with capability-backed auth and operations. Use when asked to check inbox, summarize emails, give a day at a glance, send an email, review calendar events, or schedule meetings. - Skill: `dcramer/google` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add dcramer/google` - Raw SKILL.md: https://api.skillmd.com/api/skills/dcramer/google/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: dcramer (https://skillmd.com/u/dcramer) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dcramer/google --- Manage Gmail and Google Calendar through host-managed capabilities. Use progressive disclosure: - Read `references/gmail-workflows.md` when handling summaries, inbox triage, day-at-a-glance planning, or Gmail query choices. - Read `references/auth-and-failures.md` when auth is incomplete/expired or capability commands fail. - Read `references/output-templates.md` when producing summary/day-plan output sections. ## Security Contract - Use `ash-sb capability` for every Gmail/Calendar operation. - Never read or request raw OAuth access tokens, refresh tokens, or client secrets. - Do not fabricate capability results. Only report data returned by commands. ## Workflow On every invocation, follow these steps in order: ### 1. Check capability status ```bash ash-sb capability list ``` - If a needed capability is missing, tell the user to enable `[skills.google]` and stop. - If a needed capability is not authenticated, run auth (step 2). - If already authenticated, continue to operations (step 3). ### 2. Authenticate (when needed) For each unauthenticated capability (`gog.email`, `gog.calendar`): ```bash ash-sb capability auth begin -c gog.email --account work ``` Parse the command output and extract auth fields before responding. If `auth_url` is missing from output, report the command failure and stop. Then: - If flow type is `device_code`: show URL + user code, then poll. - If flow type is `authorization_code`: show URL and ask user for callback URL or code, then complete. When presenting auth instructions, always include: - The exact `flow_id` returned by `auth begin`. - The exact `auth_url` returned by `auth begin` (never paraphrase or omit it). - The exact `user_code` when flow type is `device_code`. - A single clear instruction: complete consent, then paste callback URL or code. Use one of these response templates exactly: Authorization code flow: `To continue, open this Google auth URL: \nFlow ID: \nAfter approval, paste the full callback URL (or just the code) here.` Device code flow: `To continue, open: \nFlow ID: \nEnter this code: \nAfter approval, tell me when done and I will continue.` Use these commands: ```bash ash-sb capability auth poll --flow-id --timeout 300 ash-sb capability auth complete --flow-id --callback-url '' ash-sb capability auth complete --flow-id --code '' ``` If user intent is setup-only, stop after successful auth confirmation. If the user provides a callback URL or auth code in a follow-up message, complete that existing flow immediately with `auth complete`. Do not start a new `auth begin` while a valid callback/code is present unless completion fails with invalid/expired flow. If `flow_id` is not already known, run `ash-sb capability auth list -c --account ` and use the most recent pending flow. ### 2b. Proactive re-auth when scopes change or auth expires If a user asks for an operation and capability invoke/list returns auth-required or similar auth errors: 1. Tell the user this action requires Google re-authorization (for example new Gmail/Calendar scopes or expired authorization). 2. Immediately start auth with `ash-sb capability auth begin -c ` instead of waiting. 3. Present the returned auth URL and clear next step instructions. 4. Continue completion via `auth poll` or `auth complete` based on flow type. Do not stop at "you need auth" when you can initiate the flow directly. ### 3. Perform operations Use only capability operations and explicit JSON input. Core commands: ```bash ash-sb capability invoke -c gog.email -o list_messages --account work --input-json '{"folder":"inbox","limit":20}' ash-sb capability invoke -c gog.email -o search_messages --account work --input-json '{"query":"is:unread newer_than:1d","limit":20}' ash-sb capability invoke -c gog.email -o get_message --account work --input-json '{"id":""}' ash-sb capability invoke -c gog.email -o get_thread --account work --input-json '{"thread_id":"","limit":20}' ash-sb capability invoke -c gog.email -o archive_messages --account work --input-json '{"ids":[""],"archive":true}' ash-sb capability invoke -c gog.email -o update_labels --account work --input-json '{"ids":[""],"add_label_ids":["IMPORTANT"],"remove_label_ids":[]}' ash-sb capability invoke -c gog.calendar -o list_events --account work --input-json '{"calendar":"primary","window":"1d"}' ash-sb capability invoke -c gog.calendar -o create_event --account work --input-json '{"title":"Team sync","start":"2026-03-04T18:00:00Z"}' ``` If the user asks a broad question and does not provide scope, use these defaults: - Email summaries: `search_messages` with `{"query":"is:unread newer_than:1d","limit":20}` - Day-at-a-glance: `list_events` with `{"calendar":"primary","window":"1d"}` plus unread/recent email query - Message deep read: run `get_message` for each item you summarize ### Account and calendar defaults Interpret account/calendar phrasing with these defaults unless user explicitly says otherwise: - "work calendar", "my work calendar", or "calendar at work" means account alias `work` and calendar `primary`. - "personal calendar", "my calendar", or unspecified calendar means account alias `default` and calendar `primary`. - "add/connect/link my calendar" means start auth for `gog.calendar` using that alias. Do not ask taxonomy prompts like "do you mean second account vs shared calendar vs subscribed calendar" before starting auth. If account alias is implied, proceed with that alias and only ask a single follow-up if a concrete operation later needs a non-primary calendar id. ## Behavior Playbooks ### Summarize Emails When user asks for summaries (for example "summarize my emails", "what did I miss"): 1. Gather candidate messages with `search_messages` (preferred) or `list_messages`. 2. Fetch full message content with `get_message` for messages you summarize. 3. Summarize using the section template in `references/output-templates.md`. 4. Keep each bullet tied to a concrete message subject/sender so the user can act on it. Do not summarize from snippets alone when full content can be fetched. ### Day At A Glance When user asks for a day overview: 1. Pull today/near-term calendar with `list_events`. 2. Pull high-signal recent email using `search_messages` (for example unread/new/important) and fetch full content for top items. 3. Render the response with the day-at-a-glance template in `references/output-templates.md`. 4. If there are no events or no high-signal email, say that explicitly instead of leaving sections blank. Use Google calendar + Google email only for this view. ### Standard mutations Before `send_message`, `create_event`, `archive_messages`, or `update_labels`, always confirm key details. Required confirmation fields: - Email send: recipient, subject, body intent - Event create: title, start time/date, end time or duration, timezone context if unclear - Archive/update labels: target account alias, message IDs (or clearly identified messages), and the exact label/archive action ## Output Rules - Keep timestamps conversational (for example "2 hours ago", "tomorrow at 3pm"). - For summary workflows, prefer grouped bullets over raw dumps. - After mutation success, confirm the action and stop unless user asked for more. - Only claim success after command output confirms it. - For auth/setup completion, explicitly state which capability is now connected. - For auth-required errors, use proactive language: - Say what requires re-auth (for example "inbox summary needs Gmail scope re-authorization"). - Provide the exact auth URL/code immediately after initiating `auth begin`. - Ask for callback URL/code in one concise step. Never reply with only "need auth" or "use /google". Always include the runnable next step with the actual auth URL. Do not mention slash commands (for example `/google`) as a substitute for auth instructions. ## Error Handling - If a command fails, report the error message and stop. - Do not request raw credentials or attempt unsupported workarounds. - If capability is unavailable or disabled, instruct the user to enable `[skills.google]`.