Skip to content

Commit fe43533

Browse files
radiosilenceclaude
radiosilence
and
claude
authored
feat: add /fastmail Claude Code skills (#13)
* feat: add /fastmail Claude Code skills for CC users Adds a global /fastmail skill plus 6 subcommand-focused skills so Claude Code agents know how to use the CLI without guessing flags. Closes #5 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: add skill frontmatter headers to all fastmail skills Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: add Claude Code skills section to README Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 6698647 commit fe43533

8 files changed

Lines changed: 585 additions & 0 deletions

File tree

‎.claude/skills/fastmail.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: fastmail
3+
description: Complete reference for fastmail-cli — all commands, flags, config, and common patterns
4+
---
5+
6+
# fastmail-cli — Complete Reference
7+
8+
fastmail-cli is a Rust CLI for Fastmail via JMAP (email) and CardDAV (contacts). All output is JSON: `{"success": true, "data": {...}}`.
9+
10+
## Setup
11+
12+
```bash
13+
fastmail-cli auth fmu1-YOUR-TOKEN
14+
```
15+
16+
Config lives at `~/.config/fastmail-cli/config.toml`:
17+
```toml
18+
[core]
19+
api_token = "fmu1-..."
20+
21+
[contacts]
22+
username = "you@fastmail.com"
23+
app_password = "xxxx..."
24+
```
25+
26+
Or via env: `FASTMAIL_API_TOKEN`, `FASTMAIL_USERNAME`, `FASTMAIL_APP_PASSWORD`
27+
28+
Debug: `RUST_LOG=debug fastmail-cli [cmd]`
29+
30+
---
31+
32+
## Command Reference
33+
34+
### List
35+
36+
```bash
37+
fastmail-cli list emails [-m MAILBOX] [-l LIMIT] # default: INBOX, 50
38+
fastmail-cli list mailboxes
39+
fastmail-cli list identities # sender aliases for --from
40+
```
41+
42+
### Get & Thread
43+
44+
```bash
45+
fastmail-cli get EMAIL_ID # full email with body
46+
fastmail-cli thread EMAIL_ID # entire conversation
47+
```
48+
49+
### Search
50+
51+
```bash
52+
fastmail-cli search [OPTIONS]
53+
--text/-t STR # full-text (from/to/subject/body)
54+
--from/--to/--cc/--bcc/--subject/--body STR
55+
--mailbox/-m STR
56+
--before/--after STR # ISO 8601: 2024-01-15
57+
--unread --flagged --has-attachment
58+
--min-size/--max-size BYTES
59+
--limit/-l N # default 50
60+
```
61+
62+
### Compose
63+
64+
```bash
65+
fastmail-cli send --to ADDR --subject SUBJ --body BODY [--cc] [--bcc] [--from IDENTITY] [--draft]
66+
fastmail-cli reply EMAIL_ID --body BODY [--all] [--cc] [--bcc] [--from IDENTITY] [--draft]
67+
fastmail-cli forward EMAIL_ID --to ADDR [--body STR] [--cc] [--bcc] [--from IDENTITY] [--draft]
68+
```
69+
70+
### Manage
71+
72+
```bash
73+
fastmail-cli move EMAIL_ID --to MAILBOX
74+
fastmail-cli mark-read EMAIL_ID [--unread]
75+
fastmail-cli spam EMAIL_ID [-y]
76+
```
77+
78+
### Attachments
79+
80+
```bash
81+
fastmail-cli download EMAIL_ID [-o OUTPUT_DIR] [-f raw|json] [--max-size 1M]
82+
```
83+
84+
### Masked Email
85+
86+
```bash
87+
fastmail-cli masked list
88+
fastmail-cli masked create [--domain URL] [--description STR] [--prefix STR]
89+
fastmail-cli masked enable/disable/delete ID [-y]
90+
```
91+
92+
### Contacts
93+
94+
```bash
95+
fastmail-cli contacts list
96+
fastmail-cli contacts search QUERY # name, email, or org
97+
```
98+
99+
### Other
100+
101+
```bash
102+
fastmail-cli completions bash|zsh|fish|powershell
103+
fastmail-cli mcp # start MCP server for Claude Desktop
104+
```
105+
106+
---
107+
108+
## Common Patterns
109+
110+
```bash
111+
# Find unread emails from a sender
112+
fastmail-cli search --from boss@company.com --unread
113+
114+
# Get a thread then reply
115+
fastmail-cli thread abc123
116+
fastmail-cli reply abc123 --body "Thanks, will do." --from work@me.com
117+
118+
# Save draft instead of sending
119+
fastmail-cli send --to x@y.com --subject "Draft" --body "..." --draft
120+
121+
# Download all attachments from an email
122+
fastmail-cli download abc123 -o ~/Downloads
123+
124+
# Move to folder after reading
125+
fastmail-cli move abc123 --to "Archive"
126+
```
127+
128+
---
129+
130+
## Subcommand Skills
131+
132+
- `/fastmail/search` — search workflows and filter combinations
133+
- `/fastmail/compose` — send, reply, forward, drafts, identities
134+
- `/fastmail/conversations` — threading, listing, reading
135+
- `/fastmail/attachments` — downloading and extracting attachments
136+
- `/fastmail/masked` — masked email management
137+
- `/fastmail/contacts` — contact search

‎.claude/skills/fastmail/attachments.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: fastmail/attachments
3+
description: fastmail-cli download — save attachments or extract text content from emails
4+
---
5+
6+
# fastmail-cli — Attachments
7+
8+
## Download Attachments
9+
10+
```bash
11+
fastmail-cli download EMAIL_ID [OPTIONS]
12+
```
13+
14+
| Flag | Short | Description |
15+
|------|-------|-------------|
16+
| `--output` | `-o` | Output directory (default: current dir) |
17+
| `--format` | `-f` | `raw` (save files) or `json` (extract text content) |
18+
| `--max-size` | | Max image size before resizing (e.g. `500K`, `1M`) |
19+
20+
## Examples
21+
22+
```bash
23+
# Download all attachments to current directory
24+
fastmail-cli download abc123
25+
26+
# Download to specific folder
27+
fastmail-cli download abc123 -o ~/Downloads/invoices
28+
29+
# Extract text content as JSON (good for parsing docs/PDFs)
30+
fastmail-cli download abc123 -f json
31+
32+
# Resize large images during download
33+
fastmail-cli download abc123 --max-size 800K -o ~/Downloads
34+
```
35+
36+
## Format Details
37+
38+
**`raw`** (default): Saves attachment files to disk as-is.
39+
40+
**`json`**: Extracts text from attachments using kreuzberg (supports 56+ formats including PDF, DOCX, XLSX, images with OCR, etc.). Returns structured JSON with content and detected language — useful for agents that need to read document contents without saving files.
41+
42+
## Workflow: Find Emails with Attachments Then Download
43+
44+
```bash
45+
# Find emails with attachments
46+
fastmail-cli search --has-attachment --from invoices@vendor.com
47+
48+
# Download attachments from a specific email
49+
fastmail-cli download EMAIL_ID -o ~/Documents/invoices
50+
51+
# Or extract text for processing
52+
fastmail-cli download EMAIL_ID -f json | jq '.data[].content'
53+
```
54+
55+
## Tips
56+
57+
- `get EMAIL_ID` includes attachment metadata (names, sizes, content types) without downloading — check what's there before downloading.
58+
- Use `-f json` when you need to read document content programmatically; use `raw` when you need the actual files.
59+
- `--max-size` is useful for emails with many large images where you only need thumbnails.

‎.claude/skills/fastmail/compose.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
name: fastmail/compose
3+
description: fastmail-cli send, reply, forward, draft — flags, identities, and compose patterns
4+
---
5+
6+
# fastmail-cli — Compose (Send / Reply / Forward / Draft)
7+
8+
## Identities
9+
10+
Before composing, check available sender identities:
11+
12+
```bash
13+
fastmail-cli list identities
14+
```
15+
16+
Use the identity email string with `--from` on any compose command.
17+
18+
---
19+
20+
## Send
21+
22+
```bash
23+
fastmail-cli send \
24+
--to "alice@example.com,bob@example.com" \
25+
--subject "Subject line" \
26+
--body "Plain text body" \
27+
[--cc "cc@example.com"] \
28+
[--bcc "bcc@example.com"] \
29+
[--from "alias@yourdomain.com"] \
30+
[--draft]
31+
```
32+
33+
- `--to`, `--subject`, `--body` are required.
34+
- Multiple recipients: comma-separated string.
35+
- `--draft` saves to Drafts instead of sending.
36+
37+
## Reply
38+
39+
```bash
40+
fastmail-cli reply EMAIL_ID \
41+
--body "Reply text" \
42+
[--all] \
43+
[--cc "extra@example.com"] \
44+
[--bcc "hidden@example.com"] \
45+
[--from "alias@yourdomain.com"] \
46+
[--draft]
47+
```
48+
49+
- `EMAIL_ID` is the email you're replying to (from `list`, `search`, or `thread`).
50+
- `--all` replies to all recipients (reply-all).
51+
- Threading headers (`In-Reply-To`, `References`) are set automatically.
52+
53+
## Forward
54+
55+
```bash
56+
fastmail-cli forward EMAIL_ID \
57+
--to "recipient@example.com" \
58+
[--body "Here's that email I mentioned..."] \
59+
[--cc "cc@example.com"] \
60+
[--bcc "bcc@example.com"] \
61+
[--from "alias@yourdomain.com"] \
62+
[--draft]
63+
```
64+
65+
- `--body` is optional — text appears before the forwarded content.
66+
67+
---
68+
69+
## Common Patterns
70+
71+
```bash
72+
# Reply from a specific alias
73+
fastmail-cli list identities
74+
fastmail-cli reply abc123 --body "On it." --from work-alias@mydomain.com
75+
76+
# Reply-all and BCC someone for records
77+
fastmail-cli reply abc123 --body "Thanks all." --all --bcc archive@mydomain.com
78+
79+
# Save a draft to review before sending
80+
fastmail-cli send --to x@y.com --subject "Careful email" --body "..." --draft
81+
82+
# Forward with context note
83+
fastmail-cli forward abc123 --to manager@company.com --body "FYI, see below."
84+
85+
# Quick reply inline
86+
fastmail-cli reply $(fastmail-cli search --from boss@co.com --unread | jq -r '.data[0].id') \
87+
--body "Done."
88+
```
89+
90+
---
91+
92+
## Notes
93+
94+
- Body is plain text only.
95+
- For HTML or complex formatting, compose in Fastmail web and use `--draft` to stage.
96+
- `--from` must match an identity returned by `list identities` — arbitrary addresses won't work.

‎.claude/skills/fastmail/contacts.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
name: fastmail/contacts
3+
description: fastmail-cli contacts — CardDAV setup, list and search contacts
4+
---
5+
6+
# fastmail-cli — Contacts
7+
8+
Contacts use CardDAV and require separate credentials from the JMAP API token.
9+
10+
## Configuration
11+
12+
```toml
13+
# ~/.config/fastmail-cli/config.toml
14+
[contacts]
15+
username = "you@fastmail.com"
16+
app_password = "your-app-password"
17+
```
18+
19+
Or via env:
20+
```bash
21+
FASTMAIL_USERNAME="you@fastmail.com"
22+
FASTMAIL_APP_PASSWORD="your-app-password"
23+
```
24+
25+
Generate an app password at: Fastmail Settings → Privacy & Security → App Passwords
26+
27+
## Commands
28+
29+
```bash
30+
# List all contacts
31+
fastmail-cli contacts list
32+
33+
# Search by name, email, or organization
34+
fastmail-cli contacts search "Alice"
35+
fastmail-cli contacts search "acme.com"
36+
fastmail-cli contacts search "ACME Corp"
37+
```
38+
39+
## Typical Patterns
40+
41+
```bash
42+
# Find email address before composing
43+
fastmail-cli contacts search "Bob Smith" | jq '.data[0].emails[0].value'
44+
45+
# Verify who someone is before replying
46+
fastmail-cli contacts search "bob@unknown.com"
47+
48+
# Find all contacts at a company
49+
fastmail-cli contacts search "bigcorp.com"
50+
```
51+
52+
## Notes
53+
54+
- `contacts list` returns all contacts — can be large. Prefer `contacts search` for targeted lookups.
55+
- Contact data includes name, emails, phone numbers, organization, and notes where available.
56+
- Read-only via CLI — create/edit contacts through Fastmail web or a CardDAV client.

0 commit comments

Comments
 (0)