scrolls-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scrolls explainer

Scrolls 讲解器

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.

此 skill 提供一个自包含的 HTML 页面，以可视化方式讲解 scrolls skill 系列。该页面已预先构建并随附于

assets/scrolls-explainer.html

。共有三种模式：

/scrolls-explainer
或
--show
（两者效果相同）：在原地打开该页面，不复制任何内容。
-o PATH
：将页面复制到用户所需的文件或文件夹。
--build
：根据与当前 skill 相邻的
```
scrolls-*
```
skills 重新生成页面，使其与这些 skills 的现状保持一致。

范围说明： 此 skill 绝不会读取、检查或修改用户的 scrolls memory（
docs/.scrolls/
、
SCROLLS.md
、
CLAUDE.md
、
AGENTS.md
）。默认模式（
--show
）不写入任何内容。
-o
只会将页面写入指定路径，除非用户明确要求（使用
-f
），否则绝不会覆盖该位置上已有的不同文件。
--build
只会写入此 skill 自己的
assets/scrolls-explainer.html
；在配合
--reviewed
时（或添加缺失的标签页后），还会写入
assets/explainer-graph.json
，绝不会写入此 skill 文件夹之外的内容。

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

脚本以两种行为一致的形式提供：

explain.sh

（bash——适用于 macOS、Linux，或安装了 Git Bash/WSL 的 Windows）和

explain.ps1

（PowerShell 7+——适用于 Windows，或安装了

pwsh

的 macOS/Linux）。两者都是

explain.py

（仅使用标准库的 Python 3.9+）的轻量启动器，会依次查找并使用

python3

和

python

。应根据实际可用的环境选择启动器：先尝试

bash --version

；如果成功，则使用

.sh

；否则通过

pwsh

使用

.ps1

（首选），仅当

pwsh

不可用时才使用 Windows 内置的

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.

参数	含义
(无)、 `--show`	默认模式。不复制任何内容：打印内置 `assets/scrolls-explainer.html` 的路径和 `file://` URL，并在默认浏览器中就地打开。如果无法打开浏览器（远程或无头机器），这只会显示一条提示，不视为错误。 `--show` 不能与 `-o` 组合使用。
`-o` 、 `--output PATH`	改为将页面复制到此路径。文件路径按原样使用；如果目标是现有文件夹（如 `.` ），或路径以 `/` 结尾，则在其中放入 `scrolls-explainer.html` 。缺失的文件夹会自动创建。
`-f` 、 `--force`	仅可与 `-o` 一起使用：覆盖该路径上已有的不同文件。未指定此参数时，脚本会拒绝操作（退出码 3），不做任何更改。如果文件内容完全相同，则只会报告其已是最新状态。
`--open`	与 `-o` 一起使用：同时在默认浏览器中打开副本。
`--build`	根据与当前 skill 相邻的 `scrolls-*` skills 重新生成 `assets/scrolls-explainer.html` （见下文“构建”）。单独使用时只进行重新构建；可添加 `--show` 打开结果，或添加 `-o` 同时复制页面。
`--reviewed`	仅可与 `--build` 一起使用：相关 skills 中 `SKILL.md` 发生变化的标签页均已检查；记录新的 fingerprints 后再进行构建。
`--skills-dir DIR`	仅可与 `--build` 一起使用：指定 `scrolls-*` skills 所在目录。默认为当前 skill 所在的文件夹。
`--version`	打印页面版本（ `scrolls-explainer X.Y.Z` ）并退出。
`-h` 、 `--help`	打印用法并退出。

退出码：

表示完成（或已是最新状态），

表示内置页面缺失或无法写入文件，

表示用法错误，

表示目标位置已有不同文件且未提供

-f

，

表示

--build

因相关 skills 需要人工处理而停止，

表示

--build

找不到 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.

根据请求选择模式。
- 仅输入
```
/scrolls-explainer
```
  、使用
```
--show
```
  ，或提出“给我看看”“打开它”“让我看看讲解器”等请求时：显示内置页面（不附加任何 flags）。这是默认模式：除非用户要求，否则不要将页面复制到任何位置。
- 用户提出“重新构建”“重新生成”“更新讲解器”“让页面与 skills 保持一致”等请求时：使用
```
--build
```
  （然后遵循“构建”部分）。
- 用户需要自己的文件（保存、导出、放入
```
docs/
```
  、给我一份副本、
```
-o …
```
  ）时：使用
```
-o
```
  复制页面。
需要副本时，选择路径。
- 用户指定了文件或文件夹：通过
```
-o
```
  传入该路径。
- 用户要求将副本放在“这里”或未指定位置：使用
```
-o .
```
  ，在当前目录中写入
```
./scrolls-explainer.html
```
  。如果宿主环境提供了专门用于存放用户可打开文件的目录（输出目录或临时目录），而当前目录是用户未要求写入的项目目录，则应改用该目录，避免页面被擅自放入用户的源代码树中。
- 仅当用户明确要求替换已有页面，或脚本已拒绝操作且用户随后确认时，才添加
```
-f
```
  。
- 当用户还希望打开副本且机器有图形显示环境时，添加
```
--open
```
  。

从相对路径所基于的目录运行脚本：

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…

显示页面时会输出

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

和

open: file://…

。复制页面时会输出

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

（或

… is already up to date

），随后输出

open: file://…

。

遇到退出码 3（目标位置已有不同文件）时：告知用户，并提供使用
```
-f
```
或选择其他
```
-o
```
路径的选项。不要自行重试并添加
```
-f
```
。遇到退出码 1、2 或 5 时：原样报告脚本消息（退出码 5 的消息会说明如何安装 network-flow skill）。遇到退出码 4 时：参见“构建”部分。
交付。 提供绝对路径和
```
file://
```
URL。如果宿主环境能够展示或发送文件（文件卡片、预览面板等），也应使用这些方式；对于
```
--show
```
，展示的就是内置文件本身。然后用几行说明如何使用该页面：
- 标签页：包括 Overview、每个 scrolls 命令对应的标签页，以及 New session（介绍新的 Agent 会话如何依次读取
```
AGENTS.md
```
  /
```
CLAUDE.md
```
  →
```
SCROLLS.md
```
  →
```
STARTER.md
```
  ）。
- 每个命令标签页都会自动播放其步骤，并在所操作文件旁显示提示框；可通过提示框中的 ‹ › 按钮逐步浏览和暂停。
- 键盘操作：
```
→
```
  /
```
←
```
  逐步浏览，
```
Home
```
  /
```
End
```
  跳至第一步/最后一步，
```
[
```
```
]
```
  或
```
Shift
```
  +方向键切换标签页，数字键跳至指定标签页，
```
Space
```
  /
```
P
```
  暂停，
```
R
```
  重新播放，
```
?
```
  显示所有快捷键，
```
Esc
```
  关闭或清空。
- 点击任意 block，即可查看其含义并追踪相关连接。
- 页面完全离线运行：不会发起网络请求，也无需安装任何内容。
对于超出页面展示范围的命令问题（精确 flags、边缘情况）：将用户引导至
```
/scrolls-help
```
，其中包含权威参考。不要描述页面和
```
/scrolls-help
```
均未说明的行为。

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 …

--build

会读取与当前 skill 相邻的

scrolls-*

skills（或

--skills-dir

指定的 skills），并根据它们重新生成页面。它会根据 skills 自行确定以下内容：

标签页。 每个 skill 对应一个标签页。如果某个 skill 的
```
SKILL.md
```
已被重命名为
```
SKILL.md.deprecated
```
、
```
.deactivated
```
或
```
.inactive
```
（这是该系列停用 skill 的约定），其标签页和相关 block 会被移除。
版本。 使用整个系列保持同步的版本号，并将其标记在页面上。

每个标签页上的文案均手写于

assets/explainer-graph.json

。构建过程会记录每个

SKILL.md

的 fingerprint（不包括版本行），当有内容需要人工处理时，以退出码 4 停止。请按以下方式处理每条消息：

SKILL.md changed since the page was last reviewed: …
——读取每个相关 skill 的
```
SKILL.md
```
（以及其
```
CHANGELOG.md
```
中最新的条目），并将其与该 skill 的标签页进行比较：检查 scenario 的
```
steps
```
（每项包含
```
title
```
和
```
text
```
）以及 block 的
```
kind
```
、
```
sub
```
和
```
detail
```
，这些内容位于
```
assets/explainer-graph.json
```
中。仅修改 skill 已不再执行或现在行为有所变化的部分；保持现有语气（每个步骤使用一到两句平实的话）。然后运行
```
--build --reviewed
```
。如果无需修改，直接运行
```
--build --reviewed
```
即可。告知用户修改了哪些标签页。
no tab for /scrolls-…
——这是一个新的 scrolls skill。根据其
```
SKILL.md
```
起草标签页：创建一个 node，其 id 为移除
```
scrolls-
```
前缀后的名称；添加指向该 skill 所操作文件的 edges（复用现有 node ids）；再创建一个使用相同 id、标记为
```
/scrolls-…
```
的 scenario，其中包含 2 到 10 个步骤。在
```
wide
```
/
```
medium
```
/
```
narrow
```
layouts 的空闲单元格中分别添加该 node。向用户展示新增内容，然后运行
```
--build --reviewed
```
。
versions differ (lockstep)
或 …: not found
——不要在讲解器中修复这些问题。直接报告：该系列的版本必须同步升级，而缺失的 skill 必须先安装（只有 skill 按上述方式停用时，标签页才会被移除）。

--build

成功后，报告其输出内容：读取了哪些 skills、是否移除了任何标签页，以及页面是否发生变化（

wrote …

）或原本就已匹配（

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.

/scrolls-explainer

的实际示例位于

assets/EXAMPLES.md

。仅在需要时读取该文件，例如需要确认文件已存在时脚本的输出，或构建过程需要审查时的行为。

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.

有关页面的构成方式（network-flow renderer、

scripts/page_enhance.py

）以及如何运行

tests/

测试套件，请参阅

meta/MAINTAINERS.md

。处理

/scrolls-explainer

请求时不会读取这些文件——回答请求时不要对

meta/

或

tests/

执行任何操作。