annotate-it

A Claude Code skill that lets a human leave inline comments on a draft the agent wrote — by highlighting text in a browser — and feeds those comments, with context, straight back to the agent. No copy-paste.

Built for the case where you ask the assistant for some text (a CV, cover letter, doc, spec, marketing copy, config) and want to point at exact phrases — "this word is wrong", "drop this bullet" — instead of retyping "change the second sentence of paragraph three".

How it works

• A two-pane local web page: the draft on the left, your comments on the right.
• Select any span → a comment box pops up, tied to that exact quote.
• Click a highlight to edit or delete it. Optional overall note.
• Click Send → your comments land back with the agent, hands-free (the agent wakes up on its own; you don't have to type anything in the terminal).

Each comment arrives anchored with the full line it sits in and a ±60-char window, so even a one-word selection is unambiguous.

Demo

2026-06-02_14-11-00_1.5x.mp4

Install

It's a personal skill — drop the folder where your agent looks for skills:

# Claude Code
git clone <this-repo> ~/.claude/skills/annotate-it

# or copy an existing checkout
cp -r annotate-it ~/.claude/skills/

(Codex: ~/.agents/skills/. Any agent that loads Claude-style skills works.)

Requirements: Node.js 18+ (uses only built-in modules — no npm install).

Usage (what the agent does)

The skill is self-driving once invoked; this is the loop it follows:

1. Write the draft to <workdir>/draft.txt (any directory — /tmp/review, a project subfolder, anywhere you can write). Plain text — the file's own structure carries through as-is.
2. Start the server in the background:

   node ~/.claude/skills/annotate-it/server.mjs --dir <workdir>

   It prints {"url":"http://localhost:PORT", ...} (also in <workdir>/server-info.json).
3. Open the URL, comment, click Send.
4. The agent reads the last line of <workdir>/feedback.jsonl and revises.
5. New round: agent overwrites draft.txt, you refresh the page.

The resume is hands-free. After giving you the URL, the agent runs a waiter in the background and ends its turn:

node ~/.claude/skills/annotate-it/wait-for-feedback.mjs --dir <workdir>

When you click Send, the waiter exits — and a background task exiting is what re-invokes the agent. So the agent wakes up by itself; no "tell me when you're done" ping. (It's still turn-based under the hood: a browser click can't reach a model directly, so the waiter's exit is the bridge. Expect a few seconds of lag — mostly the harness re-invocation, not the file watch.)

Feedback format

Each Send appends one JSON line to feedback.jsonl:

{"overall":"...","count":2,"comments":[
  {"quote":"selected text","note":"your comment",
   "line":"the whole line it sits in",
   "before":"~60 chars before","after":"~60 chars after"}
]}

Files

File	Role
SKILL.md	Skill manifest + the loop the agent follows
server.mjs	Dependency-free HTTP server: serves the page, the draft, collects feedback
review.html	The comment UI (inline highlights, context-anchored comments)
wait-for-feedback.mjs	Background watcher; exits on a new submission to auto-resume the agent

License

MIT