HERA Mail

Internal email system for HERA agents to send, receive, read, and manage direct messages with optional file attachments.

Security Scan

The skill's code and docs mostly match its stated purpose (a local agent-to-agent mail system), but there are multiple inconsistencies and a few risky design choices you should understand before installing.

Purpose & Capability

Name/description align with included scripts: list_inbox.py, read_mail.py, send_mail.py implement a local file-based mail system. The skill only performs local file I/O (read/write/copy) and does not request network access or external credentials, which is coherent with an internal mail tool.

Instruction Scope

SKILL.md instructs the agent to run the bundled scripts and describes expected directory structures, which matches the scripts. However the SKILL.md examples use placeholders like {baseDir} while the scripts hardcode an absolute base_dir (/Users/zhaoruiwu/.openclaw/workspace/hera-agents). SKILL.md also contains a metadata block requesting always: true (force inclusion). The send_mail script copies arbitrary attachment paths provided on the command line — that behavior is expected for attachments but means the skill can read any local file path you pass it (potential data access risk if misused). The docs also suggest chmod on a specific user path, leaking a developer username and encouraging use of that path.

Install Mechanism

Instruction-only skill (no install spec). No remote downloads or package installs are performed by the skill bundle itself, which limits install-time risk.

Credentials

The skill requests no environment variables or external credentials and the scripts do not read env vars. However, the scripts hardcode an absolute path under a developer home (/Users/zhaoruiwu/...), which is inflexible and reveals developer-specific context. Also, because send_mail copies arbitrary provided file paths, giving this skill access to run with your agent effectively allows it to read files you point it to.

Persistence & Privilege

Registry metadata shown to you lists always: false, but SKILL.md contains an openclaw.metadata block with "always": true. That discrepancy is important: if the platform honors the SKILL.md metadata and forces this skill always-on, it would be included in every agent run. For a file-accessing communication skill, forced always-on status increases risk and should be justified explicitly. The skill does not modify other skills or system-wide configs, but the always:true entry is a red flag unless explained.

What to consider before installing

This skill appears to implement a simple local mail system and contains no network exfiltration code, but there are coherence and risk concerns you should resolve before installing: 1) Ask the maintainer why SKILL.md sets openclaw.metadata.always = true while the registry shows always = false; never enable always:true unless you trust the source. 2) Request that the hardcoded base path (/Users/zhaoruiwu/...) be replaced with a configurable baseDir or environment variable so it won't accidentally read/write in an unexpected home directory. 3) Be aware send_mail will copy any file path you provide — avoid passing sensitive local file paths to the script and consider restricting allowable attachment directories. 4) If you proceed, run the skill in a sandboxed environment first and review/modify the scripts to use a safe, explicit data directory. If the skill's source or maintainer cannot justify the always:true setting and the hardcoded paths, treat it with caution or do not install.

HERA Mail System

Internal email system for agent-to-agent communication within the HERA research assistant framework.

Quick Start

Check Inbox

python3 {baseDir}/scripts/list_inbox.py <agent-name>

Read a Message

python3 {baseDir}/scripts/read_mail.py <agent-name> <mail-file.md>

Send a Message

python3 {baseDir}/scripts/send_mail.py <from-agent> <to-agent> "<subject>" <attachment-paths...>

Agent Names

Agent	Name for Scripts
Group Leader	group-leader
Rough Reader	rough-reader
Intensive Reader	intensive-reader
Code Guider	code-guider
Coordinator 1	coordinator-1
Coordinator 2	coordinator-2
Rough Checker 1	rough-checker-1
Rough Checker 2	rough-checker-2
Report Writer	report-writer

Email Format

[FROM: agent-name]
[TO: agent-name]
[TIMESTAMP: YYYY-MM-DD HH:MM:SS]
[MAIL-ID: unique-id]
[SUBJECT: subject text]
[STATUS: unread]

---

Message body content here.
No formal greetings needed - be direct and concise.

---
[END]

Attachments

Attachments are stored in:

hera-agents/<recipient>/inbox/attachments/<mail-id>/<files>

Supported: PDFs, images, data files, code, any file type.

Workflows

Workflow 1: Check and Read Messages

1. List inbox: list_inbox.py <agent-name>
2. Identify unread messages (marked with [○])
3. Read specific message: read_mail.py <agent-name> <file.md>
4. Message automatically marked as read

Workflow 2: Send Message with Attachment

# Send paper to Rough Reader
python3 send_mail.py group-leader rough-reader "Review this paper" /path/to/paper.pdf

# Send data visualization to Report Writer
python3 send_mail.py intensive-reader report-writer "Analysis results" /path/to/figure.png /path/to/data.csv

Workflow 3: Interactive Send (with body from stdin)

cat <<EOF | python3 send_mail.py coordinator-1 code-guider "Code review needed"
Please review the attached code for:
1. Performance issues
2. Memory leaks
3. Best practices

Deadline: EOD
EOF

Message Types

Type	Sender	Recipient	Purpose
Task Assignment	Group Leader	Any agent	Assign new work
Work Submission	Any agent	Coordinator/Leader	Submit completed work
Review Request	Any agent	Rough Checker	Request quality check
Information Request	Any agent	Reader agents	Request analysis
Data Transfer	Any agent	Any agent	Share files/data

Best Practices

1. Be direct - No formal greetings, get straight to the point
2. Clear subjects - Subject line should summarize the task/request
3. Attach relevant files - Include papers, data, code as needed
4. Check inbox regularly - Agents should monitor their inbox
5. Mark important messages - Use mail ID for reference in future comms

Directory Structure

hera-agents/
├── <agent-name>/
│   ├── inbox/           # Received messages
│   │   ├── *.md         # Mail files
│   │   ├── *.read       # Read markers
│   │   └── attachments/ # Attached files per mail
│   └── outbox/          # Sent message copies
│       └── *.md
└── skills/hera-mail/
    ├── scripts/
    │   ├── list_inbox.py
    │   ├── read_mail.py
    │   └── send_mail.py
    └── references/

Examples

Example 1: Group Leader assigns task to Rough Reader

cat <<EOF | python3 send_mail.py group-leader rough-reader "Scan arXiv papers on quantum error correction"
Priority: High
Scope: Last 6 months
Focus: Surface codes, LDPC codes

Deliverable: List of top 10 relevant papers with abstracts
Deadline: 2 hours
EOF

Example 2: Intensive Reader sends analysis to Report Writer

python3 send_mail.py intensive-reader report-writer "Analysis complete: Quantum Error Correction" \
    /workspace/analysis/summary.md \
    /workspace/analysis/key_findings.csv \
    /workspace/figures/error_rates.png

Example 3: Coordinator requests quality check

python3 send_mail.py coordinator-1 rough-checker-1 "QC needed: Literature review draft" \
    /workspace/drafts/lit_review_v1.md

Troubleshooting

Inbox not found: Ensure agent directory exists under hera-agents/

Mail not delivered: Check recipient agent name is correct

Attachment missing: Verify file path is absolute and file exists

Permission denied: Ensure scripts are executable:

chmod +x /Users/zhaoruiwu/.openclaw/workspace/hera-agents/skills/hera-mail/scripts/*.py