gmail

Files (1)

• SKILL.md

SKILL.md (first lines)

# Gmail Reports — Claude Code Skill Suite (March 2026)

> **Philosophy:** Gmail-first, reporting-powered. Turn raw inbox data into
> clear, client-ready or personal productivity reports.

---

## Quick Reference

| Command | What It Does |
|---------|-------------|
| `/gmail report today` | Full report for today's emails |
| `/gmail report week` | Full report for the last 7 days |
| `/gmail report month` | Full report for the current or last 30 days |
| `/gmail report year` | Full report for the current or last 12 months |
| `/gmail summary today` | Fast snapshot of volume, unread count, and top senders |
| `/gmail summary week` | Weekly summary without full deep analysis |
| `/gmail unread today` | Report only unread emails from today |
| `/gmail unread week` | Report only unread emails from the week |
| `/gmail spam week` | Analyze spam volume and spam trends for the week |
| `/gmail senders month` | Rank top senders for the month |
| `/gmail labels month` | Break down email volume by Gmail labels |
| `/gmail categories month` | Analyze Primary, Promotions, Social, Updates, and Forums |
| `/gmail attachments month` | Report attachment-heavy traffic and file volume |
| `/gmail response-time week` | Estimate reply behavior and response latency |
| `/gmail trends year` | Compare activity across months over the year |
| `/gmail custom --from YYYY-MM-DD --to YYYY-MM-DD` | Custom date range report |
| `/gmail organize month` | Analyze unlabeled emails and suggest label taxonomy |
| `/gmail suggest-labels month` | Alias for `/gmail organize` |
| `/gmail report-pdf` | Generate a professional PDF report with charts and tables |

### Common Filters

- `--include-spam` / `--exclude-spam`
- `--unread-only` / `--read-only` / `--all-received`
- `--label "Work"`
- `--category promotions`
- `--sender someone@example.com`
- `--has-attachments`
- `--from YYYY-MM-DD` / `--to YYYY-MM-DD`
- `--pdf` (generate PDF version)
- `--pt` (output in Portuguese)

---

## Orchestration Logic

### Full Report (`/gmail report <period>`)

**Phase 1: Data Collection (Sequential)**
1. **Detect data source** — Check availability in this order:
   - MCP Gmail tools available → use directly (no credentials needed)
   - `credentials.json` present → run `scripts/fetch_gmail_data.py` (OAuth flow)
   - Exported mailbox file provided → load JSON/CSV/MBOX directly
2. Fetch messages for the requested period
3. Apply selected filters (unread, spam, label, sender, category, attachments)

**Phase 2: Parallel Analysis (Delegate to Subagents)**
Launch these 5 subagents simultaneously:

| Subagent | File | Responsibility |
|----------|------|---------------|
| gmail-volume-analysis | `agents/gmail-volume-analysis.md` | Volume, spikes, and seasonality |
| gmail-noise-analysis | `agents/gmail-noise-analysis.md` | Spam, low-value mail, clutter patterns |
| gmail-sender-analysis | `agents/gmail-sender-analysis.md` | Sender ranking and concentration |
| gmail-organization-analysis | `agents/gmail-organization-analysis.md` | Labels, categories, inbox structure |
| gmail-response-analysis | `agents/gmail-response-analysis.md` | Response behavior and follow-up patterns |

**Phase 3: Synthesis (Sequential)**
1. Collect all subagent reports
2. Calculate composite Gmail Inbox Score (0-100)
3. Generate prioritized findings and recommendations
4. Output client-ready report (Markdown or PDF)

### Scoring Methodology

| Category | Weight |
|----------|--------|
| Inbox Health & Workload | 25% |
| Unread Backlog | 20% |
| Spam / Noise Ratio | 15% |
| Sender Concentration | 10% |
| Response Behavior | 15% |
| Label & Category Organization | 10% |
| Attachment / File Load | 5% |

---

## Sub-Skills (15 Specialized Components)

| # | Skill | Directory | Purpose |
|---|-------|-----------|---------| 
| 1 | gmail-report | `skills/gmail-report/` | Full report orchestration and scoring |
| 2 | gmail-summary | `skills/gmail-summary/` | Quick inbox summary |
| 3 | gmail-period | `skills/gmail-period/` | Day/week/month/year/custom range handling |
| 4 | gmail-unread | `skills/gmail-unread/` | Unread-only filtering and analysis |
| 5 | gmail-spam | `skills/gmail-spam/` | Spam inclusion/exclusion analysis |
| 6 | gmail-senders | `skills/gmail-senders/` | Top senders and sender concentration |
| 7 | gmail-labels | `skills/gmail-labels/` | Label distribution analysis (descriptive) |
| 8 | gmail-categories | `skills/gmail-categories/` | Promotions/Social/Primary/etc. analysis |
| 9 | gmail-attachments | `skills/gmail-attachments/` | Attachment volume and file pattern analysis |
| 10 | gmail-response-time | `skills/gmail-response-time/` | Reply speed and follow-up behavior |
| 11 | gmail-trends | `skills/gmail-trends/` | Trend lines across days, weeks, months |
| 12 | gmail-custom | `skills/gmail-custom/` | Custom date-range reports with mixed filters |
| 13 | gmail-report-md | `skills/gmail-report-md/` | Markdown report generation |
| 14 | gmail-report-pdf | `skills/gmail-report-pdf/` | Professional PDF report with charts |
| 15 | gmail-organize | `skills/gmail-organize/` | Inbox organization advisor (prescriptive) |

---

## Subagents (5 Parallel Workers)

| Agent | File | Skills Used |
|-------|------|-------------|
| gmail-volume-analysis | `agents/gmail-volume-analysis.md` | gmail-period, gmail-report |
| gmail-noise-analysis | `agents/gmail-noise-analysis.md` | gmail-spam |
| gmail-sender-analysis | `agents/gmail-sender-analysis.md` | gmail-senders |
| gmail-organization-analysis | `agents/gmail-organization-analysis.md` | gmail-labels, gmail-categories, gmail-organize |
| gmail-response-analysis | `agents/gmail-response-analysis.md` | gmail-response-time |

From michelbr84/gmail-report-claude, MIT.

More from michelbr84/gmail-report-claude