Mouse Trail Masking Reveal

Reusable Agent Skills for building soft mouse/cursor-trail masking reveal effects on websites.

This repository packages the Mouse Trail Masking Reveal workflow as two portable skills:

  • image-layer-alignment-validator: checks whether two raster layers are spatially compatible before using them in reveal, before/after, morph, or mask-compositing effects.
  • cursor-reveal-hero: builds, repairs, tunes, and validates a canvas-based soft cursor-trail reveal hero effect.

The skills are intentionally provider-neutral. They use the open SKILL.md Agent Skills pattern and include provider adapter notes for Codex, Claude Code, Gemini CLI, Kimi Code CLI, Qwen Code, GLM-based coding agents, and generic LLM coding assistants.

Demo

Demo by @sergekost:

Mouse Trail Masking Reveal demo

Watch on YouTube: youtu.be/BppodCPasDc.

Full-quality MP4: media/sergekost-cursor-reveal-demo.mp4.

Why This Exists

The idea came after seeing a manual Figma workflow by @thedesignely. That post demonstrated the design direction manually in Figma. This package turns the same kind of visual workflow into reusable LLM-agent skills for website work: first validate image-layer alignment, then build the interactive cursor reveal implementation.

Repository Layout

mouse-trail-masking-reveal/
├── skills/
│   ├── image-layer-alignment-validator/
│   └── cursor-reveal-hero/
├── adapters/
│   ├── codex/
│   ├── claude-code/
│   ├── gemini-cli/
│   ├── kimi-code-cli/
│   ├── qwen-code/
│   ├── glm-agents/
│   └── generic-agent/
├── docs/
├── media/
└── scripts/

Quick Start

Install the two canonical skills into the location your agent scans:

mkdir -p .agents/skills
cp -R skills/image-layer-alignment-validator .agents/skills/
cp -R skills/cursor-reveal-hero .agents/skills/

Then ask your coding agent:

Use $image-layer-alignment-validator to compare my base and reveal images.
Then use $cursor-reveal-hero to build the interactive cursor trail reveal hero.

Demo Media

  • media/sergekost-cursor-reveal-demo.mp4: demo by @sergekost.
  • media/sergekost-cursor-reveal-demo-preview.gif: README preview by @sergekost.
  • YouTube demo: youtu.be/BppodCPasDc.
  • media/thedesignely-figma-manual-reference.mp4: reference video attributed to @thedesignely.

See docs/media-and-attribution.md before redistributing the videos.

Provider Support

See docs/provider-matrix.md and the adapters/ folder.

The short version:

  • Codex: use .agents/skills/ or a user/admin skill location.
  • Claude Code: use filesystem-based custom skills.
  • Gemini CLI: use .gemini/skills/ or .agents/skills/.
  • Kimi Code CLI: use .kimi/skills/, .agents/skills/, or another configured skills directory.
  • Qwen Code: use .qwen/skills/ or project/user skill locations.
  • GLM agents: use the Agent Skills folder in the host agent, such as Claude Code, OpenCode, OpenClaw, AutoClaw, or another GLM-powered coding shell.
  • Generic agents: paste or mount the SKILL.md folders as task-specific instructions with scripts/resources available.

Requirements

For image-layer-alignment-validator:

  • Python 3
  • Pillow
  • numpy
  • opencv-python

For cursor-reveal-hero smoke checks:

  • Node.js
  • Playwright

The skills themselves are Markdown-first and can still guide an agent without these dependencies; the scripts need them for deterministic checks.

Privacy

This package contains no API keys, tokens, credentials, or machine-specific paths. Scripts run locally by default. See PRIVACY.md and SECURITY.md.

License

Code and skill text are released under the MIT License. Third-party media may have separate rights; see docs/media-and-attribution.md.