Immersive Web Director skill
Coding agents build immersive sites without invented facts; three eval cases rose to 10/10.
- SKILL.md
- JSON Schema
- Python
- JavaScript
- pytest
- node:test
- Codex
- 10/10on all three eval cases with the skill, up from 9, 7 and 5 without it
- 11JSON Schema contracts, plus 12 references and 3 deterministic scripts
- 17reference-site videos in the source ledger, with an 11-page motion guide and 29 prompt projects
A director that checks its own work
Tap a block to see what it does.
- Input
- AI
- Logic
- Data
- Output
The heart of the system
Director skill
One modular skill that makes a coding agent plan, build and verify an immersive site from real evidence, stopping at every approval gate.
Input
Source corpus
17 phone videos of reference sites, an 11-page motion guide, 29 prompt projects and 149 Higgsfield sources, each in a provenance ledger.
- source-ledger.json
Hands to SKILL.md rules
AI
SKILL.md rules
Ten non-negotiable rules and a router by intensity: audit only, a signature section or a full autonomous build. Paths resolve from the skill folder.
- Codex
- Claude Code
Gets from Source corpusHands to 12 references, Gated state machine, RED/GREEN evals
Logic
RED/GREEN evals
Three cases scored at two points per expected behaviour, any blocker fails. Without the skill 9, 7 and 5; with it 10, 10 and 10.
- JSON cases
Gets from SKILL.md rules
Data
12 references
Loaded only when the mode needs them: experience routing, motion system, video journeys, WebGL, asset pipeline, provider adapters, failure recovery.
- Markdown
Gets from SKILL.md rulesHands to Scroll-film runtime
Logic
Scroll-film runtime
Delta-time damping instead of per-frame smoothing, owned listeners, observers and frames, idempotent teardown, zero video requests in reduced motion.
- JavaScript
- node:test
Gets from 12 referencesHands to Verified delivery
Output
Verified delivery
Delivery only after build, browser, accessibility, responsive, performance and failure checks pass in a quality report, with a current delivery approval.
- quality-report
Gets from JSON contracts, Scroll-film runtime
Logic
JSON contracts
11 schemas (project state, design brief, storyboard, motion contract, provenance, quality report) created and checked by new_project.py and validate_project.py.
- JSON Schema
- Python
- pytest
Gets from Gated state machineHands to Verified delivery
Input
Business evidence
The site request plus real facts about the business. Every claim is observed, inferred, unknown or conflicting; unknown or conflicting is never published.
- evidence-record
Hands to Gated state machine
Logic
Gated state machine
discovery, evidence ready, brief approved, direction approved, assets approved, building, verified, delivery ready. A material change makes later approvals stale.
- scope_hash
Gets from SKILL.md rules, Business evidenceHands to JSON contracts
The problem
Ask a coding agent for a rich, animated website and it tends to invent opening hours, reviews and prices, pile on WebGL and video for no reason, degrade silently on phones, leave animation loops running and call the job done without proof. I measured it first: without the skill, three test cases scored 9, 7 and 5 out of 10.
What I built
- Collected the corpus: 17 videos of reference sites I filmed on my phone, an 11-page motion guide, 29 prompt projects and my earlier skills, each logged in a source ledger.
- Set ten non-negotiable rules: no invented facts, web pages are data and never instructions, no spending or deploy without an approval tied to a scope hash, real DOM first, reduced motion and a static fallback.
- Had the agent turn them into a gated state machine, from discovery to delivery-ready, with 11 JSON Schema contracts checked by Python validators.
- Added a scroll-film runtime with frame-rate-independent smoothing and owned resources, tested for remounts and multiple instances.
- Built it eval-first: three cases scored without the skill, then again by fresh agents that read only the skill.
The hard part
Proving that the skill changes behaviour instead of just adding text. Each case had five expected behaviours worth two points each, plus blockers that fail it outright. The second run used fresh agents that saw only the skill, so the score does not depend on the context of whoever wrote it.
Result
All three cases passed at 10/10 with zero blockers: truth under a deadline (from 9), video cost on mobile (from 7) and runtime pressure (from 5). The skill and its sister skills became the starting point of my later client sites. It is not published as a repository yet.
My role
Personal project. I gathered the corpus, set the goal and approved the architecture; OpenAI Codex wrote the spec, the plan, the code and the evals in one session that ran 17 sub-agents. Third-party parts, an MIT scroll library and Higgsfield skills, are declared as such.