How to Deploy Custom Zeroclaw Skills, or Setting up E-mail AI Agent

Tools

• OPENCLAW • ZEROCLAW • AI AGENTS • HIMALAYA • LLM • AI •

Writing and Deploying Custom ZeroClaw Skills can be tricky, especially if you want your AI agent to work on e-mails. Here is what actually works, or a practical walkthrough using a Himalaya e-mail skill on headless Debian with ZeroClaw. In March 2026 the cleanest security architecture for an AI agent is to host it in sandboxed Headless Debian VM, using ZeroClaw framework.

What a Skill Actually Is?

ZeroClaw skills are directories containing at most two files. A SKILL.md injects instructions into the agent’s context — it’s documentation the agent reads. A SKILL.toml registers an executable tool the agent can actually invoke. You need both for a working tool. SKILL.md alone gives the agent knowledge but nothing to run.

WASM modules are a separate, opt-in feature. For wrapping an existing CLI binary like himalaya, plain SKILL.toml + SKILL.md is all you need.

~/email/
├── SKILL.toml   ← registers the executable tool
└── SKILL.md     ← agent instructions & command reference

SKILL.toml — The Tool Definition

The [[tools]] block is what creates the callable tool. The description field is critical — it’s what the agent reads when deciding how to translate natural language into a command. Be explicit and provide exact syntax examples. Without them, the agent will hallucinate plausible-sounding but wrong subcommands (it will guess mail ls instead of envelope list).

~/email/SKILL.toml

[skill]
name = "email"
description = "Himalaya is a CLI email client for managing emails from the terminal via IMAP/SMTP."
version = "0.1.0"
 
[[tools]]
name = "email"
description = """
Run himalaya CLI commands. Always use exact himalaya syntax:
- List inbox:            himalaya envelope list
- List folder:           himalaya envelope list --folder "Sent"
- Read email:            himalaya message read <id>
- Send email:            himalaya message write -H "To:x@y.com" -H "Subject:Z" "body"
- Reply:                 himalaya message reply <id>
- Reply all:             himalaya message reply <id> --all
- Forward:               himalaya message forward <id>
- Move:                  himalaya message move <id> "Folder"
- Delete:                himalaya message delete <id>
- Search:                himalaya envelope list from x@y.com subject meeting
- JSON output:           append --output json to any envelope command
- Download attachments:  himalaya attachment download <id>
Never invent subcommands. Always use 'envelope list' not 'mail ls' or similar.
"""
kind = "shell"
command = "himalaya"

SKILL.md — The Agent Reference

The SKILL.md is loaded into the agent’s context at startup. Keep it focused on usage — no installation instructions, no config setup, just the commands an agent needs day-to-day. The first non-heading line becomes the skill description shown in zeroclaw skills list.

~/email/SKILL.md (excerpt)

# Himalaya Email CLI
 
Himalaya is a CLI email client for managing emails from the terminal via IMAP/SMTP.
 
## Tips
- Message IDs are relative to the current folder — re-list after switching folders.
- Use --output json for structured output on any envelope command.
 
## Listing & Searching
    himalaya envelope list
    himalaya envelope list --folder "Sent"
    himalaya envelope list from john@example.com subject meeting
 
## Reading
    himalaya message read 42
 
## Writing & Sending
    himalaya message write -H "To:x@example.com" -H "Subject:Hello" "body"

Installing and Removing the Skill

Install

zeroclaw skills install ~/email

ZeroClaw copies the directory into ~/.zeroclaw/workspace/skills/email/, runs a security audit (rejects symlinks, files over 512 KB, shell chaining operators in commands), and registers the skill. On success:

✓ Skill installed and audited: ~/.zeroclaw/workspace/skills/email (3 files scanned)
  Security audit completed successfully.

Reinstalling

ZeroClaw will refuse to overwrite an existing skill. Remove it first before reinstalling after edits.

Remove

zeroclaw skill remove email

Or directly:

rm -rf ~/.zeroclaw/workspace/skills/email

Verify

zeroclaw skills list

You should see email v0.1.0 — Himalaya is a CLI email client... in the output. Skills are auto-loaded on agent startup — no restart needed after a fresh install.

Using It in Interactive Mode

zeroclaw agent

When the agent wants to run a command, it will prompt for confirmation. Use A (Always) to allow all email tool calls for the session:

🔧 Agent wants to execute: email.email
   command: envelope list
   [Y]es / [N]o / [A]lways for email.email: A

Example prompts that work well:

> Check my inbox and summarize unread emails
> Find emails from john@example.com about the project
> Reply to email 15 and say I'll review it by Friday
> Move email 23 to Archive
> Download attachments from email 31 to ~/Downloads

Natural language tip

If the agent maps a natural language request to the wrong command, be more explicit: «run himalaya envelope list with json output» is more reliable than «list my emails» until the tool description is tuned well.

Setting Up Himalaya on Headless Debian

Install from the precompiled binary — do not use apt, it does not exist yet. And do not compile, you can run out of resources on your VM or VPS. The script below detects your architecture, downloads the correct binary from the official releases, writes a Mailo config, and verifies the connection.

#!/usr/bin/env bash
set -euo pipefail
echo "=== Himalaya + Mailo CLI Setup (Precompiled) ==="
 
read -rp  "Enter your Mailo email address: " MAILO_EMAIL
read -rsp "Enter your Mailo password: "      MAILO_PASS
echo
 
echo "Installing dependencies..."
sudo apt update && sudo apt install -y curl tar
 
SYSTEM=$(uname -s | tr '[:upper:]' '[:lower:]')
MACHINE=$(uname -m | tr '[:upper:]' '[:lower:]')
case $MACHINE in
  x86_64)          TARGET=x86_64-linux  ;;
  aarch64|arm64)   TARGET=aarch64-linux ;;
  armv7l)          TARGET=armv7l-linux  ;;
  *)               echo "Unsupported: $MACHINE"; exit 1 ;;
esac
 
TMPDIR=$(mktemp -d); trap "rm -rf $TMPDIR" EXIT
curl -sLo "$TMPDIR/himalaya.tgz" \
  "https://github.com/pimalaya/himalaya/releases/latest/download/himalaya.$TARGET.tgz"
mkdir -p "$HOME/.local/bin"
tar -xzf "$TMPDIR/himalaya.tgz" -C "$TMPDIR"
cp -f "$TMPDIR/himalaya" "$HOME/.local/bin/himalaya"
 
grep -q '.local/bin' "$HOME/.bashrc" || \
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"
export PATH="$HOME/.local/bin:$PATH"
echo "Installed: $(himalaya --version)"
 
CONFIG_DIR="$HOME/.config/himalaya"
mkdir -p "$CONFIG_DIR"
cat > "$CONFIG_DIR/config.toml" <<EOF
[accounts.mailo]
default = true
email = "$MAILO_EMAIL"
backend.type = "imap"
backend.host = "mail.mailo.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "$MAILO_EMAIL"
backend.auth.type = "password"
backend.auth.raw = "$MAILO_PASS"
message.send.backend.type = "smtp"
message.send.backend.host = "mail.mailo.com"
message.send.backend.port = 465
message.send.backend.encryption.type = "tls"
message.send.backend.login = "$MAILO_EMAIL"
message.send.backend.auth.type = "password"
message.send.backend.auth.raw = "$MAILO_PASS"
EOF
 
echo "Testing connection..."
himalaya folder list > /dev/null 2>&1 \
  && echo "✔ Connected" \
  || { echo "✖ Failed. Run: himalaya --debug folder list"; exit 1; }
echo "Done. Run: himalaya envelope list"

ℹ Upgrade password storage later!

The script uses backend.auth.raw to get you running quickly. For production use, replace it with:

backend.auth.cmd = "pass show mailo"

and store credentials in the Unix pass password manager.

Security: Use a Dedicated Agent Email

🔒 Critical — Read This

Never connect an AI agent to your personal email. An agent with inbox access can read, send, forward, and delete on your behalf. One confused instruction or prompt injection in a received email is enough to cause serious damage.

Use a completely separate, dedicated address created specifically for the agent.

Why not Gmail? Gmail requires OAuth2, which adds significant complexity and requires app registration. For an agent-controlled mailbox you want simple traditional authentication — a standard IMAP/SMTP login with a username and password.

Mailo.com is a good fit: it’s an EU-compliant provider that supports standard IMAP/SMTP with password auth, no OAuth dance required. Create a free account, use it only for the agent, and treat it as disposable.

The full setup for this guide runs inside a headless Debian VM with ZeroClaw sandboxed inside it — adding a layer of isolation between the agent and your host system. This is the recommended topology:

VM → ZeroClaw sandbox → agent → CLI tool → dedicated mailbox

Summary

1. Create ~/email/SKILL.toml with a [[tools]] block pointing to himalaya, with explicit command examples in the description.
2. Create ~/email/SKILL.md with day-to-day command reference for the agent.
3. Install: zeroclaw skills install ~/email
4. To update: zeroclaw skill remove email → edit files → reinstall.
5. Verify with zeroclaw skills list, then test in zeroclaw agent.
6. Use a dedicated Mailo address — never your personal email.

For questions about agent deployment, agentic CLI tools development, or security assessments for your specific AI workflow, get in touch.

How to Securely Deploy AI Agents in Business

Kako odpreti e-račun (XML) in ga pretvoriti v PDF s QR kodo za plačilo, brezplačno in brez namestitve

EDIFACT Viewer: How to Read Any EDI Message Instantly

View any XML File with Universal XML Viewer, for Humans and AI

HideGPT, AI Detector and Em dash remover