사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/sugatoray/aiskills --skill scrolls-explainer시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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.-owrites only the page, at the path given, and never overwrites a different existing file unless the user asked (-f).--buildwrites only this skill's ownassets/scrolls-explainer.htmland, 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: 0 done (or already up to date), 1 the bundled page is missing or a file can't be written, 2 usage error, 3 a different file is in the way (no -f), 4 --build stopped because the skills need attention, 5 --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
-fonly when the user asked to replace an existing page, or the
script already refused and the user then confirmed.
- Add
--openwhen 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/Endfirst/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.mdwas 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/ or tests/ while answering one.