Orz slides skills

Skill wangyu16/orz-slides/orz-slides-skills

Markdown → one .slides.html deck that edits itself in the browser. Ships agent skills.

Install

npx -y skills add wangyu16/orz-slides --skill orz-slides-skills

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Author and edit single-file, self-editing .slides.html presentation decks (orz-slides). Use when a user wants to turn notes or markdown into a browser-based slide deck — one portable HTML file that presents in any browser (reveal.js), is written in orz-markdown with a layout syntax, and can be edited in-browser. Covers the deck source format, slide/layout/region markers, structure templates, and per-slide capacity budgets so slides do not overflow.

SKILL.md

16.0 KB, ~4.3k tokens by cl100k_base, as published. Nobody here has run it

orz-slides — author a `.slides.html` deck

orz-slides turns a deck source into one .slides.html file that:

presents in any modern browser (reveal.js: keyboard/touch nav, slide overview),
is authored entirely in orz-markdown (math, mermaid, smiles, qr, charts, tabs, containers) with a small layout syntax,
can be edited in the browser (per-slide pop-out CodeMirror editor + live preview) and saves itself back into the file.

The deck source is the single source of truth, embedded in the file:

<script type="text/orz-slides" id="orz-deck">
  ...deck config + slides (this is what you write)...
</script>

You write only the deck source. Never hand-write the surrounding HTML (reveal scaffold, runtime, CDN links) — saving regenerates it. To change a deck, edit the deck source (in a .md-ish file fed to the CLI, or in-browser) and let the tool re-serialize.

Status: orz-slides is published to npm (v0.8.5) as two lockstep packages — the orz-slides CLI and the orz-slides-browser engine. Generate decks with the CLI (npx orz-slides deck.md, or install it globally). Speaker view (S), step-reveal fragments, an on-deck timer (T), and slide numbers are wired; PDF export is the remaining planned presenter feature.

When to use it

A user wants a single shareable file that presents like a slide deck with no install — email it, host it, open it offline-of-tooling in a browser.
The content is markdown-native (bullets, math, diagrams, chemistry, code) and the author wants slides without a pixel-design tool.
Prefer .md.html (orz-mdhtml) when the output is a document to read/annotate; prefer .slides.html (orz-slides) when it is a deck to present.

The deck source format

A deck source is plain text: an optional leading  config block, then a sequence of slides. Every slide begins with a  marker — that marker is also the slide separator. There is no bare ---.

<!-- deck
  title: Controlled Polymerization
  theme: executive
  ratio: 16:9
  author: Dr. Yu Wang
  footer: Internal · v3 · 2026
-->

<!-- slide template=title -->
# Controlled Polymerization
## RAFT vs ATRP
**Dr. Yu Wang** · Louisiana · 2026

<!-- slide 2col 3/2 -->
## Results
<!-- @left -->
- Accuracy **92%**
<!-- @right -->
{{smiles C(=S)(SC)SC}}

Deck config (``, optional)

YAML-ish key: value lines. : is for config values; it never appears in a layout. Keys: title, theme, ratio (16:9 default, or 4:3), author, footer (deck-wide footer shown on normal slides), transition (default reveal transition).

title and author also seed the generated document's portable metadata in standard <head> tags and the #orz-meta JSON island. Programmatic hosts may pass richer metadata (license, canonical source, date, description, keywords) to buildSlidesHtml; host values win field by field. This metadata affects the document head only and does not replace the visible footer or deck content.

Theme ids: paper, architect, executive, sage, poppy, neon, chalk (plus a base). Readers can switch live in the editor.

Slide marker (``, mandatory)

The marker carries the layout (a preset alias or a raw split) plus per-slide options:

<!-- slide -->                          single region (plain markdown slide)
<!-- slide 2col 3/2 -->                 a preset with a track ratio
<!-- slide col 3/2 { main; side } -->   a raw split (same grammar as presets)
<!-- slide template=title -->           a structure-page template
<!-- slide 2col bg=#0b3 t=fade -->      with options

Per-slide options (all optional): bg= (color or image), t= (transition), fit= (fit | scroll | off, default fit), class=, id=, and the bare flag step (step-reveal — see below). Template variants use v= (e.g. template=title v=2).

Step-reveal fragments

Reveal a slide's content one piece at a time:

Whole slide — add the bare step flag:  (or combined with a layout, ). Lists reveal per item; other top-level blocks (paragraphs, images, tables) reveal one at a time, in document order, across all regions.
Individual block — tag it with {{attrs[.fragment]}} (orz-markdown attrs), e.g. A revealed paragraph.{{attrs[.fragment]}}. Note: attrs cannot tag a list item — use the step flag for per-bullet reveal.

Presenting

reveal.js keyboard nav, plus: S opens a dedicated speaker view (current + next slide, the slide's @notes, a wall clock and a start/pause/reset timer; arrows there drive the deck). T toggles an on-deck clock/timer overlay. Slide numbers (c/t) and a progress bar show during the presentation.

Track ratios always use / (CSS-aligned: 3/2, auto/1fr, 30%/1fr). : is reserved for key: value config. One symbol, one meaning.

The slide frame & the heading rule

Every normal slide has the same three-band vertical frame:

┌─────────────────────┐
│   title band        │  ← the slide's leading h2 (auto-lifted)
├─────────────────────┤
│   content area      │  ← divided by the layout grammar
├─────────────────────┤
│   footer band       │  ← optional (deck footer and/or @footer)
└─────────────────────┘

Headings are tightly scoped — one rule per level, so a heading's role is never ambiguous:

Level	Role
h1 (`#`)	Title pages only (`template=title`) — the presentation title. Not allowed on a normal slide.
h2 (`##`)	The slide title of a normal slide. Exactly one, and it is the slide's first content. A second h2 (or any h1) on a normal slide is a lint error.
h3–h6	In-slide sub-headings (ordinary markdown).

The leading h2 is auto-lifted into the title band — never put it inside a region. A titled two-column slide is simply:

<!-- slide 2col -->
## Results          ← becomes the title band (spans the slide)
<!-- @left -->  …
<!-- @right --> …

Regions (``)

The content area is split into regions, one per layout leaf. A region's body runs from its  marker to the next marker and is rendered as orz-markdown. Content before the first region marker goes to the layout's primary region (the first leaf), so a single-region slide needs no markers at all.

Region names are flat and unique per slide, regardless of nesting depth — the nesting lives in the layout, not the names. A marker is always just .

The three reserved regions

These names have fixed meaning in every layout:

Marker	Meaning
`<!-- @notes -->`	Speaker notes → reveal's `<aside class="notes">`. Never shown on the slide; stored in the deck, round-tripped on save, and shown in the speaker view (press S while presenting).
`<!-- @footer -->`	This slide's footer band — shows on that slide alone and overrides the deck-wide footer. The deck-wide footer (`<!-- deck footer: … -->`) appears on every slide except the opening `title` page; add an `@footer` to a title slide to force one.
`<!-- @float … -->`	A free-positioned overlay, outside the grid (see below).

Floats (``)

A float is an overlay box layered on top of the layout at a fixed position and size — the one escape from the grid. Use it sparingly (a badge, callout, watermark, logo, pull-out figure): typically zero per slide, occasionally one or two.

<!-- @float left=58% top=10% w=36% h=44% -->
> Key takeaway: **narrow PDI** across all methods.

Geometry attributes (percent of the slide, or px): any of left right top bottom w h; optional z= (default = declaration order, so a later float sits on top). The body is orz-markdown rendered inside the box. Each  is its own overlay (repeatable).

The layout grammar (recursive splits)

The content area is divided by one rule applied recursively: split a box into rows or columns; each cell is a named region or another split.

split  := ("row" | "col") tracks "{" item (";" item)* "}"
item   := region-name | split
tracks := token ("/" token)*        // 2/1 · auto/1fr/auto · 30%/1fr · 200px/1fr

col 2/1 { left; right } — two columns, 2:1.
row auto/1 { head; col 1/1 { a; b } } — a header row above two columns.
Leaves are region names, filled by .

Because the rule is recursive, headers, footers, sidebars, quadrants, and arbitrary grids are all just splits — nothing is special-cased:

<!-- slide row auto/1/auto { banner; col 3/2 { main; row 1/1 { fig; note } }; bar } -->

Presets (named layouts — aliases)

Presets are aliases that expand to the grammar, so the everyday case stays terse. They are sugar, not a separate system — use a preset, a raw split, or mix freely. An optional [a/b] sets the track ratio.

Preset	Expands to	Regions
(none)	single region	`body`
`2col [a/b]`	`col a/b { left; right }`	left, right
`3col`	`col 1/1/1 { left; mid; right }`	left, mid, right
`2row [a/b]`	`row a/b { top; bottom }`	top, bottom
`main-side [a/b]`	`col a/b { main; side }` (default `2/1`)	main, side
`quad`	`row 1/1 { col 1/1 { tl; tr }; col 1/1 { bl; br } }`	tl, tr, bl, br

Structure-page templates (`template=`)

Templates are structure pages. A template= slide reads structured fields from its markdown — # title, ## subtitle, then the rest as a meta/byline block — and lays them out with dedicated styling instead of the region grid. Pick a layout with v= (e.g. template=title v=2):

Template	Write	Layouts (`v=`)
`title`	`#` title, `##` subtitle, author/date line	v1 centered + accent rule (default) · v2 left accent bar · v3 uppercase kicker · v4 split (bold accent band beside the title) · v5 full-color cover (title bottom-left) · v6 oversized editorial (huge type)
`section`	`#` section title (rest = meta)	v1 underline rule (default) · v2 centered accent · v3 surface band + left bar · v4 outlined box
`outline`	an agenda list	v1 plain (default) · v2 cards · v3 two columns
`closing`	thanks / contact / a `{{qr}}`	v1 centered (default) · v2 full-color cover · v3 oversized

All template styling adapts to the active theme (via --accent / --ink / --muted), light or dark.

Capacity budgets — author within the slide, don't overflow

Scale-to-fit is a safety net, not a licence to overflow. These are per-container budgets for a 16:9 slide at the default theme font. They scale with a region's area: a half-width column gets ~half a full body's budget; a quad cell ~a quarter.

Container	Budget (16:9, default font)
Slide title (h2)	≤ ~10 words, 1 line
Title-page title (h1)	≤ ~8 words
Full body (single region)	≤ ~6 bullets or ~55 words or ~14 code lines
One column of `2col`	≤ ~5 bullets / ~35 words
One cell of `3col` / `quad`	≤ ~3–4 bullets / ~20 words
`side` (in `main-side`)	≤ ~4 short bullets, or one small figure
Bullet line	≤ ~10 words, 1 line; avoid nesting beyond 1 level
Table	≤ ~6 rows × 4 cols (full width); fewer in a column
Code block	≤ ~12 lines full / ~8 in a column
Figure / diagram / chart	one primary visual per region

Core rule: prefer splitting into another slide over crowding one. Budgets shrink proportionally for 4:3 and for smaller regions; estimate any nested split with budget ≈ baseline × region-area-fraction.

Do / don't

Start every slide with a  marker.
Put exactly one ## h2 as the first line of each normal slide (the title).
Reach for a preset first; drop to a raw split only when you need nesting.
Keep region content under the budgets above; split a crowded slide in two.
Use  for speaker notes — they never clutter the slide.
Use a deck-wide footer () and override per-slide with  only when needed.

Don't

Don't use # (h1) on a normal slide, or a second ## (h2) — both are lint errors.
Don't hand-edit the generated .slides.html; edit the deck source.
Don't use : in a layout, or / in a config value.
Don't reuse a region name within a slide (names are unique per slide).
Don't lean on floats for layout — that is what splits are for. Floats are occasional overlays, not the grid.

Example slides

A titled two-column slide

<!-- slide 2col 3/2 -->
## Results at a glance
<!-- @left -->
- Accuracy **92%** across all runs
- Latency under **40 ms**
- Zero regressions in CI
<!-- @right -->
{{chart
type: bar
labels: A, B, C
series: Score = 92, 81, 76
}}
<!-- @notes -->
Lead with accuracy; the latency number is the surprise — pause here.

A nested-split slide (header row over a main + stacked-figures column)

<!-- slide row auto/1 { head; col 3/2 { main; row 1/1 { figA; figB } } } -->
## Pipeline architecture
<!-- @head -->
Ingest → transform → serve, with back-pressure between stages.
<!-- @main -->
```mermaid
graph LR; A[Ingest]-->B[Transform]-->C[Serve]

Spec v3 — scan to read.


### A title page

Controlled Polymerization

RAFT vs ATRP — a practical comparison

Dr. Yu Wang · University of Louisiana · 2026


---

## Special content & enhancers

Region bodies are full orz-markdown. The deck runs client enhancers, drawn per
visible slide (and re-run on edit): **KaTeX** (math/mhchem, pre-rendered),
**Mermaid**, **SmilesDrawer** (chemistry), and **`{{chart}}`** (simple
bar/line/pie/doughnut via Chart.js — the line-based `type:` / `labels:` /
`series:` config shown above). For the full orz-markdown syntax (containers
`::: name`, `{{name body}}` plugins, `{{attrs[#id .class]}}`, tabs), read the
orz-markdown skill at `node_modules/orz-markdown/orz-markdown-skills/SKILL.md`.

## What the generated file needs at view time

"Self-contained" means *one file*. By default the CLI **inlines** the engine,
reveal's core CSS, and **all seven themes**, so a text deck **presents and
switches themes offline**. The libraries that load from CDN (cached after first
load) are only: KaTeX (math), Mermaid, SmilesDrawer, Chart.js, and CodeMirror
(the editor) — so a deck that uses math/diagrams/charts, or in-browser editing,
needs internet. `--cdn` instead references the engine + theme from jsDelivr
(smaller files, needs network). Editing/Save in place needs a Chromium browser
(File System Access API); presenting works in all modern browsers.

## Security

`.slides.html` files are **single-file executable HTML** — opening one runs its
embedded JavaScript. Treat them like programs: only open or edit files from a
trusted source, and advise users the same. The one-click framework update is
opt-in (edit view only, explicit confirm) and always fetches from the hardcoded
canonical jsDelivr packages — a tampered file can't redirect it. A file's
integrity can't be verified from inside it; for authenticity, verify out-of-band.
See the README "Security" section.

Gives 0 of the 12 instructions most slides presentations skills give in ~4.3k tokens

Counted across 568 of the 571 authors here whose files we hold, read 2026-08-06

include a visual element on every slidein 52 of 568, across 21 files
put one idea per slidein 50 of 568, across 42 files
state the design approach before writing codein 38 of 568, across 8 files
validate XML immediately after each editin 37 of 568, across 7 files
rasterize gradients and icons as PNG images before referencing themin 37 of 568, across 7 files
generate and inspect thumbnails to validate layoutin 37 of 568, across 7 files
commit to a single visual motif across every slidein 37 of 568, across 12 files
use web-safe fonts onlyin 36 of 568, across 7 files
keep 0.5 inch minimum marginsin 35 of 568, across 9 files
use two-column layout for slides with charts or tablesin 34 of 568, across 5 files
save a template inventory analysis to a filein 33 of 568, across 4 files
use subagents to visually inspect rendered slidesin 33 of 568, across 9 files

Said here and by no other author read

Write exactly one h2 as the first line
Prefer splitting into another slide over crowding
Put exactly one h2 on each normal slide
Write only the deck source text
Use the step flag for per-bullet reveal
Use colons only for config key value pairs

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.