Skip to content
/ghost-cursor

Agent skill

ghost-record is a skill for coding agents such as Cursor and Claude Code. You type one sentence about a component, and you get back a recorded, checked take and the snippet that embeds it. The agent doesn’t ask you anything unless it can’t find the component.

Install

Copy skills/ghost-record from this repository into your agent’s skills folder, then add the two tools its script runs on.

cp -r skills/ghost-record .cursor/skills/      # Cursor
cp -r skills/ghost-record ~/.claude/skills/    # Claude Code
npm i -D playwright tsx
npx playwright install chromium

It works in Next.js projects that use @imuratalpay/ghost-cursor. In other setups, give it a page that already renders the component inside a <GhostReplay>.

Use it

Name the component, then say what the cursor should do, in order.

/ghost-record filter list: type "to", then pick Tooltip

The agent finds FilterList, reads it, and turns the sentence into four steps. Then it runs the skill’s script once. This is what that run printed on this site:

Output
→ FilterList from apps/site/components/demos/filter-list.tsx
  recording where it's embedded: /docs/examples (apps/site/app/docs/examples/page.tsx:54)
  using the dev server already running at http://localhost:3001
  take 1 of 3
✓ take 4 steps · 4.0s · 2 presses · 1.7 KB
✓ replay matches the live run
  saved apps/site/components/demos/filter-list.take.json

apps/site/app/docs/examples/page.tsx:54 already embeds FilterList. Swap its recording for the new take, or paste this where you want another copy:

import { GhostReplay } from "@imuratalpay/ghost-cursor";
import { FilterList } from "@/components/demos/filter-list";
import filterListTake from "@/components/demos/filter-list.take.json";

<GhostReplay recording={filterListTake} style={{ height: 300 }}>
  <FilterList />
</GhostReplay>
Nothing picked yet
0.0s
The take that sentence produced, embedded with the printed snippet.

What the script does

  1. Looks for a page where the component sits directly inside a <GhostCursor> or <GhostReplay>. If there isn’t one, it mounts the component alone on a temporary /ghost-stage route.
  2. Uses the dev server that’s already running for the app, or starts one.
  3. Records the steps through the dev-only recorder with real mouse and keyboard input. Paths curve and ease, long moves overshoot slightly, and typing runs at 65 to 160ms per key.
  4. Replays the take with Preview and compares the component’s final DOM with the live run. Text that changes on its own, like a clock, is left out. If they differ, it records again, slower, up to three times.
  5. Saves <component>.take.json next to the component and prints the snippet. It never overwrites a take that a page already imports.
  6. Deletes the temporary route and stops the dev server, if it started one.

Defaults

SettingDefault
Box height320px on the temporary route, otherwise the embed’s height
PropsNone. The agent passes --props when the component needs them.
Output<component>.take.json next to the component
Tries3, at full speed, then 85%, then 75%
ServerThe one in .next/dev/lock, then ports 3000 to 3003, then a new one

The skill’s SKILL.md lists what each failure means. The most common one is a step that aims at an element before an earlier step has opened it.