Create Hook

Create Hook

Type: Utility skill (procedural, no agentic lead or sub-agents).

Adds a Cursor lifecycle hook: a script that runs when a specific agent event fires. Hooks are project-level only (.cursor/hooks/ and .cursor/hooks.json).

1. Choose the lifecycle event

Register the hook under one of these keys in hooks.json:

2. Add the script

• Path: .cursor/hooks/<name>.js (or .sh if shell). Use a clear name (e.g. memory-reminder.js, on-stop.js).
• Runtime: Node.js is typical; command in hooks.json is run with Cursor's working directory set so that node hooks/<name>.js resolves (run from .cursor).
• Input: The hook receives a single JSON object on stdin. Read it like this:

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});
process.stdin.on("end", () => {
  const payload = JSON.parse(input);
  const roots = payload.workspace_roots || [process.cwd()];
  const root = path.resolve(roots[0]); // repo root
  // ... use root for paths like path.join(root, '.cursor', 'next-step.md')
});

• Payload: Often includes workspace_roots (array of repo roots). Use the first root as the project root for paths. Event-specific payloads may include file_path, prompt, etc.
• Output: Hook can write files (e.g. .cursor/next-step.md), log to stderr, or exit; avoid writing to stdout if the protocol expects JSON there.
• Shebang: Start Node scripts with #!/usr/bin/env node.

3. Register in hooks.json

• Path: .cursor/hooks.json
• Format:

{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "node hooks/on-stop.js" },
      { "command": "node hooks/my-new-hook.js" }
    ]
  }
}

• Append to the array for the chosen event; do not remove existing hooks unless the user asks to replace them.

Checklist

• Script created under .cursor/hooks/<name>.js (or .sh)
• Script reads JSON from stdin and uses workspace_roots for repo root when needed
• Entry added to .cursor/hooks.json under the correct event key
• Command is node hooks/<name>.js (or ./hooks/<name>.sh); path is relative to .cursor

Reference

• Existing hooks in this repo: .cursor/hooks/on-stop.js, .cursor/hooks/after-file-edit.js, .cursor/hooks/memory-reminder.js — use them as patterns for stdin handling and path.join(root, ...).
• Project memory (.cursor/memory.md) notes that new hooks should be added under .cursor/hooks/ and registered in .cursor/hooks.json.