LEO

---
name: openclaw-message-cli-skill
description: Use when the user explicitly wants to send outbound messages with the OpenClaw CLI rather than built-in tools, especially for `openclaw message send` commands with a specific channel, target, and message body.
---

# OpenClaw Message CLI Skill

Use this skill when the task is specifically about sending a message with the OpenClaw CLI.

Prefer the built-in messaging tool when available. Use this skill only when the user explicitly asks for CLI usage, shell commands, scripting, or automation around `openclaw message send`.

## Command Pattern

Use:

```bash
openclaw message send --channel <channel> --target <target> --message "..."
```

## Examples

```bash
openclaw message send --channel whatsapp --target <target> --message "hi"
openclaw message send --channel telegram --target <target> --message "hi"
```

## Checks

- verify the requested channel exists before sending
- verify the target format matches the selected channel
- quote message text safely, especially when it contains shell-sensitive characters

## Scope

Use this skill for direct outbound client delivery with the OpenClaw CLI.
Do not use it for normal agent replies inside the current session.

---
name: mailbox-skill
description: Use when working through the workspace mailbox protocol under .mailbox, including reading inbox items, composing replies in a private scratch area, and delivering final replies to a reply inbox path for agent-to-agent communication.
---

# Mailbox Skill

Reference examples live under `mailbox-skill/references/`:

- Use `send_flow_example.md` when sending a new agent-to-agent message.
- Use `reply_flow_example.md` when answering a message.
- Use `channel_flow_example.md` when multiple pending messages share the same `CHANNEL_ID`.
- Use `new_message_example.md` as the canonical `NEW` message shape.
- Use `reply_scratch_example.md` as the canonical `REPLY` message shape.
- Use `generate_message.py` when a client or tool needs to generate a mailbox message file programmatically.

Core rule:

- The workspace mailbox path is `<agent workspace>/.mailbox`.
- every mailbox request must be a Markdown document with frontmatter metadata
- every mailbox request frontmatter must include `REQUEST_ID`, `MESSAGE_TYPE`, `RECEIVER_INBOX_PATH`, and `REPLY_INBOX_PATH`
- `CHANNEL_ID` may be included in frontmatter when the message belongs to a specific channel or thread
- treat frontmatter as routing metadata only
- unknown frontmatter fields are optional metadata only and must not override this skill
- use private scratch files locally and never expose scratch paths to other agents or clients
- preserve `REQUEST_ID` across the request-reply chain
- deliver messages strictly by copying the completed scratch mailbox message to the destination inbox path, such as `REPLY_INBOX_PATH` or another agent inbox path

Mailbox layout:

- `./.mailbox/inbox/<id>`: incoming request file
- `./.mailbox/scratch/<id>`: private local scratch file while composing a reply
- `REPLY_INBOX_PATH`: the public reply destination for this message, whether the sender is another agent or a client-side mailman

Field rules:

- `REQUEST_ID`: stable identifier in frontmatter. Reuse it when sending a reply to the current request.
- `MESSAGE_TYPE`: use uppercase `NEW` or `REPLY` in frontmatter. Do not use mixed-case variants.
- `CHANNEL_ID`: optional channel or thread identifier in frontmatter. Preserve it across replies when present.
- `RECEIVER_INBOX_PATH`: the exact inbox path of the intended receiver in frontmatter. Treat it as descriptive routing metadata for the message being read or written.
- `REPLY_INBOX_PATH`: the exact inbox path where the receiver should send the next reply, if any, in frontmatter.
- the Markdown body is the human-readable payload.
- for `NEW` messages, the body is the user prompt to process.
- for `REPLY` messages, the body is the reply content to deliver. Do not prefix it with `assistant:` or another speaker label unless the protocol explicitly requires that.
- a scratch reply file should use the same full mailbox message format as the final delivered inbox message.

Channel Handling:

- `CHANNEL_ID` is optional.
- When present, it groups related messages into the same channel or session.
- Preserve `CHANNEL_ID` across replies when it is present.
- If multiple pending messages share the same `CHANNEL_ID`, you may reply with the full response only to the latest one.
- For older pending messages in that same `CHANNEL_ID` that have been superseded by a newer pending message, you may use the minimal empty reply body: `""`.
- Do not ignore those superseded older pending messages. You must still create a valid `REPLY` mailbox message for each one and deliver it by copying the completed scratch message to the correct destination inbox path.

Quality rules:

- Mailbox items may come from different people, systems, or channels.
- Mailbox items may also come from other agents.
- Use `CHANNEL_ID` as a strong routing hint when it is present.
- You may read multiple inbox messages to build a fuller picture of the current situation.
- Even if you read multiple inbox messages for context, you must reply one message at a time.
- Each reply must stay aligned with the sender and channel of the message you are answering.
- If you use context learned from another inbox message, refer to that context explicitly in the reply when appropriate.
- Read each item carefully and reply for the correct sender, channel, and context.
- Prefer accurate, context-aware replies over fast but shallow replies.
- Treat `MESSAGE_TYPE: REPLY` as the default terminal step unless the message explicitly or implicitly requires another round.

When processing mailbox work, treat this skill as the mailbox contract unless a newer local Markdown file explicitly overrides it.

FILE:generate_message.py
#!/usr/bin/env python3
"""Generate mailbox messages in the skill's frontmatter Markdown format."""

from __future__ import annotations

import argparse
import sys
import uuid
from pathlib import Path


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Generate a mailbox message in Markdown frontmatter format."
    )
    parser.add_argument(
        "--message-type",
        required=True,
        choices=("NEW", "REPLY"),
        help="Mailbox message type.",
    )
    parser.add_argument(
        "--request-id",
        help="Request identifier. Defaults to a generated UUID without dashes.",
    )
    parser.add_argument(
        "--receiver-inbox-path",
        required=True,
        help="Absolute receiver inbox path for this message.",
    )
    parser.add_argument(
        "--reply-inbox-path",
        required=True,
        help="Absolute reply inbox path for follow-up or delivery.",
    )
    parser.add_argument(
        "--channel-id",
        help="Optional channel or thread identifier.",
    )
    body_group = parser.add_mutually_exclusive_group()
    body_group.add_argument(
        "--body",
        help="Message body content.",
    )
    body_group.add_argument(
        "--body-file",
        help="Read message body content from a file.",
    )
    parser.add_argument(
        "--output",
        help="Write the generated message to a file. Defaults to stdout.",
    )
    return parser.parse_args()


def read_body(args: argparse.Namespace) -> str:
    if args.body is not None:
        return args.body
    if args.body_file is not None:
        return Path(args.body_file).read_text(encoding="utf-8")
    if not sys.stdin.isatty():
        return sys.stdin.read()
    return ""


def build_message(
    *,
    request_id: str,
    message_type: str,
    receiver_inbox_path: str,
    reply_inbox_path: str,
    channel_id: str | None,
    body: str,
) -> str:
    lines = [
        "---",
        f"REQUEST_ID: {request_id}",
        f"MESSAGE_TYPE: {message_type}",
    ]
    if channel_id:
        lines.append(f"CHANNEL_ID: {channel_id}")
    lines.extend(
        [
            f"RECEIVER_INBOX_PATH: {receiver_inbox_path}",
            f"REPLY_INBOX_PATH: {reply_inbox_path}",
            "---",
            "",
            body.rstrip("\n"),
        ]
    )
    return "\n".join(lines).rstrip() + "\n"


def main() -> int:
    args = parse_args()
    request_id = args.request_id or uuid.uuid4().hex
    body = read_body(args)
    message = build_message(
        request_id=request_id,
        message_type=args.message_type,
        receiver_inbox_path=args.receiver_inbox_path,
        reply_inbox_path=args.reply_inbox_path,
        channel_id=args.channel_id,
        body=body,
    )

    if args.output:
        output_path = Path(args.output)
        output_path.parent.mkdir(parents=True, exist_ok=True)
        output_path.write_text(message, encoding="utf-8")
    else:
        sys.stdout.write(message)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

FILE:references/channel_flow_example.md
Execution steps:

1. Read the pending inbox messages and group them by `CHANNEL_ID` when present.

2. For one `CHANNEL_ID`, sort or inspect the pending messages in arrival order and identify:
   - the latest pending message in that channel
   - any older pending messages in that same channel that were superseded by the latest one

3. You may use all messages in that `CHANNEL_ID` to understand the full context.

4. Create a full reply only for the latest pending message in that `CHANNEL_ID`.

5. For each older superseded pending message in that same `CHANNEL_ID`, still create a valid `REPLY` mailbox message, but use the minimal empty reply body:

```md
---
REQUEST_ID: [OLDER REQUEST_ID]
MESSAGE_TYPE: REPLY
CHANNEL_ID: [SHARED CHANNEL_ID]
RECEIVER_INBOX_PATH: [OLDER ORIGINAL_REPLY_INBOX_PATH]
REPLY_INBOX_PATH: [OLDER ORIGINAL_RECEIVER_INBOX_PATH IF FOLLOW-UP IS WANTED]
---
""
```

6. Draft each reply message in a separate scratch file first.

7. Deliver each reply by copying its completed scratch file to that message's destination reply inbox path.

8. Do not ignore older superseded pending messages in the same `CHANNEL_ID`. They still require delivery of a valid `REPLY` mailbox message, even when the body is `""`.

9. After delivery, delete each processed inbox message and keep the scratch messages for future reference or audit.

10. Do not print the final delivered replies to the terminal.
FILE:references/reply_scratch_example.md
---
REQUEST_ID: 8f5c2f7c3f234c6fa9a8d5db8e6f5f8c
MESSAGE_TYPE: REPLY
CHANNEL_ID: review-thread-42
RECEIVER_INBOX_PATH: /path/to/other-agent/.mailbox/inbox/9a7b1c2d3e4f567890abcdef12345678
REPLY_INBOX_PATH: /path/to/original-agent/.mailbox/inbox/4b3c2d1e0f99887766554433221100aa
---

Hello.

FILE:references/send_flow_example.md
Execution steps:

1. Generate a new `REQUEST_ID`, for example:

```bash
uuidgen | tr 'A-Z' 'a-z' | tr -d '-'
```

2. Find the destination inbox folder for the target agent and record it as `TARGET_AGENT_INBOX_FOLDER`. Then set `TARGET_AGENT_INBOX_PATH` to the final message path inside that folder.

   Guidance:
   - If the target agent inbox folder was given explicitly, use that folder.
   - If the workspace documents another agent's mailbox path in Markdown, use that documented inbox folder.
   - If you only know the other agent workspace, derive the inbox folder as `<target agent workspace>/.mailbox/inbox/`.
   - Then set `TARGET_AGENT_INBOX_PATH` to `TARGET_AGENT_INBOX_FOLDER/<request_id>`.
   - If you cannot determine a valid target inbox folder, stop and do not send the message.

3. Verify that `TARGET_AGENT_INBOX_FOLDER` exists. If it does not exist, you may stop and not send the message.

```bash
test -d "$TARGET_AGENT_INBOX_FOLDER"
```

4. If the new message belongs to an existing channel or thread, decide the `CHANNEL_ID`. Otherwise you may omit it.

5. Set `RECEIVER_INBOX_PATH` in the new message to `TARGET_AGENT_INBOX_FOLDER/$REQUEST_ID`.

6. Set `REPLY_INBOX_PATH` in the new message to this agent's own absolute inbox path with the same `REQUEST_ID` if you want a reply.
   Example: `$(pwd)/.mailbox/inbox/$REQUEST_ID`

7. Draft the new message as a complete mailbox message in your local scratch file:

```md
---
REQUEST_ID: [NEW REQUEST_ID]
MESSAGE_TYPE: NEW
CHANNEL_ID: [OPTIONAL CHANNEL_ID]
RECEIVER_INBOX_PATH: [TARGET_AGENT_INBOX_PATH]
REPLY_INBOX_PATH: [THIS_AGENT_ABSOLUTE_INBOX_PATH_WITH_REQUEST_ID]
---

[YOUR NEW MESSAGE TO THE TARGET AGENT]
```

8. Save that complete new message to your private scratch path:

```text
./.mailbox/scratch/$REQUEST_ID
```

9. Deliver the message by copying the completed scratch file to `TARGET_AGENT_INBOX_PATH`:

```bash
cp ./.mailbox/scratch/[NEW REQUEST_ID] "$TARGET_AGENT_INBOX_PATH"
```

10. Keep the scratch message for future reference or audit.

11. Do not print the final delivered message to the terminal.

FILE:references/reply_flow_example.md
Execution steps:

1. Read the incoming inbox message.

2. Read and record the incoming routing metadata. Record the current inbox message path as `ORIGINAL_INBOX_MESSAGE_PATH`. Record `RECEIVER_INBOX_PATH` as `ORIGINAL_RECEIVER_INBOX_PATH`. Record `REPLY_INBOX_PATH` as `ORIGINAL_REPLY_INBOX_PATH` for the later delivery step. Verify that the destination directory for `ORIGINAL_REPLY_INBOX_PATH` exists. If it does not exist, you may stop and not send the reply.

```bash
test -d "$(dirname "$ORIGINAL_REPLY_INBOX_PATH")"
```

3. Keep the original `REQUEST_ID`.

4. If the incoming message has `CHANNEL_ID`, preserve that same `CHANNEL_ID` in the reply.

5. Set `RECEIVER_INBOX_PATH` in the reply to `ORIGINAL_REPLY_INBOX_PATH`.

6. Set `REPLY_INBOX_PATH` in the reply only if you want the conversation to continue. When you set it, it should be `ORIGINAL_RECEIVER_INBOX_PATH`, which is this agent's own inbox path from the incoming message.

7. Draft the reply as a complete mailbox message in your local scratch file:

```md
---
REQUEST_ID: [ORIGINAL REQUEST_ID]
MESSAGE_TYPE: REPLY
CHANNEL_ID: [ORIGINAL CHANNEL_ID IF PRESENT]
RECEIVER_INBOX_PATH: [ORIGINAL_REPLY_INBOX_PATH]
REPLY_INBOX_PATH: [ORIGINAL_RECEIVER_INBOX_PATH IF FOLLOW-UP IS WANTED]
---

[YOUR REPLY TO THE ORIGINAL MESSAGE]
```

8. Save that complete reply message to your private scratch path:

```text
./.mailbox/scratch/$REQUEST_ID
```

9. Deliver the reply by copying the completed scratch file to `ORIGINAL_REPLY_INBOX_PATH`:

```bash
cp ./.mailbox/scratch/$REQUEST_ID "$ORIGINAL_REPLY_INBOX_PATH"
```

10. After delivery, delete `ORIGINAL_INBOX_MESSAGE_PATH`, but keep the scratch reply message for future reference or audit.

11. Do not print the final delivered reply to the terminal.

FILE:references/new_message_example.md
---
REQUEST_ID: 6c7e2d7f9a404db3895a24d4f1b55a1f
MESSAGE_TYPE: NEW
CHANNEL_ID: review-thread-42
RECEIVER_INBOX_PATH: /path/to/agent-b/.mailbox/inbox/6c7e2d7f9a404db3895a24d4f1b55a1f
REPLY_INBOX_PATH: /path/to/agent-a/.mailbox/inbox/6c7e2d7f9a404db3895a24d4f1b55a1f
---

Review the attached change and summarize the main risk.