Ravi email-writing

Best practices for writing high-quality emails that look professional and avoid spam filters. Reference this before composing, replying, or forwarding emails...

Security Scan

The guide is generally coherent with its email-writing purpose, but the runtime instructions assume local tools (ravi CLI and jq) and access to a user identity without declaring those requirements, which is an unexplained mismatch the user should understand before installing or running.

Purpose & Capability

Name/description (email-writing best practices) match the content, but the SKILL.md instructs using local commands like `ravi email compose` and `ravi identity list --json | jq -r '.[0].name'` while the skill metadata declares no required binaries or credentials. The instructions therefore rely on external tooling not declared in the skill manifest — an incoherence that could cause unexpected behavior or hidden dependencies.

Instruction Scope

The instructions stay focused on writing emails and deliverability guidance. However they explicitly instruct running local CLI commands that access the user's email identity and compose/send flow (via the ravi CLI) and pipe output through `jq`. That is within the functional scope but implies the agent will execute local commands and read identity data; the manifest does not call this out.

Install Mechanism

No install spec and no code files (instruction-only) — lowest-install risk. Nothing is downloaded or written to disk by the skill package itself.

Credentials

The skill declares no environment variables or credentials, and the instructions do not request secrets directly. Still, the CLI calls assume access to a local email identity/config that could indirectly expose account information when executed.

Persistence & Privilege

Skill is not always-enabled and does not request elevated or persistent privileges. Autonomous invocation is allowed by default but not combined with any other high-risk factors in the manifest.

What to consider before installing

This is primarily an instruction-only style guide that looks useful for composing emails, but before installing or invoking it: 1) Confirm you have the referenced tooling (the 'ravi' CLI and 'jq') and understand where the ravi tools come from — the skill assumes those commands exist but does not declare them. 2) Recognize that following the examples will run local CLI commands that read your email identity/config; only run them if you trust the ravi CLI. 3) If you want stricter safety, require the agent to ask before running any shell/CLI commands, or manually run the sample commands yourself. 4) If you expect plain-text email support in your environment, be aware the guide strongly prefers HTML bodies — verify compatibility with your mail system. If you can confirm the provenance of the ravi tooling and are comfortable allowing local CLI usage, the skill appears coherent; otherwise treat it with caution.

Email Writing Guide

Write emails that look like they came from a real person — not an AI. Good email hygiene improves deliverability, avoids spam filters, and gets responses.

Subject Lines

• 40-60 characters — long subjects get truncated on mobile
• Be specific — "Q3 metrics review for Acme project" beats "Update"
• No ALL CAPS — spam filters penalize this heavily
• Avoid spam triggers — "free", "act now", "limited time", "click here", "urgent", "guaranteed", "no obligation"
• Match the tone — casual for teammates, professional for external contacts

HTML Body Structure

The --body flag in ravi email compose/reply/forward accepts HTML. Always use semantic tags — never pass plain text.

Note: --subject is only used with ravi email compose. Reply and forward commands auto-derive the subject from the original message (prepending Re: or Fwd:).

Do this:

<p>Opening line that states the purpose.</p>

<p>Supporting details in a second paragraph.</p>

<ul>
  <li>Key point one</li>
  <li>Key point two</li>
</ul>

<p>Closing with a clear next step or ask.</p>

<p>Best,<br>IDENTITY_NAME</p>

Don't do this:

Plain text with no tags at all

Or this:<br><br>Using br chains<br><br>instead of paragraphs

Rules:

• Always wrap text in <p> tags
• Use <h2> for section headers (not <h1>)
• Use <ul>/<li> for lists, not dashes or asterisks
• Use <a href="...">descriptive text</a> for links — never bare URLs
• No <html>, <head>, or <body> wrapper tags — the email system adds these
• No <br> chains — use separate <p> tags instead
• Get the identity name with: ravi identity list --json | jq -r '.[0].name'

Recommended Template

Copy-paste starting point for most emails:

NAME=$(ravi identity list --json | jq -r '.[0].name')

ravi email compose \
  --to "[e-mail]" \
  --subject "Specific subject under 60 chars" \
  --body "<p>Hi Alex,</p>

<p>I'm reaching out about [specific topic]. [One sentence of context.]</p>

<p>[Core message — what you need, what you're sharing, or what you're asking.]</p>

<ul>
  <li>[Key point or action item]</li>
  <li>[Key point or action item]</li>
</ul>

<p>[Clear next step — what should the recipient do?]</p>

<p>Best,<br>$NAME</p>" --json

Tone and Style

• First person, active voice — "I'll send the report Monday" not "The report will be sent"
• Short paragraphs — 2-3 sentences max per <p> tag
• Get to the point — state your purpose in the first sentence
• End with an action item — "Can you review by Friday?" not "Let me know your thoughts"
• No filler phrases — cut "I hope this email finds you well", "Just wanted to touch base", "Per our previous conversation"
• No robotic language — cut "I am writing to inform you", "Please be advised", "Kindly note"
• Match the thread tone — if they're casual, be casual. If they're formal, be formal.

Anti-Spam Essentials

These rules help your emails land in the inbox, not spam:

• High text-to-HTML ratio — more words, fewer tags. Don't over-format.
• No link shorteners — use full URLs. Spam filters distrust bit.ly, t.co, etc.
• Max 2-3 links per email — more links = higher spam score
• No ALL CAPS — not even for emphasis. Use <strong> instead.
• No image-only emails — always include text content
• One topic per email — don't cram multiple requests into one message
• Don't repeat yourself — saying the same thing in different words triggers spam heuristics

Common Mistakes

Mistake	Why it's bad	Do this instead
Plain text in --body	Renders as one blob, no formatting	Wrap everything in <p> tags
<br><br> chains	Looks spammy, inconsistent spacing	Use separate <p> tags
"Dear Sir/Madam"	Outdated, signals mass email	Use the recipient's name or "Hi there"
Wall of text	Nobody reads long emails	Break into 2-3 short paragraphs
"Click here" links	Spam trigger, bad accessibility	<a href="...">descriptive text</a>
Empty or vague subject	Low open rates, looks like spam	Be specific: "Invoice #1234 for January"
Excessive HTML styling	High tag-to-text ratio triggers filters	Keep formatting minimal
No signature	Looks impersonal, unprofessional	Sign with identity name
"Sent by AI" disclaimers	Undermines trust, unnecessary	Just write naturally

Related Skills

• ravi-email-send — CLI commands for compose, reply, reply-all, and forward
• ravi-inbox — Read incoming email to understand what you're replying to
• ravi-identity — Get your identity name for email signatures
• ravi-feedback — Tell the Ravi team if email deliverability could be better