Table of Contents generated with DocToc
This directory documents the Gmail tool adapter — the set of capabilities the skills use when the adopting project declares Gmail as its inbound-email / draft-creation backend.
A project opts into this tool by naming it in its manifest under Tools enabled. For the adopting project see ../../<project-config>/project.md.
The skills use Gmail for four capabilities. Each has its own reference file in this directory:
| Capability | File | What it covers |
|---|---|---|
| MCP operations | operations.md | The mcp__claude_ai_Gmail__* tool catalogue (search, read, draft, list) + the no-update / no-delete limitation |
| Drafting backends | draft-backends.md | The two drafting backends (claude.ai Gmail MCP vs OAuth + curl), why both exist, and the tools.gmail.draft_backend config knob |
| Threading | threading.md | The “always pass threadId when the backend supports it” rule — how drafts stay on the inbound thread across reporter replies, ASF-security relays, PMC credit questions, follow-ups |
| ASF-security-relay drafting | asf-relay.md | Special-case drafting rules when the inbound report is relayed by the ASF security team rather than sent by the external reporter directly |
| Search queries | search-queries.md | Gmail search-operator cheat-sheet + skill-specific query templates (candidate-listing, reporter-thread lookup, CVE-review comments) |
Related, adjacent tool:
| Capability | File | What it covers |
|---|---|---|
| ASF PonyMail archive lookups | ponymail-archive.md | URL-construction pattern for the ASF's lists.apache.org archive (used by sync-security-issue to scan the public users@ archive for the advisory URL, and by import-security-issue to resolve a pastable thread URL for the private security@ list) |
Gmail is the security team‘s inbox for the private security@<project>.apache.org mailing list and the draft queue for every outbound reporter reply the skills compose. Gmail’s draft capability is load-bearing and cannot be swapped — this directory stays in every project's toolchain because PonyMail MCP, the alternative read path documented at ../ponymail/tool.md, is read-only and cannot compose reporter replies.
Role when PonyMail MCP is opted into. When a user sets tools.ponymail.enabled: true in their config/user.md and authenticates the MCP, PonyMail becomes the primary read backend for archive queries (reporter-thread lookups, reviewer-comment searches, users@ / dev@ archive scans, prior-rejection precedents). Gmail stays as the fallback read path — used when a specific list is outside the user's tools.ponymail.private_lists allowlist, when PonyMail returns an error, or when inbox latency matters for just-arrived messages. Gmail remains the only backend for draft composition regardless. When the user has not opted into PonyMail MCP, Gmail is the sole read backend and the skills run exactly as before.
A project that runs on a different mail stack can swap this directory for a sibling tools/<name>/ that provides equivalent capabilities against its own backend (Fastmail, Microsoft Graph, Mailgun, a ponymail-mcp OAuth flow, …). The contract the generic skills rely on is:
Re: <root subject> + In-Reply-To / References headers so the recipient's client still threads it). The two backends available today are documented in draft-backends.md.The threading semantics — “prefer thread attachment when available; fall back to same-subject matching, never fabricate a new subject” — are non-negotiable regardless of backend; see threading.md.
Gmail drafts created by the skills land in the user's personal Gmail account and are visible only to that user until sent. Never send — the skills only create drafts; a human review-and-send step is required for every outbound message. Confidentiality rules in ../../AGENTS.md still bind the draft content: status updates to the reporter may reference the private tracker URL (reporter is on the private thread), but any message destined for a mailing list outside the security circle must be scrubbed.