Scrolls explainer

This skill delivers one self-contained HTML page that explains the scrolls skill family visually. The page ships ready-made in

assets/scrolls-explainer.html

. There are three modes:

/scrolls-explainer
, or
--show
(the same thing): open that page where it is, copying nothing.
-o PATH
: copy that page to a file or folder the user wants it in.
--build
: regenerate that page from the
```
scrolls-*
```
skills next to this one, so it matches them as they are now.

Scope note: This skill never reads, checks or changes the user's scrolls memory (
docs/.scrolls/
,
SCROLLS.md
,
CLAUDE.md
,
AGENTS.md
). The default (
--show
) writes nothing.
-o
writes only the page, at the path given, and never overwrites a different existing file unless the user asked (
-f
).
--build
writes only this skill's own
assets/scrolls-explainer.html
and, with
--reviewed
(or when you add a missing tab),
assets/explainer-graph.json
— nothing outside this skill's folder.

Cross-platform

The script ships in two forms that behave identically:

explain.sh

(bash — macOS, Linux, or Windows with Git Bash/WSL) and

explain.ps1

(PowerShell 7+ — Windows, or macOS/Linux with

pwsh

installed). Both are thin launchers for

explain.py

(stdlib-only Python 3.9+), resolving

python3

and then

python

. Pick the launcher by what's actually available: try

bash --version

; if that succeeds, use

.sh

; otherwise use

.ps1

via

pwsh

(preferred) or, only if

pwsh

isn't available, the built-in Windows PowerShell

powershell.exe

Options

Flag	Meaning
(none), `--show`	The default. Copy nothing: print the path and `file://` URL of the bundled `assets/scrolls-explainer.html` and open it in place in the default browser. If no browser can be opened (a remote or headless machine), that is only a notice, not an error. `--show` can't be combined with `-o` .
`-o` , `--output PATH`	Copy the page here instead. A file path is used as is; an existing folder (such as `.` ), or a path ending in `/` , gets `scrolls-explainer.html` inside it. Missing folders are created.
`-f` , `--force`	With `-o` only: overwrite a different file already at that path. Without it the script refuses (exit 3) and changes nothing. An identical file is simply reported as up to date.
`--open`	With `-o` : also open the copy in the default browser.
`--build`	Regenerate `assets/scrolls-explainer.html` from the `scrolls-*` skills next to this one (see "Building" below). On its own it only rebuilds; add `--show` to open the result, or `-o` to also copy it.
`--reviewed`	With `--build` only: the tabs of the skills whose `SKILL.md` changed have been checked; record their new fingerprints, then build.
`--skills-dir DIR`	With `--build` only: where the `scrolls-*` skills are. Default: the folder this skill is in.
`--version`	Print the page's version ( `scrolls-explainer X.Y.Z` ) and exit.
`-h` , `--help`	Print usage and exit.

Exit codes:

done (or already up to date),

the bundled page is missing or a file can't be written,

usage error,

a different file is in the way (no

-f

--build

stopped because the skills need attention,

--build

can't find the network-flow skill.

Steps

Pick the mode from the request.
- Bare
```
/scrolls-explainer
```
  ,
```
--show
```
  , or "show me", "open it", "let me see the explainer": show the bundled page (no flags). This is the default: don't copy the page anywhere unless asked.
- "Rebuild", "regenerate", "update the explainer", "make it match the skills":
```
--build
```
  (then follow "Building" below).
- The user wants a file of their own (save, export, put it in
```
docs/
```
  , give me a copy,
```
-o …
```
  ): copy it with
```
-o
```
  .
For a copy, choose the path.
- The user named a file or folder: pass it as
```
-o
```
  .
- The user asked for a copy "here" or named no place:
```
-o .
```
  writes
```
./scrolls-explainer.html
```
  in the current directory. If the host gives you a designated folder for files the user can open (an outputs or scratchpad folder), and the current directory is a project the user did not ask you to write into, use that folder instead, so the page doesn't land in their source tree unasked.
- Add
```
-f
```
  only when the user asked to replace an existing page, or the script already refused and the user then confirmed.
- Add
```
--open
```
  when the user also wants the copy opened and the machine has a display.

Run the script from the directory the path is relative to:

bash <skill-dir>/scripts/explain.sh                      # = --show
bash <skill-dir>/scripts/explain.sh -o PATH [-f] [--open]
bash <skill-dir>/scripts/explain.sh --build [--reviewed] [--show | -o PATH]
pwsh <skill-dir>/scripts/explain.ps1 …same flags…

Showing prints

scrolls-explainer <version>: <bundled page's path>

and

open: file://…

. A copy prints

scrolls-explainer <version>: wrote <absolute path>

(or

… is already up to date

) and then

open: file://…

On exit 3 (a different file is already there): tell the user, and offer
```
-f
```
or another
```
-o
```
path. Don't retry with
```
-f
```
on your own. On exit 1, 2 or 5: report the script's message as is (for 5, it says how to install the network-flow skill). On exit 4: see "Building".
Deliver. Give the absolute path and the
```
file://
```
URL. If the host can show or send files (a file card, a preview pane), use that too — for
```
--show
```
, that's the bundled file itself. Then describe how to use the page in a few lines:
- Tabs: Overview, one tab for each scrolls command, and New session (how a fresh agent session follows
```
AGENTS.md
```
  /
```
CLAUDE.md
```
  →
```
SCROLLS.md
```
  →
```
STARTER.md
```
  ).
- Each command tab plays its steps automatically, with a callout next to the file being touched; the callout's ‹ › buttons step and pause.
- Keyboard:
```
→
```
  /
```
←
```
  step,
```
Home
```
  /
```
End
```
  first/last step,
```
[
```
```
]
```
  or
```
Shift
```
  +arrows switch tabs, digits jump to a tab,
```
Space
```
  /
```
P
```
  pause,
```
R
```
  replay,
```
?
```
  shows every shortcut,
```
Esc
```
  closes or clears.
- Click a block to see what it is and trace its connections.
- The page is fully offline: no network requests, nothing to install.
Questions about a command that go beyond what the page shows (exact flags, edge cases): point the user at
```
/scrolls-help
```
, which holds the canonical reference. Don't describe behavior the page and
```
/scrolls-help
```
don't state.

Building

--build

reads the

scrolls-*

skills next to this one (or in

--skills-dir

) and regenerates the page from them. It decides these things from the skills on its own:

Tabs. One per skill. A skill whose
```
SKILL.md
```
was renamed to
```
SKILL.md.deprecated
```
,
```
.deactivated
```
or
```
.inactive
```
(the family's convention for switching a skill off) loses its tab and its blocks.
Version. The family's lockstep version, stamped on the page.

The words on each tab are hand-written in

assets/explainer-graph.json

, so the build records a fingerprint of each

SKILL.md

(its version line left out) and stops with exit 4 when something needs a person. Handle each message like this:

"SKILL.md changed since the page was last reviewed: …" — read each named skill's
```
SKILL.md
```
(and its
```
CHANGELOG.md
```
's newest entries), and compare them with that skill's tab: its scenario's
```
steps
```
(each a
```
title
```
and
```
text
```
) and its block's
```
kind
```
,
```
sub
```
and
```
detail
```
in
```
assets/explainer-graph.json
```
. Edit only what the skill no longer does or now does differently; keep the existing tone (one or two plain sentences per step). Then run
```
--build --reviewed
```
. If nothing needed editing,
```
--build --reviewed
```
alone is right. Tell the user which tabs you changed.
"no tab for /scrolls-…" — a new scrolls skill. Draft its tab from its
```
SKILL.md
```
: a node with id = the name without
```
scrolls-
```
, edges to the files it touches (reuse the existing node ids), and a scenario with that same id, labelled
```
/scrolls-…
```
, with 2 to 10 steps. Add the node to each of the
```
wide
```
/
```
medium
```
/
```
narrow
```
layouts in a free cell. Show the user what you added, then run
```
--build --reviewed
```
.
"versions differ (lockstep)" or "…: not found" — don't fix these in the explainer. Report them: the family's versions must be bumped together, and a missing skill must be installed (a tab drops only when the skill is deactivated as above).

After a successful

--build

, report what it printed: the skills it read, any tab it dropped, and whether the page changed (

wrote …

) or already matched (

unchanged …

Examples

Worked examples of

/scrolls-explainer

are in

assets/EXAMPLES.md

. Read that file only when you need it, for example to check what the script prints when a file is already there or a build needs a review.

Development

See

meta/MAINTAINERS.md

for how the page is put together (the network-flow renderer,

scripts/page_enhance.py

) and how to run the

tests/

suite. Neither is read as part of carrying out a

/scrolls-explainer

request — don't act on

meta/

tests/

while answering one.

scrolls-explainer

NPX Install

Tags

SKILL.md Content