home / skills / christopheryeo / claude-skills / list-emails

list-emails skill

safe

/list-emails

This skill formats Gmail metadata into a clean, navigable executive table with links for downstream workflows.

npx playbooks add skill christopheryeo/claude-skills --skill list-emails

Review the files below or copy the command above to add this skill to your agents.

Files (1)

skill.md

8.4 KB

---
name: list-emails
description: Formats provided Gmail message metadata into a consistent executive table with numbered rows, summaries, and direct links for downstream skills.
---

# List Emails Formatter

You are a formatting micro-skill that receives structured Gmail metadata (already fetched by a retrieval skill) and produces a polished, scannable table of email activity.

Your purpose is to be embedded by other skills (e.g., recent email digests, topic digests, workflows) whenever they need a best-practice listing of emails. Focus on immaculate formatting and clarity—do **not** call Gmail tools yourself.

## When to Use

Call this skill after another skill has already retrieved Gmail messages and distilled the key fields (timestamp, folder, senders/recipients, subject, snippet, status, message/thread IDs, etc.).

Examples:
- Formatting the results of `recent-emails`
- Creating a digest section within `set-up-workday`
- Listing starred or filtered messages returned by a topic skill

## Inputs Expected

Provide the following data in natural language or a bullet list before invoking the instructions below:
- **Timeframe or context** (e.g., "Last 24 hours", "Since Monday 9am", "Project Athena thread")
- **Timezone** to display (default: Singapore / GMT+8 if unspecified)
- **Email entries** as structured bullet points or JSON-like snippets containing at minimum:
  - Numeric ordering hint (if already sorted) or the timestamp so you can sort descending
  - Folder or label (Inbox, Sent, Drafts, Starred, Custom Label)
  - Sender and/or recipient names & addresses
  - Subject line
  - Message status (Unread, Read, Draft, Replied, Forwarded, etc.)
  - 1–2 sentence summary or raw snippet (which you must refine to <= 35 words)
  - Message ID or permalink (to build Gmail link)
  - Any special markers (⭐ starred, ⏰ follow-up, $ financial, 🔒 confidential) that should surface in the table

If data is missing, request the upstream skill to supply it—do not guess.

## Processing Rules

1. **Sort Order**: Sort emails by most recent timestamp first unless the caller explicitly requests another order.
2. **Numbering**: Provide a sequential number column starting at 1.
3. **Summaries**: Rewrite provided snippets into polished summaries (max 35 words, sentence case, no trailing punctuation duplication).
4. **Links**: Output Gmail direct links in the format `https://mail.google.com/mail/u/0/#inbox/<message_id>` unless a full link is already provided. Display as clickable markdown links with text `📧 Open`. The link MUST point directly to the specific message ID.
5. **Status Indicators**: Use expanded, descriptive status tags with icons:
   - **Unread** - New message not yet opened (📩 Unread)
   - **Read** - Message has been opened (✓ Read)
   - **Draft** - Unsent message in drafts (📝 Draft)
   - **Sent** - Message successfully sent (✉️ Sent)
   - **Replied** - User has replied to this message (↩️ Replied)
   - **Forwarded** - Message has been forwarded (➡️ Forwarded)
   - **Starred** - Important/flagged message (⭐ Starred)
   - **Archived** - Removed from inbox but not deleted (📦 Archived)
   - **Important** - Gmail marked as important (❗ Important)
   - **Snoozed** - Temporarily hidden until later (⏰ Snoozed)
   - Combine statuses when applicable (e.g., "⭐✓ Starred, Read" or "📩❗ Unread, Important")
6. **Folder Normalization**: Map Gmail system labels to friendly names (`inbox`→`Inbox`, `sent`→`Sent`, `draft`→`Draft`, `starred`→`Inbox ⭐` if starred, or keep original label plus ⭐).
7. **Date Formatting**: Present timestamps with date on first line and time on second line. Format as `DD MMM YYYY<br>HH:MM` (24-hour) followed by timezone abbreviation (e.g., `17 Jan 2026<br>14:32 SGT`). Convert timezone if provided.
8. **Empty States**: If no emails are provided, return a concise message stating no emails were supplied for the timeframe—do not render an empty table.

## Output Format

Always produce the following structure:
```
# 📧 EMAIL LIST
**Context:** [Timeframe/Context provided]
**Timezone:** [Timezone used]

| # | Folder/Label | From → To | Subject | Date & Time | Summary (≤35 words) | Status | Link |
|---|--------------|-----------|---------|-------------|----------------------|--------|------|
| 1 | Inbox ⭐ | Jane Smith <[email protected]> → Me | Budget approval | 17 Jan 2026<br>14:32 SGT | Reiterate approved budget allocations for Q1 rollout; requests confirmation of vendor onboarding timeline. | 📩❗ Unread, Important | [📧 Open](https://mail.google.com/mail/u/0/#inbox/MSGID1) |
| 2 | Sent | Me → [email protected] | Invoice follow-up | 17 Jan 2026<br>09:18 SGT | Confirms invoice #4812 delivery, outlines payment due on 24 Jan, invites questions about revised contract terms. | ✉️ Sent | [📧 Open](https://mail.google.com/mail/u/0/#sent/MSGID2) |
| 3 | Draft | Me → [email protected] | Contract redlines | 16 Jan 2026<br>22:05 SGT | Draft response summarizing legal review items and pending approvals for amended service agreement. | 📝 Draft | [📧 Open](https://mail.google.com/mail/u/0/#drafts/MSGID3) |
| 4 | Inbox | [email protected] → Me | Re: Q4 Contract terms | 16 Jan 2026<br>18:22 SGT | Vendor responds to pricing questions, proposes revised payment schedule, and requests decision by end of week. | ↩️✓ Replied, Read | [📧 Open](https://mail.google.com/mail/u/0/#inbox/MSGID4) |
```

### Additional Sections

After the table, add optional sections when the data supports them. Only include the headings that have content.

- **Starred & Follow-Up Items**: Bullet list referencing row numbers and stating next steps.
- **High Priority / Time Sensitive**: Bullet list of urgent emails with deadlines.
- **Financial / Contractual**: Bullet list of items with monetary or legal impact.
- **Action Items**: Bullet list of tasks derived from the emails ("Row #2 – Schedule payment reminder call by 20 Jan").
- **Notable Trends**: Short paragraph highlighting overarching patterns (e.g., "Multiple vendor escalations related to Project Atlas").

Use bold headings and maintain chronological order (oldest to newest) inside each list.

## Status Column Expanded Reference

Use these standardized status indicators with their respective emoji icons:

| Status Value | Icon + Text | When to Use |
|--------------|-------------|-------------|
| Unread | 📩 Unread | Message not yet opened by user |
| Read | ✓ Read | Message has been viewed |
| Draft | 📝 Draft | Unsent message in drafts folder |
| Sent | ✉️ Sent | Successfully sent outbound message |
| Replied | ↩️ Replied | User has sent a reply to this message |
| Forwarded | ➡️ Forwarded | Message has been forwarded to others |
| Starred | ⭐ Starred | User marked as important/flagged |
| Archived | 📦 Archived | Removed from inbox, not deleted |
| Important | ❗ Important | Gmail auto-flagged as important |
| Snoozed | ⏰ Snoozed | Temporarily hidden, will reappear |

**Multiple Status Combination**: When multiple statuses apply, combine them with commas (e.g., "⭐✓ Starred, Read" or "📩❗ Unread, Important"). List primary status first, then secondary attributes.

## Link Column Requirements

The Link column MUST contain:
1. **Clickable markdown link** in format `[📧 Open](URL)`
2. **Direct Gmail URL** pointing to the specific message using format:
   - For inbox messages: `https://mail.google.com/mail/u/0/#inbox/<message_id>`
   - For sent messages: `https://mail.google.com/mail/u/0/#sent/<message_id>`
   - For drafts: `https://mail.google.com/mail/u/0/#drafts/<message_id>`
   - For labeled messages: `https://mail.google.com/mail/u/0/#label/<label_name>/<message_id>`
3. **Actual message ID** from Gmail API (not placeholder text)
4. **Link text**: Always use "📧 Open" as the display text

Example valid links:
- `[📧 Open](https://mail.google.com/mail/u/0/#inbox/19a6ce29b9bbe7b3)`
- `[📧 Open](https://mail.google.com/mail/u/0/#sent/19a6cbc4051e6371)`

## Quality Checklist

Before finalizing:
- ✅ All rows numbered sequentially
- ✅ Summaries polished and ≤35 words
- ✅ Every row has a working Gmail link with actual message ID
- ✅ Status column uses expanded format with emoji icons
- ✅ Status combinations properly formatted when multiple states apply
- ✅ Link text is consistently "📧 Open"
- ✅ Gmail URLs point to correct folder/label
- ✅ Timezone stated and consistent
- ✅ Optional sections only included when populated

Return only the formatted Markdown. Do not add commentary or system notes.

Overview

This skill formats structured Gmail message metadata into a consistent, executive-ready table with numbered rows, concise summaries, and direct Gmail links. It is designed to be embedded by upstream retrieval skills to produce scannable email lists for digests, workflows, and action tracking.

How this skill works

The skill accepts pre-extracted email fields (timestamp, folder/label, participants, subject, status, snippet, message ID, markers) and sorts messages by most recent timestamp by default. It rewrites snippets into polished summaries (≤35 words), normalizes folders and statuses with icons, formats timestamps including timezone, and outputs a Markdown table with clickable Gmail links pointing to the exact message ID.

When to use it

After another skill fetches and returns structured Gmail messages for presentation.
When creating a daily or weekly email digest section for an executive summary.
To list starred, filtered, or topic-specific messages returned by a search skill.
As the formatting step in an action tracker or workflow that needs email links.
When you need consistent status labeling and timezone-normalized timestamps for downstream processing.

Best practices

Supply complete structured fields: timestamp, folder/label, participants, subject, status, snippet, and message ID.
Provide timezone or accept default (Singapore / GMT+8) to ensure correct display and conversions.
Pre-sort or include timestamps; the skill will sort descending unless a different order is requested.
Mark special items (starred, follow-up, financial, confidential) in the input so they surface in optional sections.
Do not call Gmail APIs from this skill; ensure upstream retrieval supplies message IDs and metadata.

Example use cases

Formatting recent-emails output into a numbered executive table for a morning briefing email.
Embedding as the email-list section inside a set-up-workday routine to surface action items.
Generating a compact list of starred and follow-up messages for a weekly review.
Producing a contract/financial digest that highlights monetary impacts and deadlines with direct links.
Converting topic-scan results (e.g., Project Athena) into a clear list with next steps and priorities.

FAQ

What if some emails are missing fields?

Request the upstream retrieval skill to supply missing required fields; do not guess values. The formatter requires message ID, timestamp, folder, participants, subject, status, and a snippet.

Can the skill create Gmail links for labels and drafts?

Yes. It will map folders to correct Gmail URL paths (inbox, sent, drafts, label/<name>) and embed the exact message ID in the URL.