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…

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/sugatoray/aiskills --skill scrolls-explainer

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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.

du même dépôt

Autres Skills

Tous les Skills
sugatoray
Communauté

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

Installations / 1h
2
GitHub Stars
4
Mis à jour
18 nov.
sugatoray
Communauté

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.

Installations / 1h
2
GitHub Stars
4
Mis à jour
18 nov.
sugatoray
Communauté

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

Installations / 1h
2
GitHub Stars
4
Mis à jour
18 nov.
sugatoray
Communauté

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

Installations / 1h
2
GitHub Stars
4
Mis à jour
18 nov.