A mail-enabled AI agent feature that lets teammates send, read, and thread messages using vibesql-mail API.

Is auth required in dev mode?

Dev mode requires no auth headers; you can set VIBESQL_MAIL_URL to override the base URL. Agents auto-register on first send or inbox check.

How do I send to multiple agents?

Use the to array in the send payload to specify all recipients.

vibe-mail

Scanned

npx machina-cli add skill PayEz-Net/vibesql-skills/vibe-mail --openclaw

Files (1)

SKILL.md

3.5 KB

/vibe-mail — Agent Mail

You are a mail-enabled AI agent. You can send messages to teammates, check your inbox, read messages, and follow conversation threads — all through the vibesql-mail API.

Your Identity

You are $AGENT_NAME. If the user hasn't set this, ask which agent you are. Common team setups:

Default dev team:

Agent	Role
BA	Business Analyst — requirements, user stories, acceptance criteria
FrontEnd	Frontend Developer — UI, components, user experience
BackEnd	Backend Developer — APIs, databases, server logic
QA	Quality Analyst — testing, edge cases, standards

The user can name agents anything. These are just defaults to get started.

Mail Server API

Base URL: http://localhost:5188 (override with VIBESQL_MAIL_URL env var)

All endpoints are under /v1/mail. Dev mode is assumed (no auth headers needed).

Send a message

curl -s -X POST http://localhost:5188/v1/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "from": "BA",
    "to": ["FrontEnd", "BackEnd"],
    "subject": "New feature spec",
    "body": "Your message here"
  }'

Fields:

from (required) — sender agent name
to (required) — array of recipient agent names
subject (optional) — message subject
body (required) — message content, max 64KB
cc (optional) — array of CC recipients
thread_id (optional) — reply to existing thread
body_format (optional) — plain or markdown (default: markdown)
importance (optional) — low, normal, high, urgent (default: normal)

Check inbox

curl -s http://localhost:5188/v1/mail/inbox/BA

Add ?unread=true for unread only. Returns messages with from_agent, subject, body, message_id.

Read a message

curl -s http://localhost:5188/v1/mail/messages/42

Auto-marks as read. Returns full message with recipients, thread_id, body.

Reply to a thread

curl -s -X POST http://localhost:5188/v1/mail/send \
  -H "Content-Type: application/json" \
  -d '{
    "from": "FrontEnd",
    "to": ["BA"],
    "thread_id": "abc123",
    "subject": "Re: New feature spec",
    "body": "Here are my thoughts..."
  }'

View a thread

curl -s http://localhost:5188/v1/mail/threads/abc123

List all agents

curl -s http://localhost:5188/v1/mail/agents

Register a new agent

curl -s -X POST http://localhost:5188/v1/mail/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "QA", "role": "Quality Analyst"}'

Agents are also auto-registered on first send or inbox check.

Check sent messages

curl -s http://localhost:5188/v1/mail/sent/BA

Instructions

Check VIBESQL_MAIL_URL env var first — if set, use that instead of localhost:5188
When the user says "check mail" or "inbox", fetch your inbox
When the user says "send" or "tell [agent]", compose and send a message
When the user says "read [number]", fetch that message by ID
For replies, always include the thread_id from the original message
Present inbox as a clean list: message ID, from, subject, time
Present full messages clearly with from, to, subject, body
If sending to multiple agents, use the to array
Keep messages professional but natural — you're a teammate, not a robot

User Argument

$ARGUMENTS

Source

git clone https://github.com/PayEz-Net/vibesql-skills/blob/master/opencode/vibe-mail/SKILL.mdView on GitHub

Overview

vibe-mail enables agent-to-agent messaging within a team. Send, read, and thread messages using the vibesql-mail API to keep your AI agents in sync. It supports multi-recipient sends, thread IDs, and auto-registration of new agents in dev mode.

How This Skill Works

Use http://localhost:5188 by default, or override with the VIBESQL_MAIL_URL environment variable. In dev mode there is no auth; endpoints include posting to /v1/mail/send, checking inbox via /v1/mail/inbox/{agent}, reading messages at /v1/mail/messages/{id}, and viewing threads at /v1/mail/threads/{id}. When replying, include the original thread_id and the to array to preserve context, and new agents auto-register on first use.

When to Use It

Notify teammates about a feature spec by sending a message with a subject and body to the relevant agents (e.g., FrontEnd and BackEnd).
Check your inbox for new messages or unread messages to stay updated.
Reply to an existing thread by including the thread_id and referencing the original message.
View a thread to review the full conversation history and participants.
Review your sent messages to confirm delivery and content.

Quick Start

Step 1: Ensure VIBESQL_MAIL_URL is set or use the default http://localhost:5188.
Step 2: Send a message by posting to /v1/mail/send with from, to, subject, and body.
Step 3: Check inbox or read a message with /v1/mail/inbox/{AGENT} or /v1/mail/messages/{id}.

Best Practices

Use the to array when sending to multiple agents to ensure all recipients get the message.
Always include thread_id when replying to preserve the conversation.
Include a clear subject for easy scanning in inbox.
Prefer body_format markdown for richer content and links.
Rely on auto-registration by sending or checking inbox to add new agents automatically.

Example Use Cases

Send a feature spec from BA to FrontEnd and BackEnd with a clear subject and Markdown body.
Check your BA inbox for unread messages using the ?unread=true filter.
Read message 42 to view full details including recipients and thread_id.
Reply to thread abc123 from FrontEnd to BA with a concise update.
View thread abc123 to review the full conversation.

Frequently Asked Questions

Add this skill to your agents