/triage-inbox

name: triage-inbox
description: Classify and file recent Gmail messages using the user's saved email policy. Use for inbox triage or a scheduled sorting run, including triage requested by checkin. Does not clear a historical backlog, create permanent filters, or send replies.
metadata:
  version: "2.0.0"

Inbox triage

Read recent inbox mail and file routine messages under the user's agreed rules. Preserve requests, substantive human correspondence, uncertain cases, and explicit holds for review. Return the result to `/checkin` when it invoked this skill.

This folder includes its setup templates, workflow references, and local state helper. It requires an existing Gmail connection and Python 3.9 or later, with no extra Python packages. It does not require `/checkin`, the starter kit, private scripts, or a new authenticated Gmail client. A calendar connection is optional for verifying invitations.

Modes

| Invocation | Behavior | |---|---| | `/triage-inbox` | Scan, report, and apply routine label/filing changes covered by the approved policy. | | `/triage-inbox noapply` or `/triage-inbox dryrun` | Read and show proposals only. No Gmail changes, policy edits, operational state writes, locks, or run logs. | | `/triage-inbox days:3` | Inspect the last three days. Do not advance the ordinary automatic checkpoint. | | `/triage-inbox limit:20` | Review at most 20 unique candidates across all searches, including the sweep. Report uncovered work and do not advance the checkpoint. |

Arguments combine. Resolve ambiguous arguments before acting. Until the user approves their policy and permitted actions, use preview. Missing or conflicting policy/configuration stops affected actions. A scheduled run reports missing setup instead of substituting defaults. Do not change permissions or credentials to overcome a tool denial.

First-time setup

Install the entire skill folder where the user stores skills. Have the agent do the following; the user should not have to edit label IDs or JSON:

1. **Find the existing setup.** Read the project's standing instructions and the user's chosen email-assistant folder for the account, policy, configuration, and state paths. Support the older `~/.claude-assistant/config/` and `state/` layout if already in use. Reuse existing decisions and customizations, without creating competing policies. 2. **Check the mail connection.** Discover tools for Gmail search, full message reading, label listing, label modification, and readback. Claude may expose Workspace MCP tools; Codex may expose Gmail connector tools. Map capabilities to their actual schemas. Read access is enough for preview. Explain any missing write capability before apply mode. 3. **Choose folders if needed.** A new setup can use this structure in any local or synced project folder. Runtime data belongs outside the installed skill:

   email-assistant/
   ├── policies/email-policy.md
   ├── config/triage-config.md
   └── state/triage-run-state.json

4. **Fill in the bundled templates.** Copy [email-policy.md](assets/email-policy.md) and [triage-config.md](assets/triage-config.md) only when the corresponding file is absent. Reconcile missing fields in existing files instead of overwriting them. Ask about important people, mail to keep visible, categories, read status, and holds. Examples are inactive until reviewed. 5. **Map the user's labels.** List existing Gmail labels and record their actual names/IDs in configuration. Create missing labels only after agreement. Do not require the example names or create `@FYI`. Preserve nested label names exactly as returned by the connection. 6. **Approve the policy and preview.** Show the routine filing permissions and exceptions. Record the user's agreement during setup, then run `/triage-inbox noapply`. Resolve mistakes before the first apply run. Setup writes and label creation are separate actions, never part of a `noapply` invocation. 7. **Save the locations.** Record the account and policy/config/state paths in standing instructions for future sessions and scheduled runs. Use separate state files for multiple accounts. If adopting old state without an account field, confirm which account it belongs to first. Installing this skill creates no schedule.

Example request:

Help me set up /triage-inbox for my Gmail account. Reuse the labels and email-handling rules we've already agreed on. Find my existing policy and configuration, or use the templates included with this skill if I don't have them yet.

Ask about missing choices, check the connection, and show me a preview before enabling routine filing. Preserve read and unread status unless I approve a different rule for a specific category.

Run the workflow

Read the policy/configuration and [execution.md](references/execution.md) for tools, coverage, verification, and state handling. Use [classification.md](references/classification.md) for disposition decisions. Both references are included in this folder.

1. Establish scope and ownership

Resolve one account and the saved paths. Take current holds from the user or calling `/checkin` before classification. A read-state hold and an inbox-retention hold are distinct. Never turn one into permission to violate the other.

Use the bundled helper to establish a fixed run start and lookback. Automatic runs use the last valid checkpoint with six hours of overlap and a minimum one-day window. Missing/invalid/future checkpoints use a two-day fallback and disclose older unsearched gaps. Do not silently cap an older valid checkpoint at seven days.

Acquire the helper's apply lease before any Gmail mutation. One run owns filing for this account/state path. A parent check-in and its worker must not write concurrently. Preview takes no lease. If Python or durable state is unavailable, offer read-only review rather than untracked automatic filing.

2. Discover and read before classifying

Search recent inbox mail, both re