docs: tailor imsg skill for OpenClaw agents by omarshahine · Pull Request #100105 · openclaw/openclaw

omarshahine · 2026-07-04T22:42:42Z

What Problem This Solves

Resolves a problem where the bundled imsg skill read like a generic CLI reference and did not guide OpenClaw agents through DM vs group targeting, bridge-only features, or safety-sensitive iMessage actions.

Why This Change Was Made

The skill now starts from the agent workflow: resolve the conversation, choose DM/existing group/new group, pick the lowest-capability command, confirm sends and visible state changes, and then execute with stable identifiers. It also documents current imsg surfaces for replies, formatting, reactions, polls, watch, long-running RPC, and private API actions while keeping public AppleScript permissions separate from bridge-backed IMCore behavior.

User Impact

OpenClaw agents get clearer guidance for using imsg correctly across direct messages and group chats. They should be less likely to send to ambiguous recipients, mutate groups accidentally, confuse public react with bridge tapback, or run imsg launch without user approval.

Evidence

Documented commands verified against the installed imsg 0.12.2 on macOS 26 (this is a docs change, so proof = the documented surface matches the real CLI):

$ imsg --version
0.12.2

# Poll surface the skill documents — --question/--option/--reply-to/vote flags exist,
# and there is deliberately NO --comment (that lives in openclaw/imsg#155, not shipped):
$ imsg poll --help | grep -E '^\s+--'
  --chat <value>        chat guid or rowid
  --chat-id <value>     chat rowid
  --question <value>    poll question
  --reply-to <value>    guid of message to reply to
  --option <value>      poll option text; pass at least twice
  --poll <value>        vote: guid of the poll message to vote on
  --option-id <value>   vote: UUID of the option to select
  --option-index <value>  vote: 1-based option number to select

# Capability keys the skill tells agents to gate on:
$ imsg status --json | jq '{bridge_version, v2_ready, basic_features, advanced_features}'
{ "bridge_version": 2, "v2_ready": true, "basic_features": true, "advanced_features": true }

# The documented poll-read jq filter returns real poll objects from history:
$ imsg history --chat-id <id> --limit 40 --json \
    | jq -s '[.[] | select(.poll != null) | {kind: .poll.kind}] | group_by(.kind) | map({(.[0].kind): length}) | add'
{ "created": 5, "vote": 3 }

Also: git diff --check -- skills/imsg/SKILL.md clean; pnpm docs:list used to identify relevant iMessage docs context.

Scope note: an earlier revision documented the poll caption echo, --comment override, and inbound question backfill; those live in openclaw/imsg#155, not shipped imsg 0.12.2, and were removed in 01e9c38 so this skill documents only shipped behavior (see the poll --help proof above). They'll be re-added once a release ships #155.

clawsweeper · 2026-07-04T22:44:08Z

Codex review: needs real behavior proof before merge. Reviewed July 5, 2026, 1:08 PM ET / 17:08 UTC.

Summary
The PR rewrites skills/imsg/SKILL.md into workflow-oriented OpenClaw agent guidance for iMessage/SMS targeting, sends, replies, reactions, polls, watching, bridge actions, and safety checks.

PR surface: Docs +127. Total +127 across 1 file.

Reproducibility: not applicable. this is a skill documentation PR rather than a bug report. Dependency source spot-checks cover the corrected command examples, but no real after-change imsg behavior proof is attached.

Review metrics: 1 noteworthy metric.

Visible iMessage action families: 5 documented. The PR documents sends, replies, reactions, polls, and group mutations, so the skill text can affect agent-triggered message delivery behavior.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Attach redacted terminal output, terminal screenshots, logs, or linked artifacts for the claimed imsg help/status checks.
Get maintainer confirmation that imsg should still be refined as a bundled core skill while removal work is open.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR body lists commands but does not include attached redacted terminal output, screenshots, logs, live output, or linked artifacts proving the checked imsg behavior after the change; contributor action is still needed before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

The PR still lacks attached real behavior proof for the claimed imsg help/status checks; the skill guides real sends, replies, reactions, polls, and group mutations.
[P1] The related bundled-skill trim would remove imsg from core, so maintainers need to choose whether this core skill-doc churn should land or move to ClawHub packaging.

Maintainer options:

Require proof before trusting send guidance (recommended)
Require redacted terminal output, logs, or screenshots for the imsg v0.12.2 help/status checks before merging prompt-facing message-action guidance.
Accept documented behavior risk
A maintainer could intentionally merge the skill text without contributor-posted runtime proof if they already trust the documented imsg command surface.
Pause for ClawHub packaging
If the starter-set trim is the intended direction, pause or close this PR and move the updated imsg guidance to a ClawHub skill package.

Next step before merge

[P1] The remaining blockers are contributor proof and maintainer product direction, not a narrow repair that automation can safely make.

Maintainer decision needed

Question: Should OpenClaw continue refining the bundled imsg skill while refactor(skills): trim bundled starter set #95132 proposes removing imsg from the bundled starter set?
Rationale: Both paths are coherent: this PR improves safety for a currently bundled skill, while the related cleanup moves optional skill ownership toward ClawHub; automation cannot choose that product boundary.
Likely owner: fuller-stack-dev — This account owns the overlapping bundled-starter-set trim PR that determines whether imsg remains bundled.
Options:
- Keep bundled and require proof (recommended): Treat imsg as a maintained bundled skill for now, require redacted real command proof, and review the updated guidance before merge.
- Move guidance to ClawHub: Pause or close this core PR and ask the contributor to publish the imsg skill package through ClawHub instead of keeping optional skill churn in core.
- Wait for starter-set trim: Defer this PR until the bundled-skill trimming decision in the related maintainer PR is resolved.

Security
Cleared: The diff changes one Markdown skill file and does not alter executable code, dependency sources, workflows, permissions, package metadata, or secret handling.

Review details

Best possible solution:

Require redacted real imsg help/status proof, then merge only if maintainers intentionally keep curating the bundled imsg skill; otherwise publish the updated guidance as a ClawHub skill package and let the bundled-skill trim proceed.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a skill documentation PR rather than a bug report. Dependency source spot-checks cover the corrected command examples, but no real after-change imsg behavior proof is attached.

Is this the best way to solve the issue?

Unclear: the rewrite is plausible and the prior unsupported poll example is gone, but the best merge path still depends on contributor proof and maintainer direction on bundled skill ownership versus ClawHub.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 444d54c5389a.

Label changes

Label changes:

add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit. Replaced prior rating: 🧂 unranked krab.
remove rating: 🧂 unranked krab: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

P3: This is a low-priority bundled skill documentation/workflow PR, not a runtime outage, data-loss incident, crash loop, or security bypass.
merge-risk: 🚨 message-delivery: The rewritten skill guides agent-triggered iMessage sends, reactions, poll votes, and group mutations where wrong or unproven guidance can affect real message delivery.
rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit. Replaced prior rating: 🧂 unranked krab.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists commands but does not include attached redacted terminal output, screenshots, logs, live output, or linked artifacts proving the checked imsg behavior after the change; contributor action is still needed before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

PR surface:

Docs +127. Total +127 across 1 file.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	1	184	57	+127
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	1	184	57	+127

What I checked:

Repository review policy applied: Root AGENTS.md requires full-policy review, source/dependency-backed evidence, and routes optional skill bundles to plugins, ClawHub, or owner repos when current seams suffice. (AGENTS.md:29, 444d54c5389a)
Vision scope for skills: VISION.md says bundled skills remain for baseline UX, but new skills should go through ClawHub first and bundled promotion needs a clear product, security, or ownership reason. (VISION.md:87, 444d54c5389a)
Final PR content: The final PR head documents agent flow, target resolution, bridge checks, sends, reactions, polls, watch, and safety rules, and no longer includes the earlier unsupported poll --comment example. (skills/imsg/SKILL.md:204, 01e9c38e5cd3)
Skill text is model-facing behavior: Current main tells agents to read an applicable SKILL.md and follow it, so this Markdown can directly affect agent-triggered iMessage actions. (src/agents/system-prompt.ts:269, 444d54c5389a)
Shipped imsg poll contract checked: imsg v0.12.2 exposes poll send and poll vote with --chat, --chat-id, --question, repeated --option, --poll, --option-id, and --option-index; no --comment option is present. (openclaw/imsg:Sources/imsg/Commands/PollCommand.swift:19, 9fe0d92b5dbf)
Shipped imsg send/reaction contracts checked: imsg v0.12.2 supports the documented send, react, send-attachment, send-rich, tapback, status, and watch surfaces used by the rewritten skill examples. (openclaw/imsg:Sources/imsg/Commands/SendCommand.swift:12, 9fe0d92b5dbf)

Likely related people:

steipete: Live GitHub history shows repeated imsg skill install, rename, and docs work, including the brew installer and embedded skill guidance updates. (role: introduced behavior and bundled skill history contributor; confidence: high; commits: 1cf455e91ced, decbd611a092, 9a7160786a7d; files: skills/imsg/SKILL.md)
omarshahine: Current main history shows merged iMessage native poll and reply attachment work that the rewritten skill documents, beyond authoring this PR. (role: recent adjacent iMessage contributor; confidence: high; commits: c92c33d10806, 200eb62ef4ce; files: extensions/imessage/src/actions.runtime.ts, extensions/imessage/src/message-tool-api.ts)
vincentkoc: Live history shows recent direct chat normalization work in iMessage runtime adjacent to target-resolution guidance. (role: recent adjacent iMessage contributor; confidence: medium; commits: cc89e155c35b; files: extensions/imessage/src/actions.runtime.ts)
fuller-stack-dev: The open bundled starter-set trim PR authored by this account explicitly proposes removing imsg from core, which overlaps this PR's product boundary. (role: related cleanup PR author; confidence: medium; commits: 28e0c5141a53; files: skills/imsg/SKILL.md)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (7 earlier review cycles)

reviewed 2026-07-04T22:47:41.228Z sha 9fe8a7e :: needs real behavior proof before merge. :: none
reviewed 2026-07-04T22:55:49.978Z sha 9fe8a7e :: needs real behavior proof before merge. :: none
reviewed 2026-07-05T00:47:27.966Z sha d86f844 :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll --comment example
reviewed 2026-07-05T00:52:47.241Z sha d86f844 :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll --comment example
reviewed 2026-07-05T02:22:30.670Z sha 3a0c866 :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll --comment example
reviewed 2026-07-05T03:03:05.971Z sha 3a0c866 :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll --comment example
reviewed 2026-07-05T17:00:04.951Z sha 01e9c38 :: needs real behavior proof before merge. :: none

…ble comment

…m its caption

Drop the poll caption echo, --comment override, and inbound question backfill from the imsg skill: those live in imsg PR openclaw/imsg#155, not shipped imsg 0.12.2 (poll --help exposes only --question/--option). Also removes the inaccurate 'reply comment whose reply_to is the poll guid' framing — #155 sends the caption as a plain message, not a reply. Keeps shipped poll send/vote usage. Re-add once a release ships #155.

omarshahine · 2026-07-05T16:58:53Z

Marked ready for review. The poll caption echo / --comment / inbound backfill claims (and the inaccurate 'reply comment' framing) were removed in 01e9c38 — the skill now documents only shipped imsg 0.12.2 poll behavior, verified against imsg poll --help. The unshipped caption behavior lives in openclaw/imsg#155 and will be re-added once a release ships it.

@clawsweeper re-review

clawsweeper · 2026-07-05T16:58:56Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

omarshahine · 2026-07-05T17:04:39Z

Added real behavior proof to the PR body: verified the documented commands against installed imsg 0.12.2 (--version, the poll flag surface showing no --comment, status --json capability keys, and the documented poll-read jq filter returning real poll objects).

Note the remaining item is a maintainer decision, not a contributor gap: this overlaps #95132 (trim bundled starter set) on whether skills/imsg/SKILL.md should stay bundled in core or move to ClawHub. Happy to rebase or move packaging per your call.

@clawsweeper re-review

* docs: tailor imsg skill for OpenClaw agents * docs(imsg-skill): document that poll send echoes --question as a visible comment * docs(imsg-skill): note inbound native poll question is backfilled from its caption * docs(imsg-skill): document only shipped poll behavior Drop the poll caption echo, --comment override, and inbound question backfill from the imsg skill: those live in imsg PR openclaw/imsg#155, not shipped imsg 0.12.2 (poll --help exposes only --question/--option). Also removes the inaccurate 'reply comment whose reply_to is the poll guid' framing — openclaw#155 sends the caption as a plain message, not a reply. Keeps shipped poll send/vote usage. Re-add once a release ships openclaw#155. --------- Co-authored-by: Omar Shahine <10343873+omarshahine@users.noreply.github.com>

docs: tailor imsg skill for OpenClaw agents

9fe8a7e

openclaw-barnacle Bot added size: M maintainer Maintainer-authored PR labels Jul 4, 2026

clawsweeper Bot mentioned this pull request Jul 4, 2026

refactor(skills): trim bundled starter set #95132

Draft

docs(imsg-skill): document that poll send echoes --question as a visi…

d86f844

…ble comment

clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jul 5, 2026

omarshahine added 2 commits July 4, 2026 18:39

docs(imsg-skill): note inbound native poll question is backfilled fro…

3a0c866

…m its caption

omarshahine marked this pull request as ready for review July 5, 2026 16:58

omarshahine merged commit e09aba1 into main Jul 5, 2026
74 checks passed

omarshahine deleted the scrub-imsg-skill-current-features branch July 5, 2026 17:12

github-actions Bot mentioned this pull request Jul 5, 2026

📡 Upstream Digest — 2026-07-05 19:04 UTC curtismercier/openclaw-mods#1217

Open

clawsweeper Bot mentioned this pull request Jul 14, 2026

fix(skills): require resolved approval before mutating actions #84860

Open

24 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: tailor imsg skill for OpenClaw agents#100105

docs: tailor imsg skill for OpenClaw agents#100105
omarshahine merged 4 commits into
mainfrom
scrub-imsg-skill-current-features

omarshahine commented Jul 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

omarshahine commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

clawsweeper Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omarshahine commented Jul 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

omarshahine commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 5, 2026 •

edited

Loading