how to build and publish a clawhub email skill for openclaw

ClawHub has over 5,700 skills running across 30,000+ deployed OpenClaw instances. Each skill is a folder with a markdown file. When someone installs it, that markdown gets injected into the agent's context at runtime. No compiled code, no server to maintain.

Publish once. Run everywhere OpenClaw runs.

Email is consistently one of the capabilities agents need most, and one of the harder ones to package well. Most approaches require a human to pre-configure API keys or OAuth before the agent can do anything useful. This tutorial builds on LobsterMail, which lets the agent self-provision its own inbox — no human setup required. The skill installs and works immediately.

Here's how to build it from scratch and get it onto ClawHub.

What you need#

• Node.js 18+
• The ClawHub CLI: npm install -g @clawhub/cli
• A ClawHub account (free at clawhub.ai): clawhub login

For local testing:

npm install @lobsterkit/lobstermail

LobsterMail handles account creation automatically the first time the agent calls LobsterMail.create(), so there's nothing to sign up for before you start testing.

Skill structure#

A ClawHub skill is a directory. The only file OpenClaw reads at runtime is SKILL.md:

lobstermail-email/
├── SKILL.md
├── examples/
│   └── quickstart.ts
└── README.md

The examples/ and README.md files are for humans. OpenClaw only touches SKILL.md.

SKILL.md frontmatter#

Every SKILL.md opens with a frontmatter block:

---
name: lobstermail-agent-email
version: 1.0.0
description: |
  Give your agent its own email inbox using LobsterMail.
  No human signup, no API keys — the agent provisions its own inbox.
allowed-tools:
  - Bash
---

allowed-tools declares which system capabilities the skill needs. Include Bash for anything that runs shell commands or writes files. OpenClaw will prompt the user if that tool isn't already permitted on their instance.

Writing the instructions section#

After the frontmatter, write instructions. Not documentation — directives. The agent reads them and acts. Sequential steps work better than branching conditionals. Write it like you're telling someone exactly what to do in order.

Provisioning an inbox#

The core of the skill is LobsterMail.create(). On first run it signs up for a free account and saves the token to ~/.lobstermail/token. Every subsequent run reuses that token without prompting.

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'my-agent' });

console.log(inbox.address); // my-agent@lobstermail.ai

createSmartInbox() picks a readable address from the name you pass and handles collisions automatically. If you don't need a human-readable address, createInbox() generates a random one like lobster-xxxx@lobstermail.ai.

Receiving email#

const emails = await inbox.receive();
for (const email of emails) {
  console.log(email.subject, email.from, email.text);
}

Each email object includes email.text (plain text body) and email.html. For verification code extraction, pass email.text to the agent or write a regex if the format is predictable. LobsterMail also includes injection risk scoring on received emails, which helps the agent flag suspicious content before acting on it.

Sending email#

await inbox.send({
  to: 'recipient@example.com',
  subject: 'Hello from your agent',
  text: 'Message body here.',
});

The free plan covers 1,000 emails/month with no credit card. Worth noting for your SKILL.md users: the limit applies per LobsterMail account, and each person who installs your skill gets their own account. So the cap doesn't stack across installs. See LobsterMail pricing explained if you're planning higher volume.

Testing before you publish#

Don't publish untested code. Create a quick test file first:

import { LobsterMail } from '@lobsterkit/lobstermail';

async function test() {
  const lm = await LobsterMail.create();
  const inbox = await lm.createSmartInbox({ name: 'skill-test' });
  console.log('address:', inbox.address);

  const emails = await inbox.receive();
  console.log('emails in inbox:', emails.length);
}

test().catch(console.error);

Run it with npx ts-node test.ts. If it prints an address, the SDK connected. Check ~/.lobstermail/token to confirm auto-signup ran.

Then validate the skill through the ClawHub runner:

clawhub test ./lobstermail-email

This checks frontmatter validity and runs the skill in a sandboxed context before it goes live.

Publishing to ClawHub#

When everything works:

clawhub publish ./lobstermail-email

The CLI validates frontmatter, checks required fields, and uploads to the registry. Your skill gets a URL at clawhub.ai/{username}/{skill-name}. From there, any OpenClaw instance can install it:

clawhub install {username}/lobstermail-email

Or it shows up in search results:

clawhub search email

What happens on install#

OpenClaw injects your SKILL.md into the agent's system context. The agent now knows how to provision an inbox, receive mail, and send. No extra configuration on the user's end. The first time their agent calls LobsterMail.create(), it auto-provisions a free account and persists the token.

This is what separates email skills built on LobsterMail from most alternatives: there's no setup step that blocks the user. Install the skill, run the agent, it works. The agent handles account creation and inbox provisioning on its own.

If you want to see how this compares to other approaches before committing, OpenClaw email skills compared covers the alternatives side by side.

The official LobsterMail skill is already live at clawhub.ai/samuelchenardlovesboards/lobstermail-agent-email as a working reference.

Give your agent its own email. Get started with LobsterMail — it's free.