Scrollcraft Skill for Hermes Agent: Scroll-Driven Landing Pages

Scrollcraft is an optional Hermes Agent skill that turns a landing page into a scroll-driven timeline, where the wheel acts as a scrubber and each section is a distinct beat in a film. It is for people who want a site that feels like an experience rather than a document, and who are willing to answer a structured interview before any code is written. The skill ships as version 1.0.0 under the MIT licence, authored by nateherkai (upstream scroll-craft) and ported by Hermes Agent, with support for linux, macos, and windows.

What it does

Scrollcraft produces a complete package, not just a page. The output includes an interview brief, a page grammar, a customer-journey map, a feeling curve with one engineered peak, a scroll score, a signature move, assets, a real HTML page built on a token-driven design floor, and a strip of screenshots proving the page holds up at every scroll position.

Reach for it when the request is "scrollytelling", "scroll animation site", "a site where scrolling plays a video", "Apple-style landing page", "3D scroll world", "make my brand a scroll experience", "this looks like a template", or any brief that calls for a site that should feel like an experience rather than a document.

The skill is opinionated about what it is not. It is not "generate a flythrough and drop text on it", because that produces one device applied to a whole page, recognisable at a glance. Four spine rules keep the result from collapsing into a template:

Variety is the product. At least four device families, never the same device twice in a row. Read references/devices.md.
The world is photographic unless the brand is genuinely illustrated. Clay/low-poly diorama is banned as a default. Read references/worlds.md.
No continuous chain unless the brief is literally "one continuous journey" (then see references/worldflight.md).
A different world is not a different page. Structure is a separate axis; decide it deliberately. Read references/uniqueness.md.

Before you start

Scrollcraft is an optional skill, installed on demand. Its path is optional-skills/web-development/scrollcraft. The skill runs on linux, macos, and windows.

The bootstrap step expects Node.js and a full ffmpeg build. The source warns that distro-stripped ffmpeg reports missing filters as command syntax errors, which is why the preflight script exists: run it rather than checking by hand.

If you plan to use the optional kie.ai asset path, you need the KIE_AI_API_KEY environment variable exported in your shell. There is no bundled env file in this port, and the path requires paid credit.

For verification, scripts/shoot.mjs needs Playwright (npm install playwright or playwright-core plus a Chrome install). Hermes' browser_exec tool is the lighter alternative for scroll-screenshot verification: serve the build, scroll in steps, capture screenshots, and inspect them yourself.

Step 0: The interview

Always ask the user in chat before building anything. The skill is explicit that this means real questions, asked and answered in the conversation, written down, not a brief inferred from the brand name. Eight questions in one pass:

Vibe in three to five words, plus up to three references from any medium (film, album cover, shop, magazine, game, not "sites you like").
The scroll journey, section by section, in their words.
The energy curve: where calm, where intense.
How should someone feel while scrolling, stage by stage, and what is the ONE moment they should remember? This becomes the feeling curve and the peak. See references/feel.md.
One thing this site should do that no site they have seen does: the seed of the signature move.
How far from premium-minimal? Offer the range in references/uniqueness.md §5: brutalist, maximalist, playful, retro, dense, editorial, premium-minimal.
One unbroken world, or distinct scenes? The biggest structural fork, and it is their call.
What assets do they already have? Footage, photos, product shots, brand kit. "Nothing" is fine and means a fully generated world.

Write the answers verbatim into /builds//BRIEF.md (use write_file) before any act planning. BRIEF.md must contain the eight answers, the feeling curve (one line per act: emotion, then cause), the peak (as the sentence a visitor would say to a friend), the completed "It's the site where ___" sentence, and any authored silence. If the user is genuinely unreachable in a fully autonomous run, self-author BRIEF.md, mark it Self-authored, not interviewed, and say so in the report.

Bootstrap

Run the preflight rather than checking by hand. The source notes it catches a stripped ffmpeg that reports missing filters as syntax errors:

node <skill>/scripts/doctor.mjs
node <skill>/scripts/workspace.mjs --ensure   # prints workspace, seeds registry

Workspace resolution order: SCROLLCRAFT_HOME env var; nearest .scrollcraft.json ({ "workspace": "..." }) walking up from cwd; /scrollcraft. Builds live at /builds//, the fingerprint registry at /FINGERPRINTS.md (seeded from templates/FINGERPRINTS.md, starts empty, and the gate stops you repeating yourself).

Copy engine/scrollcraft.js and engine/scrollcraft.css into the build folder. Never edit the engine per-project. Theme with tokens; write your own markup. Bespoke behaviour is bespoke JS in the page, driven off --sc-p and your own data-sc-* attributes.

Step 1: The brief, journey first

Ask the subject open, in plain prose. Then ask only what Step 0 did not cover: what is this and who is it for; the one sentence the page installs; the one next action (one label, used everywhere); what they already have; art direction from references/worlds.md. Then write the journey: four to seven beats, each a shift in what the visitor knows or feels. Beats are the spine; a section serving no beat is cut. Confirm the journey with the user before generating assets, because assets are the expensive part.

Step 2: Grammar, gate, then score

Full detail in references/uniqueness.md.

Pick a grammar. Eight, mutually exclusive. Choosing filmic one-shot means saying in the report why the other seven lost. Nav, hero and close follow from the grammar.
Invent the signature move. One bespoke interaction coded in the page, not a parameter change to a kit device. Interview question 5 is the seed.
Run the fingerprint gate. The planned build must differ from every row in /FINGERPRINTS.md on at least 4 of 6 dimensions: grammar, nav treatment, hero device, act-sequence shape, close pattern, signature move. If it fails, change the plan, not the log.
Write the feeling curve before the score table (method: references/feel.md). Then assign each beat a device in a written table (beat / device / why).

Checks before building: grammar bans hold; 4+ device families; no device twice in a row; at most two scrub acts; no two adjacent acts with the same feeling; one peak with the largest span; total page length 8, 14 viewport-heights.

Step 3: Assets

Full pipeline, prompt scaffolds and model notes: references/assets.md.

Hermes-native paths first:

User-supplied footage and photos: no key, no spend, a first-class route. Grade and encode them.
The image_generate tool for stills: one style preamble reused verbatim in every prompt is what makes six images look like one shoot. Inspect every asset (vision_analyze) before use; rerolling beats shipping a bad frame.

Optional upstream path, kie.ai (vendored verbatim as scripts/kie.mjs): photoreal stills and camera-move clips. Requires the KIE_AI_API_KEY environment variable (export it in your shell; there is no bundled env file in this port). Check balance with node /scripts/kie.mjs probe; a still costs cents, a 5s clip more.

node <skill>/scripts/kie.mjs still "<style preamble>\n\n<scene>" out/01-hero.png --ar 16:9
node <skill>/scripts/kie.mjs shot  "<camera move>" out/01-hero.png out/01.mp4 --dur 5
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile

Encode for scrubbing, not playback. encode.sh sets a dense GOP because seeking walks from the previous keyframe; a normal web encode scrubs like mud. It also strips audio.

Step 4: Build the page

Write real HTML: real markup, real reading order. The engine reads data-sc-* attributes off your markup and drives it; it never generates DOM. Start from references/template.html. Device patterns: references/devices.md. Spacing, type, depth, colour: references/taste.md, read it before writing markup. Theme by overriding tokens, six values and two fonts:

:root {
  --sc-canvas: #0A0806;  --sc-surface: #16110E;
  --sc-ink:    #F5EBDD;  --sc-ink-soft: #A2968A;
  --sc-accent: #FF5A3D;  --sc-accent-ink: #15110F;
  --sc-font-display: "Archivo", system-ui, sans-serif;
  --sc-font-text:    "Geist", system-ui, sans-serif;
}

Step 5: Verify by scrolling it

Not optional. Every scroll position is a different frame; failures live between the two you looked at. Full procedure: references/verify.md.

cd <build project> && npm i playwright-core     # once
node <skill>/scripts/serve.mjs --root . --port 4500 &
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion

The harness walks each act at six positions, waits for scrub video to settle, reports dead scroll, cues that never reach full opacity, and composited contrast; it writes a contact sheet. Then read sheet.png yourself (vision_analyze), because the harness proves a clip advances, not that the page means anything. Run the feel check (references/feel.md §6): scroll cold, one word per act, diff against BRIEF.md. Where they disagree the page is wrong, not the brief.

A green run does not cover a real phone (video decoder, autoplay policy, Low Power Mode). On any reported mobile defect, deploy references/device-diag.html beside the site on the first round and let the device answer.

When not to use it

The source does not offer a list of alternatives, but it does draw a clear boundary around what Scrollcraft is not. It is not a flythrough generator with text dropped on top, and it is not a template. If the brief is a document rather than an experience, or if the user cannot answer the interview questions, the skill's own rules will push back. The four spine rules also rule out a continuous chain unless the brief is literally "one continuous journey", and they rule out clay or low-poly diorama as a default world.

Limits and gotchas

The source lists several pitfalls worth reading before you start:

scripts/shoot.mjs needs Playwright (npm install playwright or playwright-core plus a Chrome install). Hermes' browser_exec tool is the lighter alternative for scroll-screenshot verification: serve the build, scroll in steps, capture screenshots, and inspect them yourself.
scripts/kie.mjs needs KIE_AI_API_KEY and paid credit; prefer image_generate or user assets when the budget is unclear.
encode.sh and doctor.mjs expect a full ffmpeg build; distro-stripped ffmpeg reports missing filters as command syntax errors, so run scripts/doctor.mjs first.
Upstream script invocations above are copied from upstream docs and unverified by this port beyond node --check syntax validation; trust --help/source if drifted.
The upstream repo ships worked examples and a change log that are not vendored in this port; see the upstream repository if you want them.

The hard rules are ship-blockers, and they are worth reading as a checklist: no clay diorama default; no "scroll to explore" cues or animated mouse icons; no 01 / 06 section counters; at most one eyebrow per three sections; no visible em dashes; vary the copy anchor; no device twice in a row; never build before the interview; one engineered peak, not zero or three; the close resolves instead of fading to a footer; curve before devices; one bespoke signature move; 4-of-6 fingerprint clearance against every row; never edit the engine; no full-frame dark overlay for contrast (scrim only where text sits); no text baked into images; no invented statistics; no transition: all or animating width/height/top/left (transform/opacity; clip-path for wipes); no gradient text or neon glow; no audio on scrub clips; never ship without Step 5.

What pairs with it

Scrollcraft sits inside the web-development category of optional Hermes Agent skills. Its own references point outward to the upstream scroll-craft repository, which ships worked examples and a change log that are not vendored in this port. Within Hermes, the image_generate tool and vision_analyze are the native asset and inspection paths, and browser_exec is the lighter alternative to Playwright for scroll-screenshot verification. The skill's own reference files, devices.md, worlds.md, uniqueness.md, feel.md, assets.md, taste.md, and verify.md, are the working companions to read alongside it.