Message Drafts

Create rich text messages that paste perfectly into Gmail, Outlook, or convert to WhatsApp-formatted text. Fragments are written in Markdown - the build script converts to platform-specific HTML automatically.

Architecture

Claude writes              Build script assembles          Output (separate file)
name.fragment.md  --->     Markdown -> HTML                name.html
(10-30 lines)              Gmail transform (tags)          (self-contained preview
                           Outlook transform (styles)       with three body versions)
                           Inject into shell.html

The fragment is the source of truth. The assembled HTML is a derived output. Never edit the .html output directly.

Create Workflow

Draft email content in conversation
Write a .fragment.md file to data/writing/email_drafts/
Run the assembler with --serve to produce the preview HTML and launch the server

uv run .claude/skills/message/scripts/assemble.py /path/to/name.fragment.md --serve

Run with run_in_background: true. The server picks a random free port and prints the URL. The preview auto-refreshes when the HTML file changes - no manual browser refresh needed.

Edit Workflow

When editing an existing email (argument provided, or user asks to change something):

Read the small .fragment.md file
Use the Edit tool to make targeted changes
Re-run the assembler without --serve to rebuild the preview

uv run .claude/skills/message/scripts/assemble.py /path/to/name.fragment.md

The preview server is still running in the background from the create step. The assembler overwrites the HTML file atomically, and the browser auto-refreshes within 2 seconds. Do not re-launch the server on edits - the user keeps the same URL.

Fragment Format

Fragments are Markdown files with YAML frontmatter:

---
to: recipient@example.com
cc: optional@example.com
subject: Email Subject
---

Hi **Stuart**,

Here's the ~~old approach~~ new approach.

## Key Points

- First item
- Second item

> Quoted text from previous email

| Feature | Status |
|---------|--------|
| Auth    | Done   |

Inline `code` and [a link](https://example.com).

Cheers,
Henrik

Frontmatter Fields

Field	Required	Notes
`to`	Yes	Comma-separated recipients
`subject`	Yes	Email subject line
`cc`	No	Hidden in preview if empty
`bcc`	No	Hidden in preview if empty

Formatting Reference

Standard Markdown maps to platform-specific HTML automatically:

What you want	Write in Markdown
Bold	`bold`
Italic	`italic`
Strikethrough	`~~strikethrough~~`
Heading	`## Heading`
Bullet list	`- item`
Numbered list	`1. item`
Blockquote	`> quoted text`
Inline code	`code`
Code block	triple backticks
Link	`[text](url)`
Table	`

For features not in standard Markdown, embed HTML directly (it passes through unchanged):

What you want	Embed as HTML
Custom colour	`<span style="color: #c0392b;">red text</span>`
Large text	`<font size="4">larger text</font>`
Underline	`<u>underlined</u>`
Indent	`<blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;">indented</blockquote>`

Example: User Asks for Colour and Strikethrough

User: "Write an email to Stuart. Strikethrough '$5000' and make his name red."

Claude writes .fragment.md:

---
to: akumanostuart@gmail.com
subject: Pricing Update
---

Hi <span style="color: #c0392b;">Stuart</span>,

The old pricing was ~~$5000~~ but the new rate is $3000.

Cheers,
Henrik

File Naming

data/writing/email_drafts/YYYY-MM-DD_recipient_subject.fragment.md   <- source
data/writing/email_drafts/YYYY-MM-DD_recipient_subject.html          <- assembled output

Examples:

2026-02-12_veronika_audit-proposal.fragment.md
2026-02-12_danielle_project-update.fragment.md

Platform Transforms

The build script produces three HTML versions from a single Markdown source:

Gmail (tag transform): Converts semantic HTML to Gmail-native elements.  becomes <div>,  becomes ,  becomes , headings become  with . Container gets Arial 13px. No custom colours added - only platform defaults.

Outlook (style injection): Adds inline styles to every element for Word's rendering engine. Aptos/Calibri 11pt, explicit color: #000000 on every text element, mso-line-height-rule for spacing control. No custom colours added - only platform defaults.

WhatsApp (text conversion): Strips HTML and converts to WhatsApp markdown - *bold*, _italic_, ~strikethrough~. Tables become pipe-separated text.

User-specified inline styles (colours, font sizes) are preserved through all transforms.

Preview

The assembled HTML has a Gmail/Outlook/WhatsApp mode toggle:

Gmail mode: Gmail-native HTML with Arial 13px container, Gmail action buttons (Compose in Gmail, Open Gmail Inbox, Copy for Gmail)
Outlook mode: Outlook-native HTML with full inline styles, Outlook action button (Copy for Outlook)
WhatsApp mode: Converts to WhatsApp-compatible plain text. Action buttons: Copy for WhatsApp, Send via WhatsApp

Instruct user:

Click the URL printed by the server
Select Gmail, Outlook, or WhatsApp mode
Review the email preview
Use the action buttons for their chosen client

Backward Compatibility

Legacy .fragment.html files still work. The assembler detects the extension and uses the appropriate parser. For HTML fragments, the same body is used for all three platform views (matching previous behaviour).

Structure

Follow this order in every email:

Lead with the point - the request, update, instruction, or information the recipient needs to act on. This is why they opened the email.
Supporting detail - context, logistics, or reference material that supports the lead.
Warm close - any personal, relational, or appreciative content goes at the end, just before the sign-off. Gratitude, compliments, looking-forward sentiments, and rapport-building belong here - never at the top.

The recipient should know what the email is about within the first two lines. Warmth is the exit feeling, not the entrance.

Tone

Write naturally, as a human would compose
Avoid repetitive language from previous emails in the thread
Keep prose flowing, not overly structured
Match the recipient's formality level
Use British English spelling (colour, analyse, organise, behaviour, centre)

Henrik's Default Details

Use these when composing emails on Henrik's behalf:

Purpose	Email
Primary / From address	admin@henriksoderlund.com
Google platform access requests (GA4, GTM, Google Ads, Search Console, etc.)	admin@henriksoderlund.com

Sign-off block:

Henrik Soederlund
Independent Digital Consultant
admin@henriksoderlund.com

References

references/outlook-formatting.md - Outlook element styles and colour palette reference
references/formatting-rules.md - Gmail native HTML element reference

After Preview

Once the user has the preview URL, ask whether they'd like to run the humaniser skill on the message to remove any AI writing patterns before sending. Example prompt: "Would you like me to run the humaniser skill on this draft to make it sound more natural?"

Post-Draft Actions

After saving a draft, prompt Henrik: "Log this to the client comms log?" If yes, write the entry to data/consulting/clients/[slug]/comms/_comms-log.json via inline Python or the Edit tool (manage_comms.py is read-only - no --add flag).