brsbl/moss-skills

# Moss Canvas

Canvas is a rough editable spatial surface, not a text-diagram renderer.

## Creation Authority

- Preserve and edit an existing `moss-canvas` block when the task requires it.
- Create a new canvas when the user asks for canvas or explicitly requests an editable spatial diagram.
- For a generic diagram, flow, wireframe, menu, or option sketch, use a fenced ASCII code block instead.
- Use an image for a polished static visual, a chart for quantitative shape, and HTML only for genuine interaction.

Use canvas when relative position, connectors, and rough shapes matter more than readable text in the grid. Grid characters become ink; readable words must be label metadata.

## Fence And Payload

# Moss Comments

Use comments for explicit questions, decisions, approvals, or review points that need attention on exact evidence. Fix ordinary wording, duplication, and scannability issues directly instead of leaving editorial comments, except when annotating your own edits to an existing large note.

A root comment has body markers plus a matching `comments.json` entry. Replies exist only in the sidecar and connect through `parentId`.

## Execution Context

Use these attribution values:

| Writer | `source` / `resolvedBy` |
| --- | --- |
| Human using Moss UI | `user` |
| Moss's in-app agent | `agent` |

# Moss Formulas And Variables

Use formulas for one-off numeric expressions and variables for named values that should be reused or referenced.

## Editor Entry

In the editor:

- `=2+2` creates an unnamed executable formula.
- `sum=2+2` creates a named executable variable.
- `time=9am` or `window_1=9am-930am` creates a named symbolic variable.

Variable names start with a letter and contain only letters, digits, `_`, or `-`. Symbolic values may contain punctuation and non-Latin text. A value is executable only when it is a supported numeric expression or contains a bound reference.

# Moss Frontmatter

Frontmatter is an optional top-level YAML mapping before the note's H1.

```markdown
---
status: active
tags:
  - project
people:
  - jane
---

# Note Title

# Moss HTML

Use `moss-html` only for a genuine interactive design artifact or browser behavior that native Moss nodes cannot represent. Do not rebuild native tabs, tables, callouts, checklists, charts, comments, or review workflow. Keep requirements and review instructions in native Markdown.

## Complete Shell

~~~markdown
```moss-html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="moss-html-version" content="v1">

# Moss Links

Use wiki links for Moss navigation, Markdown links for external text links, and media/embed forms only when a rendered preview is intended.

## Wiki Links

```markdown
[[Project Plan]]
[[#Local Heading]]
[[Project Plan#Scope]]
[[Project Plan|display text]]
[[Project Plan|9e64c3df-c1e2-4a4d-8c07-91528f422413]]
```

# Moss Notes

This is the canonical entry point for note layout, node selection, and core persisted syntax. Focused skills own the full contracts for frontmatter, comments, links, formulas and variables, canvas, and HTML.

## Quickstart

1. Edit the existing Markdown content file inside the note directory.
2. For a new workspace note, create `~/Moss/Notes/<Title>/<Title>.md`; never create app-owned sidecars.
3. Put optional frontmatter first, followed by one `# H1` title and then the body.
4. Start the body with a standalone takeaway, following `moss-writing-guidelines`.
5. Choose nodes with the routing table below and follow the focused skill for their exact syntax.

A **workspace note** is a canonical note bundle under `~/Moss/Notes/`. An **external note** is a Markdown file opened from another location and may use a Moss-provided sidecar path. Do not assume the workspace bundle layout for an external note.

# Moss Writing Guidelines

Write every Moss note for a reader who skims first and reads second. This skill owns note structure and composition; `moss-notes` owns file layout, node selection, and persisted syntax.

## Summary First

Frontmatter and the single H1 title come first when present. The first body paragraph after the H1 should state the answer, decision, status, or takeaway without requiring background from later sections.

- Open with the answer, decision, or takeaway — not background or process.
- State conclusions before evidence; put caveats and supporting detail after.

## Progressive Disclosure

- Order sections most- to least-important. Front-load what most readers need.

# Moss Canvas

Canvas is a rough editable spatial surface, not a text-diagram renderer.

## Creation Authority

- Preserve and edit an existing `moss-canvas` block when the task requires it.
- Create a new canvas when the user asks for canvas or explicitly requests an editable spatial diagram.
- For a generic diagram, flow, wireframe, menu, or option sketch, use a fenced ASCII code block instead.
- Use an image for a polished static visual, a chart for quantitative shape, and HTML only for genuine interaction.

Use canvas when relative position, connectors, and rough shapes matter more than readable text in the grid. Grid characters become ink; readable words must be label metadata.

## Fence And Payload

# Moss Comments

Use comments for explicit questions, decisions, approvals, or review points that need attention on exact evidence. Fix ordinary wording, duplication, and scannability issues directly instead of leaving editorial comments, except when annotating your own edits to an existing large note.

A root comment has body markers plus a matching `comments.json` entry. Replies exist only in the sidecar and connect through `parentId`.

## Execution Context

Use these attribution values:

| Writer | `source` / `resolvedBy` |
| --- | --- |
| Human using Moss UI | `user` |
| Moss's in-app agent | `agent` |

# Moss Formulas And Variables

Use formulas for one-off numeric expressions and variables for named values that should be reused or referenced.

## Editor Entry

In the editor:

- `=2+2` creates an unnamed executable formula.
- `sum=2+2` creates a named executable variable.
- `time=9am` or `window_1=9am-930am` creates a named symbolic variable.

Variable names start with a letter and contain only letters, digits, `_`, or `-`. Symbolic values may contain punctuation and non-Latin text. A value is executable only when it is a supported numeric expression or contains a bound reference.

# Moss Frontmatter

Frontmatter is an optional top-level YAML mapping before the note's H1.

```markdown
---
status: active
tags:
  - project
people:
  - jane
---

# Note Title

# Moss HTML

Use `moss-html` only for a genuine interactive design artifact or browser behavior that native Moss nodes cannot represent. Do not rebuild native tabs, tables, callouts, checklists, charts, comments, or review workflow. Keep requirements and review instructions in native Markdown.

## Complete Shell

~~~markdown
```moss-html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="moss-html-version" content="v1">

# Moss Links

Use wiki links for Moss navigation, Markdown links for external text links, and media/embed forms only when a rendered preview is intended.

## Wiki Links

```markdown
[[Project Plan]]
[[#Local Heading]]
[[Project Plan#Scope]]
[[Project Plan|display text]]
[[Project Plan|9e64c3df-c1e2-4a4d-8c07-91528f422413]]
```

# Moss Notes

This is the canonical entry point for note layout, node selection, and core persisted syntax. Focused skills own the full contracts for frontmatter, comments, links, formulas and variables, canvas, and HTML.

## Quickstart

1. Edit the existing Markdown content file inside the note directory.
2. For a new workspace note, create `~/Moss/Notes/<Title>/<Title>.md`; never create app-owned sidecars.
3. Put optional frontmatter first, followed by one `# H1` title and then the body.
4. Start the body with a standalone takeaway, following `moss-writing-guidelines`.
5. Choose nodes with the routing table below and follow the focused skill for their exact syntax.

A **workspace note** is a canonical note bundle under `~/Moss/Notes/`. An **external note** is a Markdown file opened from another location and may use a Moss-provided sidecar path. Do not assume the workspace bundle layout for an external note.

# Moss Writing Guidelines

Write every Moss note for a reader who skims first and reads second. This skill owns note structure and composition; `moss-notes` owns file layout, node selection, and persisted syntax.

## Summary First

Frontmatter and the single H1 title come first when present. The first body paragraph after the H1 should state the answer, decision, status, or takeaway without requiring background from later sections.

- Open with the answer, decision, or takeaway — not background or process.
- State conclusions before evidence; put caveats and supporting detail after.

## Progressive Disclosure

- Order sections most- to least-important. Front-load what most readers need.