sugatoray/aiskills

scrolls-explainer

Shows, copies or rebuilds scrolls-explainer.html: an interactive, offline page that explains how the scrolls skill family works (/scrolls-setup, /scrolls-update, /scrolls-hide, /scrolls-unhide, /scrolls-remove, /scrolls-restore, /scrolls-help) — one tab per…

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/sugatoray/aiskills --skill scrolls-explainer

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

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

FlagMeaning
(none), --showThe 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 PATHCopy 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, --forceWith -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.
--openWith -o: also open the copy in the default browser.
--buildRegenerate 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.
--reviewedWith --build only: the tabs of the skills whose SKILL.md changed have been checked; record their new fingerprints, then build.
--skills-dir DIRWith --build only: where the scrolls-* skills are. Default: the folder this skill is in.
--versionPrint the page's version (scrolls-explainer X.Y.Z) and exit.
-h, --helpPrint 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

  1. 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.

  1. 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.

  1. 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://….

  1. 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".

  1. 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.
  1. 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/ or tests/ while answering one.

z tego samego repozytorium

Więcej Skills

Wszystkie Skills
sugatoray
Społeczność

create-lib-docs

Writes top-grade, verified user documentation for a library, CLI or framework as a folder of Markdown pages plus SVG diagrams, structured the way FastAPI, Pydantic, DuckDB and Effect structure theirs: a landing page with a 30-second example, Getting Started, a progressive Tutorial with runnable steps, task-oriented How-to Guides, Concepts (explanations with diagrams), an exhaustive Reference (CLI flags, API, config, output schemas, one anchor per error with cause and fix), FAQ/troubleshooting, a

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
18 lis
sugatoray
Społeczność

dynamic-promo-video

Build a short narrated promo/intro video (HTML scenes, zoom/tilt, voiceover, music) for a library, app or product. Use for explainer or launch videos made from code, real screenshots and TTS.

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
18 lis
sugatoray
Społeczność

meeting-agenda

Turn a meeting agenda into a self-contained HTML slide deck with a countdown timer per item: one slide per item (large 01, 02… number, title, optional sub-points), a ring timer that turns amber in the last 20% and red with a +M:SS count-up past zero, a footer with clickable progress dots and a per-item meeting progress bar, and a built-in editor (gear button) that saves to localStorage or downloads an updated copy. Use when the user invokes /meeting-agenda, or asks for agenda slides, a timed age

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
18 lis
sugatoray
Społeczność

scrolls-compact

Compacts the history in a docs/.scrolls/ (or docs/scrolls/) project-memory system at a point in time, and saves a git checkpoint of everything it condenses. Condenses the parts of SPEC.md, PLAN.md, HANDOFF.md, GAPANALYSIS.md and GAPCONTEXT.md that git blame shows are older than a compaction base — by default the newer of 7 days ago and the 20th-latest first-parent commit on main/master — while open tickets, open gaps and HANDOFF's open threads always stay word for word. Records ONE commit whose

Instalacje / 1h
2
GitHub Stars
4
Aktualizacja
18 lis