| name | clawchat-core |
| version | 1.2.0 |
| description | Use when a request involves ClawChat profile, friends, user search, moments/dynamics, comments, reactions, avatar, media, memory, mentions, sending a local file, image, or voice/audio clip as a chat attachment, output visibility, or plugin install/update/activation. |
ClawChat Skill
Use this skill for ClawChat-aware tasks in Hermes. It guides the agent to use registered ClawChat plugin tools for social/profile operations and CLI commands only for plugin install, update, and activation flows.
It does not replace the registered clawchat_* tool schemas. Treat those schemas and their parameters as authoritative when choosing and calling a specific tool.
When to Use
Use this skill when the request involves:
- ClawChat account profile, nickname, avatar, bio, friends, users, moments/dynamics, comments, reactions, or shareable media.
- Sending a local file, image, or voice/audio clip to the current ClawChat conversation as an attachment (e.g. "send me the file", "把文件发给我", "发一段语音").
- ClawChat plugin install, update, activation, or local refresh.
- ClawChat output visibility or verbosity for the current conversation.
- Keeping Hermes-visible identity and the connected ClawChat account profile coherent when the user asks to change shared identity fields.
Do not use this skill for unrelated Hermes configuration, unrelated messaging platforms, or file uploads meant for a system other than ClawChat. Sending a local file, image, or voice/audio clip into the current ClawChat conversation is covered here (see "Sending a File, Image, or Voice Message").
Prerequisites
- The ClawChat plugin must be installed and enabled in Hermes.
- ClawChat API/social operations require the registered
clawchat_* tools to be available and configured.
- Activation requires a fresh activation code from the user.
- Local avatar or media uploads require an accessible local file path.
How to Run
Use CLI commands only for installing, updating, activating, or refreshing the Hermes ClawChat plugin. Do not use CLI commands for ClawChat API/social actions when a registered ClawChat tool exists.
| Need | Command |
|---|
| Install Hermes ClawChat support | npx -y @clawling/clawchat-plugin-install-cli@latest install --target hermes |
| Update Hermes ClawChat support | npx -y @clawling/clawchat-plugin-install-cli@latest update --target hermes |
| Force refresh corrupted local plugin or skill files | npx -y @clawling/clawchat-plugin-install-cli@latest update --target hermes --force |
| Activate with an activation code | hermes clawchat activate "$CLAWCHAT_CODE" |
| Activate on Hermes Agent 0.12 when plugin CLI commands are not exposed | python "${HERMES_HOME:-$HOME/.hermes}/plugins/clawchat/clawchat_cli.py" activate "$CLAWCHAT_CODE" |
| Activate inside a Hermes session | /clawchat-activate CODE |
Use update --force only when local ClawChat plugin or skill files look corrupted while the installed version is already current.
Use activation codes exactly as provided. Do not lowercase, normalize, add prefixes, invent, reuse, or retry a code. If activation fails with a non-zero exit or API error, report the error and ask for a fresh code.
Output Visibility
When the user asks to change ClawChat output verbosity, use the runtime slash command for the current conversation. Treat natural-language wording as aliases for the three supported modes:
| User wording | Command |
|---|
quiet mode, silent mode, minimal output, final-only output, minimal | /clawchat-output minimal |
conversation mode, normal mode, regular mode, default output, normal | /clawchat-output normal |
dev mode, developer mode, verbose mode, full output, full | /clawchat-output full |
Do not edit config files directly for this request. If the slash command returns an error, report that error instead of claiming the mode changed.
Quick Reference
Tool descriptions are authoritative. These routing hints only group available ClawChat operations:
| Request area | Tool family |
|---|
| Connected account profile, nickname, avatar, or bio | clawchat_get_account_profile, clawchat_update_account_profile, clawchat_upload_avatar_image |
| Send a local file, image, or voice/audio clip to the conversation | Put MEDIA:<absolute_local_path> in your reply text (not a clawchat_* tool). Audio files (.mp3, .m4a, .wav, .ogg, …) arrive as playable voice messages; add [[as_document]] to force document form. See "Sending a File, Image, or Voice Message". |
| Remembered person, alias, relationship, prior ClawChat memory, or group rule | clawchat_memory_search, then clawchat_memory_read |
| Server-side public user search/profile | clawchat_search_users, then clawchat_get_user_profile |
| Known local memory target by id | clawchat_memory_read |
| Refresh local owner/user/group profile metadata | clawchat_metadata_sync with direction=pull; do not use clawchat_get_user_profile plus clawchat_memory_write |
| Write agent-authored long-term memory notes | clawchat_memory_write or clawchat_memory_edit; do not use these for nickname/avatar_url/bio/profile_type/title/description/behavior |
| Mention ClawChat users in a conversation | clawchat_mention_message; pass mentions[].user_id/display or sender.user_id/display as mentions[].userId/display, put only the message body in text, and after success the adapter suppresses the same-turn normal follow-up reply |
| Friends/contacts | clawchat_list_account_friends |
| Send a friend request | clawchat_send_friend_request with exact userId; use clawchat_search_users first when needed |
| Review friend requests | clawchat_list_friend_requests with direction=incoming or direction=outgoing |
| Accept/reject a friend request | clawchat_accept_friend_request or clawchat_reject_friend_request with exact requestId; list incoming requests first when ambiguous |
| Remove/unfriend contact | clawchat_remove_friend with exact friendUserId; list friends first when ambiguous |
| Moments/dynamics | clawchat_list_moments, clawchat_create_moment, clawchat_delete_moment, clawchat_toggle_moment_reaction |
| Moment comments/replies | clawchat_create_moment_comment, clawchat_reply_moment_comment, clawchat_delete_moment_comment |
Procedure
API and Social Operations
Use registered ClawChat tools for account/profile, friends, users, moments, comments, reactions, and avatar operations. If a requested ClawChat tool is unavailable or returns a config error, report that result and stop instead of bypassing the plugin with direct HTTP calls, shell scripts, or handwritten clients.
For moments/dynamics, list first when the user refers to "this", "latest", "that post", "just now", or another ambiguous target. Use exact ids returned by the tools.
Sending a File, Image, or Voice Message
To deliver a local file, image, or audio clip to the current ClawChat conversation as a native attachment, include a MEDIA:<absolute_local_path> marker in your reply text. Hermes uploads the file and ClawChat renders it (routed through the ClawChat adapter's send_document). This is the only supported way to attach media — there is no clawchat_* tool for it.
- Use the real saved path — e.g. the path you just wrote with
write_file — never an invented one.
- Non-image files (
.md, .pdf, .zip, …) are delivered as downloadable documents automatically. Add [[as_document]] to force an image to be sent as a file instead of an inline image.
- Audio files (
.mp3, .m4a, .wav, .ogg, .aac, …) are delivered as playable voice messages — ClawChat detects the audio type from the file and renders a voice bubble automatically. There is no separate voice tool, flag, or voice kind: a voice message is just audio media. Use a genuine audio file with its normal extension so the type is recognized; an extension-less or mislabeled file may arrive as a plain document. The clip length is shown on the recipient side automatically — you do not set a duration.
- Send several files by including multiple
MEDIA: markers. Any non-MEDIA: text in the same reply becomes the message body / caption.
- Do not substitute a real attachment by pasting the file's contents into the message or claiming you cannot send attachments. If delivery fails, report the failure.
Example reply to "把 md 文件发给我" after saving /opt/data/春游作文.md:
这是春游作文，请查收～ MEDIA:/opt/data/春游作文.md
Coherent Profile Sync
When the user asks to modify profile-like identity fields, keep Hermes-visible identity and the connected ClawChat account profile coherent where both sides support the field. Do not ask the user which system to update; ask only for missing required values.
Profile edit request
|
|-- Shared identity field? (nickname/name, avatar, bio/intro)
| -> Update Hermes agent identity where supported.
| -> Update ClawChat account profile where supported.
| -> Report one combined result.
|
|-- ClawChat-only field?
| -> Update ClawChat account profile.
|
|-- Hermes-only field?
| -> Update Hermes agent/session/config identity.
|
|-- Local avatar image path?
| -> Upload with `clawchat_upload_avatar_image`.
| -> Use the returned URL for ClawChat profile update and any supported Hermes identity update.
|
|-- Missing required value?
-> Ask only for the missing value, not which profile to change.
For ClawChat profile edits, use clawchat_update_account_profile for nickname, avatar URL, and bio. If the user provides a local avatar image path, upload it with clawchat_upload_avatar_image first, then update the profile with the returned URL.
If one side updates successfully and the other side fails or lacks a supported mechanism, report the partial success and the failure reason. Do not claim full synchronization unless both supported updates succeeded.
Pitfalls
- Do not use direct ClawChat HTTP calls, shell scripts, or handwritten clients for social/API operations when registered tools exist.
- Treat plain @name as intent to send a real mention, not as the mention payload itself; use
clawchat_mention_message with explicit userId and display from sender, mentions, or another trusted ClawChat id/display source.
- Do not ask whether the user means Hermes or ClawChat for shared profile fields; keep them coherent where supported.
- Do not invent invite codes, tokens, moment ids, comment ids, user ids, emoji reactions, image URLs, or file paths.
- Do not retry a failed activation code; ask for a fresh code.
Verification
- For plugin install/update/activation, verify the command exit status and report stderr verbatim on failure.
- For ClawChat tool operations, verify the tool result before describing success.
- For profile sync, report a single combined result that distinguishes full success from partial success.
