docs(skill): expand imsg agent skill with full CLI surface

[omarshahine]

Summary

Rewrites .agents/skills/imsg/SKILL.md so agents get an accurate, complete picture of the CLI. The previous version covered only chats/history/search/send, hardcoded a machine-specific repo path (~/Projects/imsg), and never mentioned the standard-vs-bridge capability split.

Changes (verified against imsg completions llm and docs/):

• Two-tier capability model up front: standard commands (chats/group/history/watch/search/send/react + --local lookups) vs bridge commands (send-rich, tapback, poll, edit/unsend, chat-*), gated on imsg status --json, with explicit guidance to fall back to standard equivalents rather than suggest disabling SIP.
• Progressive disclosure: points agents at imsg completions llm for the full flag reference so the skill stays short.
• Keeps the original's key insight (resolve UI-visible people via chats/contact_name, not search) and adds what was missing: group before automating, --start/--end inclusive/exclusive semantics, --since-rowid as the watch cursor, --convert-attachments, SMS fallback behavior, and react's most-recent-message-only limitation with tapback as the bridge alternative.
• Requires per-action user confirmation for destructive bridge commands (unsend, delete-message, chat-delete, chat-leave, chat-remove-member).
• Verification now uses ./bin/imsg (the source-build output) for live read proof.

Review fix (540c803): default nickname moved to the bridge tier; the SIP-free tier and example now use nickname --local, with a note that --local returns your own AddressBook label rather than the iMessage-shared nickname. Matches Sources/imsg/Commands/BridgeIntroCommands.swift and the CLI help below.

Poll docs scope (decoupled from #155): an earlier revision documented the poll question echoing as a visible caption, the --comment override, and inbound question backfill. That behavior lives in #155, not on shipped main — imsg poll --help on 0.12.2 exposes only --question/--option, no --comment. Those claims were removed so this skill documents only shipped behavior and merges independently; #157 tracks re-adding them once #155 lands.

Validation transcript

Run against imsg 0.12.2 (Homebrew) on macOS:

$ imsg --version
0.12.2

$ imsg completions llm | grep -c "^### "   # command sections in the agent reference
33

$ imsg poll --help | grep -E '^\s+--'      # shipped poll surface: no --comment
  --db <value>	Path to chat.db (defaults to ~/Library/Messages/chat.db)
  --chat <value>	chat guid or rowid
  --chat-id <value>	chat rowid
  --question <value>	poll question
  --option <value>	poll option text; pass at least twice
  --option-id <value>	vote: UUID of the option to select
  --option-index <value>	vote: 1-based option number to select

$ imsg nickname --help | head -11
imsg nickname
Show contact-card / nickname info for a handle

The default mode reads the contact-card nickname the correspondent shared
over iMessage via the IMCore bridge (requires `imsg launch`, SIP disabled).

--local is a SIP-free alternative that returns YOUR local AddressBook
contact name for the handle. NOTE: this is a different datum — it is your
own contact label, not the iMessage-shared nickname/photo, which is only
available through the bridge.

$ imsg status --json | jq '{sip, v2_ready, basic_features, typing_indicators, read_receipts}'
{
  "sip": "enabled",
  "v2_ready": false,
  "basic_features": true,
  "typing_indicators": false,
  "read_receipts": false
}

(The status output above is from a SIP-enabled machine — exactly the state where the skill's fallback guidance applies.)

jq chat-filter example validated against synthetic NDJSON matching docs/json.md's Chat schema:

$ printf '%s\n' '{"id":1,"contact_name":"Beatrix Smith","identifier":"+15551234567"}' '{"id":2,"name":"Other"}' \
    | jq -s '.[] | select((.contact_name // .display_name // .name // .identifier // "" | ascii_downcase) | contains("beatrix")) | .id'
1

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 12:24 PM ET / 16:24 UTC.

Summary
The PR updates .agents/skills/imsg/SKILL.md to document the current imsg CLI command tiers, JSON/read workflows, bridge-only commands, send/react safety guidance, and validation commands.

Reproducibility: not applicable. this is a skill documentation PR, not a runtime bug report. The prior poll-doc finding no longer reproduces on the current head because the unsupported terms are absent and the remaining claims match current docs/source inspection.

Review metrics: 2 noteworthy metrics.

• Diff scope: 1 file modified, +48/-32. The review surface is limited to the bundled imsg skill and does not alter runtime code, dependencies, CI, or release scripts.
• Prior blocker check: 0 current-head matches. The unsupported poll caption/comment/backfill terms raised in earlier review cycles are absent from the current PR head.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• none.

Next step before merge

• [P2] No repair lane is needed because the current head is a focused skill-doc update with sufficient terminal proof and no actionable finding.

Security
Cleared: The diff changes only repo-local skill documentation and does not alter code execution, dependencies, CI, secrets, permissions, or release scripts.

Review details

Best possible solution:

Merge the focused skill update after normal maintainer review and status checks, while leaving the unshipped poll-caption/backfill guidance to https://github.com/openclaw/imsg/issues/157 after https://github.com/openclaw/imsg/pull/155 lands.

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

Not applicable: this is a skill documentation PR, not a runtime bug report. The prior poll-doc finding no longer reproduces on the current head because the unsupported terms are absent and the remaining claims match current docs/source inspection.

Is this the best way to solve the issue?

Yes. Updating the bundled skill is the narrow maintainable path for this agent guidance, and unshipped poll-caption behavior is now deferred to the linked follow-up instead of being documented early.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9ac97ab1d242.

Label changes

Label justifications:

• P3: This is a low-risk skill documentation update with limited blast radius and no remaining correctness finding.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes copied terminal output from a real macOS/Homebrew imsg 0.12.2 run plus a jq validation transcript for the documented filter example.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied terminal output from a real macOS/Homebrew imsg 0.12.2 run plus a jq validation transcript for the documented filter example.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully and its focused PR-validation and CLI documentation guidance was applied to this skill-doc review. (AGENTS.md:1, 9ac97ab1d242)
• Current main still has the shorter skill: Main's bundled imsg skill still documents only a small read/send workflow and a machine-specific repo path, so the PR is not already implemented on main. (.agents/skills/imsg/SKILL.md:8, 9ac97ab1d242)
• PR head adds the capability split and full-reference pointer: The PR head documents standard vs bridge tiers, bridge fallback guidance, and imsg completions llm as the full command reference. (.agents/skills/imsg/SKILL.md:12, 4e5aa724008b)
• Prior poll-doc blocker is removed: The current PR head has zero matches for the earlier unsupported poll --comment, caption, or backfill guidance; the previous 809395b head still had those terms. (.agents/skills/imsg/SKILL.md:75, 4e5aa724008b)
• Shipped poll CLI surface matches the decoupled docs: Current main's poll command exposes --question, repeated --option, vote selectors, and --reply-to, with no --comment option. (Sources/imsg/Commands/PollCommand.swift:19, 9ac97ab1d242)
• Nickname local-vs-bridge guidance matches source: Current main says default nickname uses the IMCore bridge and --local returns the local AddressBook label, matching the corrected PR text. (Sources/imsg/Commands/BridgeIntroCommands.swift:274, 9ac97ab1d242)

Likely related people:

• steipete: GitHub commit history shows recent bundled imsg skill refreshes and the generated completions command, and local blame shows the current main skill content comes through the v0.12.2 release commit. (role: recent skill and CLI-completions area contributor; confidence: high; commits: 405aa23f5d50, 9202d9701f6c, faa998e39f11; files: .agents/skills/imsg/SKILL.md, Sources/imsg/Commands/CompletionsCommand.swift)
• omarshahine: Prior merged history includes native poll voting and the BlueBubbles private-API bridge, which are key command areas summarized by this skill beyond the PR author's current branch. (role: bridge and poll-adjacent contributor; confidence: high; commits: 617d941f7b1e, c56c24d488ef; files: Sources/imsg/Commands/PollCommand.swift, Sources/imsg/Commands/BridgeMessagingCommands.swift, Sources/imsg/Commands/BridgeIntroCommands.swift)
• ranaroussi: GitHub history shows the SIP-free --local lookup modes and SMS fallback behavior were added in the same command surface the PR now documents. (role: local lookup and SMS fallback contributor; confidence: medium; commits: 5bac5ce24784; files: Sources/imsg/Commands/BridgeIntroCommands.swift, Sources/imsg/Commands/SendCommand.swift)
• veteranbv: GitHub history shows native poll creation/readback work that informs the poll examples and the deferred poll-doc follow-up. (role: native poll feature contributor; confidence: medium; commits: 0c9d85db44f0, 9a21cdbe9017, 2529aa7ad011; files: Sources/IMsgCore/MessagePolls.swift, Sources/imsg/Commands/PollCommand.swift, docs/history.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:42:52.014Z sha ee02e6c :: needs real behavior proof before merge. :: [P2] Correct the SIP-free nickname example
• reviewed 2026-07-04T22:50:47.977Z sha 540c803 :: needs maintainer review before merge. :: none
• reviewed 2026-07-04T22:54:58.024Z sha 540c803 :: needs maintainer review before merge. :: none
• reviewed 2026-07-05T00:46:08.332Z sha 7b0f07b :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll comment option
• reviewed 2026-07-05T01:42:41.118Z sha 809395b :: needs real behavior proof before merge. :: [P2] Remove the unsupported poll caption option
• reviewed 2026-07-05T10:30:37.572Z sha 809395b :: needs real behavior proof before merge. :: [P2] Remove unsupported poll caption guidance
• reviewed 2026-07-05T16:19:51.249Z sha 4e5aa72 :: needs maintainer review before merge. :: none

[omarshahine]

@clawsweeper re-review

[clawsweeper]

🦞🧹
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]

Decoupled from #155 per maintainer decision. The poll caption echo, --comment override, and inbound question backfill live in #155, not shipped main (imsg poll --help on 0.12.2 exposes only --question/--option, no --comment). Those claims are removed (4e5aa72) so this skill documents only shipped behavior; #157 tracks re-adding them after #155 lands. PR body updated with the shipped-poll-surface proof.

@clawsweeper re-review

[clawsweeper]

🦞🧹
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.