Refactor Google skill with progressive disclosure references

Co-Authored-By: GPT-5 Codex <codex@openai.com>

Author: dcramer

src/ash/integrations/skills/capabilities/google/SKILL.md

@@ -24,6 +24,12 @@ input_schema:
 
 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.
@@ -71,7 +77,7 @@ If user intent is setup-only, stop after successful auth confirmation.
 
 Use only capability operations and explicit JSON input.
 
-Common email/calendar commands:
+Core commands:
 
 ```bash
 ash-sb capability invoke -c gog.email -o list_messages --input-json '{"folder":"inbox","limit":20}'
@@ -96,11 +102,7 @@ When user asks for summaries (for example "summarize my emails", "what did I mis
 
 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 this structure:
-   - `Top priorities`
-   - `Needs reply`
-   - `FYI`
-   - `Suggested next actions`
+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.
@@ -111,11 +113,7 @@ 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. Return this structure:
-   - `Today's schedule`
-   - `Email priorities`
-   - `Conflicts / follow-ups`
-   - `Recommended next steps`
+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.

src/ash/integrations/skills/capabilities/google/references/auth-and-failures.md

@@ -0,0 +1,51 @@
+# Auth and Failure Handling
+
+Use this reference when capability auth is missing, expired, or command execution fails.
+
+## Auth Flow Handling
+
+1. Run `ash-sb capability list`.
+2. For any required capability with `Authenticated: no`, run `auth begin`.
+3. Complete with the appropriate flow:
+   - `device_code`: show URL + code, then poll.
+   - `authorization_code`: ask for callback URL or code, then `auth complete`.
+
+If user intent is setup-only, stop after auth succeeds.
+
+## Callback URL vs Code
+
+If user provides a callback URL (`http://localhost/?code=...`), pass it with `--callback-url`.
+If user provides only a code value, pass it with `--code`.
+
+Never ask for OAuth secrets.
+
+## Expired/Invalid Flow Recovery
+
+If `auth complete` reports invalid/expired flow:
+
+1. Tell the user their previous auth flow expired or no longer matches active state.
+2. Start a fresh auth flow.
+3. Ask them to complete promptly and provide the new callback URL/code.
+
+## Capability Availability Errors
+
+If capability is missing entirely:
+
+- Tell user to enable `[skills.google]`.
+- Stop rather than guessing alternatives.
+
+## Operation Failures
+
+On failure:
+
+1. Report the command error clearly.
+2. Do not claim success.
+3. Do not invent fallback data.
+4. Stop unless user asks for troubleshooting.
+
+## Mutating Action Safety
+
+Before mutating operations:
+
+- `send_message`: confirm recipient, subject intent, and body intent when ambiguous.
+- `create_event`: confirm title, date/time, and duration/end time when ambiguous.

src/ash/integrations/skills/capabilities/google/references/gmail-workflows.md

@@ -0,0 +1,47 @@
+# Gmail Workflows
+
+Use this reference when the user asks for inbox triage, email summaries, or a day-at-a-glance view.
+
+## Query Recipes
+
+Use `search_messages` with focused Gmail query syntax.
+
+| Goal | Query |
+|------|-------|
+| Unread in last day | `is:unread newer_than:1d` |
+| Unread in last week | `is:unread newer_than:7d` |
+| Important/unread | `is:important is:unread` |
+| From a person/domain | `from:alice@example.com` or `from:@example.com` |
+| Time-sensitive subjects | `subject:(urgent OR asap OR today)` |
+| Action requests | `("can you" OR "please review" OR "action required") newer_than:7d` |
+
+Prefer a narrow query first, then broaden if needed.
+
+## Summarize Emails Workflow
+
+1. Run `search_messages` (or `list_messages` when folder-based scope is requested).
+2. Select top candidates by recency + urgency language + sender relevance.
+3. Run `get_message` for each selected message before summarizing.
+4. Summarize with actionable bullets tied to sender and subject.
+
+Do not rely on snippets when full message content is available.
+
+## Day-At-A-Glance Workflow (Email Portion)
+
+1. Start with `search_messages` default query: `is:unread newer_than:1d`.
+2. If results are sparse, broaden to `newer_than:2d` or remove `is:unread`.
+3. Pull full content for top 3-8 messages with `get_message`.
+4. Prioritize messages that imply deadlines, asks, or pending replies.
+
+## Thread Usage
+
+Use `get_thread` when:
+
+- The user asks for context on a conversation.
+- A message implies prior back-and-forth and reply context matters.
+- You need to summarize the evolution of a decision.
+
+Use `get_message` when:
+
+- The user asks about one specific email.
+- You only need the latest message content.

src/ash/integrations/skills/capabilities/google/references/output-templates.md

@@ -0,0 +1,63 @@
+# Output Templates
+
+Use these templates to keep responses concise and actionable.
+
+## Email Summary Template
+
+```
+Top priorities
+- <sender> — <subject>: <1-line why this matters now>
+
+Needs reply
+- <sender> — <subject>: <what reply is needed and by when if known>
+
+FYI
+- <sender> — <subject>: <short informational summary>
+
+Suggested next actions
+- <concrete next step 1>
+- <concrete next step 2>
+```
+
+Guidelines:
+
+- Use sender + subject in each bullet.
+- Prefer short, decision-focused language.
+- If a section has no items, write `- None`.
+
+## Day-At-A-Glance Template
+
+```
+Today's schedule
+- <time range>: <event title> (<location/meeting link if available>)
+
+Email priorities
+- <sender> — <subject>: <action needed>
+
+Conflicts / follow-ups
+- <scheduling conflict or follow-up item>
+
+Recommended next steps
+- <step 1>
+- <step 2>
+```
+
+Guidelines:
+
+- Keep chronology clear in schedule section.
+- Highlight time-sensitive asks.
+- If no events or no high-signal email, state that explicitly.
+
+## Mutation Confirmation Template
+
+For successful sends/creates:
+
+```
+Sent: "<subject>" to <recipient>
+```
+
+```
+Created: <event title> — <day/time range>
+```
+
+Do not append unrelated listings unless user requests them.