moss-comments - SKILL.md Agent Skill

name: moss-comments description: Comment annotation syntax for Moss notes. Use when adding, preserving, or editing note comments and their sidecar metadata.

Comments

Comments require both body markers and comments.json.

Body Markers

Wrap the exact annotated range:

The %%m:c1:start%%current layout%%m:c1:end%% needs work.

IDs may contain letters, numbers, hyphens, and underscores.
Start and end markers are both required.
Multiple comments can share one range: %%m:a,b:start%%text%%m:a,b:end%%.

Sidecar Metadata

Write comments.json beside the note markdown file:

{"c1":{"text":"Tighten this wording.","createdAt":1707900000,"updatedAt":1707900000,"source":"external"}}

Every marker ID needs matching sidecar metadata.
Every sidecar key needs matching body markers.
source values: "external" for comments written by an agent outside of Moss, "agent" reserved for the in-app Moss agent, "user" for human comments. Always set "external" explicitly for comments you write.

Placement

Plain text: wrap the exact words.
Inline nodes: wrap the entire token, for example %%m:x:start%%[[Project Plan]]%%m:x:end%%.
Block nodes: put markers on standalone lines around the whole block.

%%m:b1:start%%
![Demo](assets/demo.png)
%%m:b1:end%%

Do not place markers inside wiki links, formula/variable pills, color code pills, fenced block payloads, or raw HTML comments. Treat atomic inline pills as indivisible. For color literals such as #4f8a6b, rebeccapurple, or rgb(72, 67, 60), prefer annotating the surrounding sentence or phrase rather than trying to split the literal itself.

Image Attachments

Comments may include image attachments stored under the note's assets/ directory:

{"c1":{"text":"See screenshot.","createdAt":1707900000,"updatedAt":1707900000,"source":"external","imageUrls":["assets/comment-abc.png"]}}

Use the imageUrls array with note-relative paths under assets/.
To read an attached image, resolve the path against the note's directory and read the file from assets/.

@Mentions

Mentions in comment text are references to notes, files, or folders. Each displayed mention is wrapped with U+2063 (INVISIBLE SEPARATOR) before and U+2064 (INVISIBLE PLUS) after, e.g. Re: ⁣@Project Plan⁤ scope.

When a comment asks you to use or inspect an @mention, use the available mention id/path or note sidecar metadata to resolve and read the referenced target before acting.
Mentioned targets may be inside or outside the Moss notes directory; do not assume ~/Moss/Notes/.
If the mention cannot be resolved or multiple targets match, report the ambiguity instead of inventing a path.
Preserve the wrappers verbatim when editing existing comment text — the renderer uses them to display the mention as a pill.