nateherkai/scroll-craft installation guide

Installing `scroll-craft` on macOS Tahoe with Apple silicon

What this repository is

`scroll-craft` is an Agent Skill for designing and building premium, scroll-driven websites. It supplies Claude Code with a detailed design procedure, references, an unmodified shared scroll engine, templates, and verification scripts. The repository also packages that skill as the native Claude Code plugin `nateherk-design`, version 0.3.0.

**Claude Code classification:** **Claude extension**. Its primary mechanism is **context injection through an Agent Skill**: Claude Code reads `SKILL.md` and follows its workflow. The repository also provides script-backed verification and asset-processing tools that Claude can run with its allowed Bash and file tools. It is not a replacement for Claude Code and is not a standalone desktop application.

The plugin can help Claude plan a visitor journey, choose a page grammar, create a feeling curve and signature interaction, build semantic HTML, and inspect scroll states. It does not provide a finished website merely by being installed.

Important macOS warning

The author states that the project has **only ever been run on Windows**. Its scripts search common Windows, macOS, and Linux locations for Chrome and FFmpeg, and they support `SCROLLCRAFT_FFMPEG` and `SCROLLCRAFT_CHROME` overrides, but the supplied files do not claim that a complete build has been tested on a Mac.

Therefore, on macOS Tahoe and Apple silicon, treat installation as **supported by intended script behavior but not validated by the author**. Run the included doctor before starting work. If it reports a failure, do not silently work around it; address the named missing requirement first.

Before installing

You need:

• **Claude Code**, already installed and usable.
• **Node.js 18 or newer**, required by every repository script.
• **A full FFmpeg build**, required to encode video for responsive scroll scrubbing. The author warns that stripped FFmpeg builds may lack essential filters such as `scale`.
• **Chrome plus `playwright-core`**, required for the automated browser verification pass.
• Optionally, **`KIE_AI_API_KEY`** if you want the skill to generate visual assets through kie.ai. It is not needed when you use your own photos or footage.

The supplied repository files do not document macOS installation commands for Claude Code, Node.js, FFmpeg, or Chrome. To avoid giving you undocumented commands, this guide does not invent package-manager instructions for them. Install those prerequisites through their first-party distribution instructions, then let the repository’s doctor report whether they are visible.

No Intel-only setup or Rosetta requirement is documented. No Apple-silicon-specific binary is included in the supplied evidence.

Recommended installation: Claude Code plugin

Open Claude Code. Enter the following command **inside Claude Code**, not in the macOS Terminal:

/plugin marketplace add nateherkai/scroll-craft

After Claude Code adds the repository as a plugin marketplace, enter:

/plugin install nateherk-design

The plugin name comes from `plugins/nateherk-design/.claude-plugin/plugin.json`. Its manifest identifies version 0.3.0, the MIT license, and the repository homepage.

If the installation summary says `Run /reload-plugins to activate.`, enter:

/reload-plugins

Do not assume reloading is needed unless Claude Code displays that message.

Confirm that Claude Code can invoke it

In Claude Code, invoke the skill directly:

/nateherk-design:scroll-craft

You can also describe the website you want in ordinary language. The skill’s declared triggers include requests for a layered or cinematic hero, scrollytelling, an Apple-style landing page, a 3D scroll world, or a website where scrolling controls video.

A successful invocation should begin a design workflow rather than instantly generate a generic page. Unless you explicitly delegate creative direction, expect questions about the desired feeling, journey, energy, memorable moment, visual range, world structure, and available assets. The workflow records this information in a build-specific `BRIEF.md` before planning the page’s acts.

Obtain a local repository copy for preflight and development

The plugin commands are the simplest installation route, but the README’s first-run checks are documented from the **repository root**. Use the repository’s GitHub page:

<https://github.com/nateherkai/scroll-craft>

Clone or download it using GitHub’s interface. The README explicitly supports cloning or downloading, but it does not provide a shell cloning command, so none is invented here. If you download a ZIP, expand it in Finder.

Open Terminal with its working directory set to the expanded repository’s top-level folder—the folder containing `README.md` and `plugins`. Then run the documented preflight:

node plugins/nateherk-design/skills/scroll-craft/scripts/doctor.mjs
node plugins/nateherk-design/skills/scroll-craft/scripts/workspace.mjs --ensure

Run the doctor first. It checks Node, a full FFmpeg build, `playwright-core`, Chrome, the optional API key, and the resolved workspace. Required failures exit unsuccessfully. The README warns that this catches three misleading problems early: stripped FFmpeg builds, missing WebP muxing, and `playwright-core` resolving from the wrong directory.

The workspace command prints the selected workspace, creates it, and seeds its fingerprint registry. Workspace resolution uses the first applicable location:

1. `SCROLLCRAFT_HOME`.
2. A nearby `.scrollcraft.json` that declares a workspace.
3. A `scrollcraft` directory under the detected project root.

New builds go under `<workspace>/builds/<name>/`, and the uniqueness registry is `<workspace>/FINGERPRINTS.md`. An empty initial registry is expected.

If the doctor reports missing browser support

The repository requires `playwright-core` to be installed **in the website build folder**, not merely somewhere else on your Mac. Once the skill has created or selected that build folder, open Terminal in that folder and run the documented command:

npm i playwright-core

Then return to the repository root and run the doctor again:

node plugins/nateherk-design/skills/scroll-craft/scripts/doctor.mjs

The supplied files do not provide commands to install Chrome or a full FFmpeg build. If either is still missing, stop and install it using first-party instructions. The repository notes that environment overrides exist for unusual locations, but it does not provide a complete copy-paste command for setting either override, so this guide does not fabricate one.

Optional: run the local plugin checkout without installing it

For skill development or inspection, the README documents starting Claude Code from the repository root with the plugin directory loaded directly:

claude --plugin-dir ./plugins/nateherk-design

This is an alternative development route, not an additional step required after marketplace installation. Keep the complete skill folder intact, including `SKILL.md`, references, scripts, templates, and the engine.

Your first website session

Start Claude Code in the project where you want the website work performed. Invoke the skill directly:

/nateherk-design:scroll-craft

Then describe the brand, intended audience, desired visitor journey, one required action, available brand assets, and whether you want one continuous world or distinct scenes. If you want Claude to make creative decisions without repeatedly seeking approval, say so explicitly; the skill supports explicit creative delegation and records authored choices in `BRIEF.md`.

Using your own photos and footage needs no generation key and incurs no generation spend. If you choose generated assets, `KIE_AI_API_KEY` is required and the external service may charge for images or clips.

The skill should keep `engine/scrollcraft.js` and `engine/scrollcraft.css` unchanged per project. Project-specific design belongs in semantic HTML, design tokens, and bespoke page JavaScript driven by the engine’s published state.

Verification expectations

Installation is not the same as proving a generated site works. The skill’s workflow requires desktop, 390-by-844 mobile, and reduced-motion browser captures. It reports dead scroll, content that never reaches full opacity, composited contrast, and video clips that never advance. It also creates a contact sheet for visual review.

Even a green automated run does **not** verify actual iPhone behavior. The author specifically warns that headless Chrome cannot reproduce an iPhone’s video decoder, autoplay policy, Low Power Mode, or touch scrolling. Test the finished site on a real phone before publishing it.

Installation checklist

You are ready to begin when:

• Claude Code accepted the marketplace and plugin installation commands.
• `/nateherk-design:scroll-craft` invokes the skill.
• Node.js is version 18 or newer.
• The repository doctor reports required checks successfully.
• The workspace command prints and initializes a workspace.
• A full FFmpeg build, Chrome, and build-local `playwright-core` are available.
• You understand that macOS Tahoe and Apple silicon have not been validated by the repository author.

The project is MIT-licensed. Keep in mind that it is intentionally opinionated: it rejects several common AI-site patterns and requires briefing, visual differentiation, accessibility-minded markup, and scroll-state verification before delivery.