moss-notes

name	moss-notes
description	Syntax and file rules for creating or editing Moss notes under ~/Moss/Notes/. Use when authoring or modifying notes, choosing a node type, or following Moss markdown conventions.

Moss Notes

Related skills: writing guidelines (moss-writing-guidelines), frontmatter (moss-frontmatter), comments (moss-comments), links (moss-links), formulas and variables (moss-formulas-variables), canvas (moss-canvas), HTML (moss-html).

Files

• Notes live under ~/Moss/Notes/.
• Folders organize notes. Subfolders and nested folders under ~/Moss/Notes/ are valid; create them when grouping helps or when the user asks.
• Edit the existing markdown content file in the note directory.
• New workspace notes use a same-named note directory and markdown file under ~/Moss/Notes/; start the file with # Title.
• Do not create or edit app-owned sidecars such as meta.json, .folder.json, or layout.json; Moss writes these automatically.
• comments.json is a content sidecar: edit it only via the comments skill.
• assets/ is note-local content storage for referenced media, not metadata.
• Use one H1 title only. Body headings start at H2.

Layers

• Frontmatter is an optional YAML block at the top.
• The first H1 is the note title.
• Body markdown follows the title.
• Comments use body markers plus a sibling comments.json in a note directory; see the comments skill (moss-comments).

Writing Quality

Write notes for a reader who skims first: lead with the takeaway, order sections most- to least-important, and keep paragraphs short. Match the representation to the information's shape, hierarchy, and density: paragraph for one connective idea, bullets for several grouped points, table for repeated attributes, tabs as containers for peer views, ASCII code blocks for agent-generated diagrams and literal text, canvas only when the user asks for canvas, and scoped HTML for visual planning artifacts. Moss nodes compose — tabs can contain tables, callouts, charts, code, HTML, and commentable text. For the full reader-first structure, node composition guidance, note archetypes, and review checklist, see the writing guidelines skill (moss-writing-guidelines).

Core Syntax

Headings

Use one H1 for the title and H2-H4 for body headings; avoid H5/H6.

Tables

Use tables for structured comparisons, compact data, status matrices, or checklists where rows and columns make scanning easier than prose.

| Column A | Column B |
| --- | --- |
| Value | Value |

• Keep each row on one line.
• Keep column counts consistent.
• Cells may contain supported text-level syntax such as emphasis, links, wiki links, inline code, formulas, highlight, underline, and image markdown as cell content. Keep the table row structure valid.
• Escape literal table pipes as \|, except inside formulas.
• Edit table markdown content only. Moss may preserve column widths in layout.json (app-managed); do not encode widths in markdown comments or HTML.

Images, Video, And Webpage Embeds

Use images for visual evidence, diagrams, screenshots, and local media assets; use video for playable recordings or YouTube references. For URL, embed, and note-local media syntax and safety rules, follow the links skill (moss-links).

Code Blocks

Use code blocks for source code, command snippets, logs, SQL, JSON/config, ASCII wireframes, or literal text that should keep spacing. Use standard fenced code blocks with a language identifier:

```sql
SELECT id, title FROM notes WHERE updated_at > '2026-01-01';
```

Bundled languages: javascript (js), typescript (ts), jsx, tsx, python (py), json, sql, css, html (htm), markdown (md), bash (sh, shell, zsh), plaintext (text, txt). Unknown identifiers are preserved as-is and render without bundled highlighting.

Charts

Use charts when visual comparison or trend shape is clearer than a short table/list.

```moss-chart
{"type":"bar","data":[{"label":"Q1","value":100}]}
```

Use current chart types only: bar, stacked-bar, line, or area. Use series for multi-series charts except stacked-bar.

• bar: compare values across categories or rankings.
• stacked-bar: show part-to-whole composition across categories or compare category breakdowns.
• line: show change over time or an ordered sequence.
• area: show trend magnitude or volume over time.
• Do not use donut or pie.
• Keep chart data valid. An invalid moss-chart block is retained as code on import; agent edits must use valid data.
• Avoid charts when a short list/table is clearer or data is too sparse or ambiguous.

Callouts

Use callouts to separate high-signal notes from body prose: informational context, warnings, or priority items.

```moss-callout
warning
Watch this before shipping.
```

First payload line is the type. The editor normalizes to this bare form on save, so do not write type: .... Types: info, warning, priority. Priority callouts can optionally put a level on the second line before the content.

Canvas

Use moss-canvas for ASCII-style diagrams, simple wireframes, flow charts, rough spatial layouts, hand-drawn/diagrammatic visuals, and other rough visual thinking. See the canvas skill (moss-canvas) for detailed rules, including when to avoid canvas and when to use moss-html or moss-chart instead.

ASCII code blocks vs moss-canvas: If a reader needs to read words in the diagram body (option sketches, menu layouts, shortcut maps, before/after comparisons), use a plain fenced code block. If the value is in spatial layout and labels can float as overlays, use moss-canvas. For UI/UX proposal notes, use concise option cards with ASCII wireframes in code blocks when they clarify the decision; keep task plans concise and link to a separate proposal note when visuals get long.

HTML

Use moss-html fenced blocks for scoped visual planning artifacts — prototypes, mockups, state boards, data-flow diagrams, explainers, behavior demos, and clickable UI states — as well as focused embedded HTML previews. Keep each block scoped to one job rather than one giant block, and ground UI HTML in the real product design. See the HTML skill (moss-html).

Tabs

Use tabs as an outer container for 2-4 peer views, options, examples, personas, modes, or states that share one context and are best inspected one at a time.

:::tabs
=== Option A
Content here.

=== Option B
Other content.
:::

A tabs block needs a === Label header. Blank lines may come before the first header; other content before it keeps the block as plain text.

Use 2-4 tabs unless the user asks for more. Tab panels may contain normal Moss content: headings, paragraphs, lists, tables, callouts, charts, code blocks, moss-html, media, links, formulas, and comment markers where those nodes are valid. Use a table or matrix instead when the reader needs to compare all peers side by side; use scoped HTML instead when seeing the whole visual state/layout at once is the point.

Text-Level Syntax

Use text-level syntax for compact references and emphasis inside paragraphs, list items, or table cells. See the links skill (moss-links) for wiki links, Markdown links, YouTube links, and media-link behavior.

Format	Syntax
Wiki link	[[Note Title]]
Highlight	<mark data-color="yellow">text</mark>
Underline	<u>text</u>

• Wiki links connect notes/headings or create navigable references in the Moss workspace; see the links skill (moss-links) for variants and other link types.
• Highlight marks important text, status, or attention within prose; use <mark data-color="yellow">...</mark> rather than ==...==.
• Underline is for intentional emphasis where it will not be confused with a link.
• Color literals in prose become atomic color pills and still export as plain text. Supported forms: 6-digit hex #rrggbb, rgb()/rgba(), and hsl()/hsla().
• Color literals inside inline code or fenced code blocks stay code.

Formulas And Variables

Use formulas and variables for compact computed or labeled values displayed inline with surrounding text or table cells. The core use case is defining editable anchors, then deriving related values from those anchors so a note can show how a system changes together.

For detailed authoring rules — editable anchors, derived values, bound references, IDs, display values, and table-cell usage — use the formulas and variables skill (moss-formulas-variables).

Avoid

• Raw HTML except supported <mark>, <u>, <blockquote>, and moss-html blocks.
• Mermaid as rendered diagrams.
• Placeholder image URLs.
• Duplicating frontmatter fields in the body.