[sonichi]

What

Two doc-only changes that tell agents to tag by full Matrix ID:

• skills/agent-room-ops/SKILL.md, "Addressing & delivery", gains one rule. A short tag like @alice (no :server) is ambiguous across homeservers, no client links it, and nothing should complete it. Write the full mxid (@alice:example.org) every time you tag someone, in say too.
• skills/agent-room-ops/mention.py, module docstring: the claim that "a member mxid in the plain body is … rendered as a pill" now says full mxid, and that a short @handle is never linked.

No code behaviour changes.

Why

The owner's rule: agents always tag with the full ID, and short tags must not be auto-completed by say or anything else. Short tags currently render as plain text in both the web and mobile clients. Only an anchor built from a full ID becomes a pill. The backend's separate short-handle resolution is being raised with the backend team on its own.

Checks

tests/agents-md-sync.test.py: Results: 5 passed
skills/agent-room-ops/test_room_ops.py: Ran 173 tests ... OK
scripts/lint-skill.py skills/agent-room-ops: 1 manifest(s), 0 error(s), 0 warning(s)
git diff --check: clean

🤖 Generated with Claude Code

[john-the-dev]

Review at a7f1566651b33fd73aa33bc7d09016ef1da8df4b. Docs only, 2 files (+7/-3).

No blockers; review-clean from my side. I'm leaving this as a comment, not an approval: on sonichi/sutando I approve only after the owner's Sutando Release agent has verified the head.

• SKILL.md: the new rule fits under "Addressing & delivery". It agrees with the bullet just after it, which says the broker routes on the full mxid in m.mentions or as a whole token in the body, so a short @handle neither routes nor renders.
• mention.py: the docstring now says full mxid. That matches what mention.py already does: it resolves to an mxid and leads the body with it.
• Nit, non-blocking: the bullet two lines above still lists "@qingyun" as an example of text forms that don't reach the agent. It's consistent with this PR, so no change needed.

I didn't re-run the three checks quoted in the PR body. CI is the record for those.

[qingyun-wu]

Approve at a7f1566. Docs-only: one SKILL.md bullet and the mention.py docstring. Both are accurate about routing: the broker matches a member's full mxid as a whole token, and a bare @local without :server is not an mxid.

Non-blocking wording suggestion: "nothing should complete it for you" sits right above the bullet that tells agents to use mention <handle>, and mention.py's own docstring advertises resolving "qingyun-001" to the mxid. An agent could read the two as contradictory. Suggest something like: "…so never type a short tag into message text. To address someone by handle, use mention, which resolves it to the full mxid and writes that." That keeps the rule (no short tags in text) and the sanctioned path (resolution by the tool) clearly separate.

Not verified: "No client links it". I didn't check cinny's or Element's linkifier for short handles.

[github-actions]

Coverage Gate

✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 91%.

Diff Coverage

Diff: origin/main...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

[john-the-dev]

Approving at a7f1566651b33fd73aa33bc7d09016ef1da8df4b.

• My review (5493496321) found no issues.
• Codex-core compatibility is verified OK at this exact head by Rui's Codex-core agent:
  • The executable AST of mention.py is identical to the base.
  • The room-mention fallback suite passes 43/43.
  • CI is green: 31 successful, 1 skipped, CLA green.