human-review
The user reviews your HTML, Markdown, or localhost page in a real browser: they fix small things
by typing, select anything to comment on it, and send you the whole batch at once.
Markdown files open rendered. Their quotes and edits reference the rendered text,
and the file itself is never touched — apply every change to the Markdown source,
keeping its formatting syntax.
The loop
Write or update the HTML or Markdown file, or start the local page being reviewed.
Open it for the user:
npx -y human-review path/to/file.html
For a page served by a local development server, open the real route instead
of recreating it as a separate HTML file:
npx -y human-review http://localhost:3000/wiki
Wait for feedback. This command blocks until the user hits Send in the
browser, then prints their batch and exits:
npx -y human-review poll path/to/file.html
The command exits only when the user clicks Send or closes the review.
There is nothing to re-run, no interval to poll on, and no --timeout to
add. It survives the local server restarting, and feedback is saved even
if the poll dies, so nothing is ever lost. How you wait depends on your
harness:
Claude Code: run it with run_in_background: true and end your turn.
Claude Code wakes you with the output the moment the command exits.
Codex, Cursor, and everything else: run it in the foreground,
inside your active turn, and stay on it until it prints feedback or
closed. Do not detach it or start it as a background session: nothing
wakes you when a detached command finishes. While the review is active:
- If the user sends a message, answer it as commentary and immediately
resume the foreground poll in the same turn. Do not send a final
response until the poll returns
feedback or closed — a final
response ends the turn and kills the wait.
- If your shell tool caps command duration, pass
--timeout a little
under the cap and run bounded polls back to back in the same active
turn until one returns feedback or closed.
Know the limit: this is reliable only while your turn stays active. A
turn that has already ended is not woken when the user hits Send; the
user has to message you, and you then run status and poll to pick
the batch up. There is no integration that resumes an ended task when
the poll exits.
If it prints {"status":"closed"}, the review is over: the user ended it,
closed the tab, or never had one open (reason says which). Stop and do
not start another poll. unsent counts feedback they left behind; if it is
not zero, tell the user in one line that it is kept and they can restore or
discard it next time. {"status":"superseded"} means a newer poll of
yours owns the wait — stop this one silently. {"status":"timeout"} only
appears after 12 hours; run status and start the wait again if the
review is still open.
Apply what comes back, then start the next background poll. --ack clears
the batch you just handled:
npx -y human-review poll path/to/file.html --ack
Repeat 3–4 until the user says they are done.
Not sure whether feedback is already waiting — say, at the start of a new turn
with no poll running? This answers instantly without blocking:
npx -y human-review status path/to/file.html
It prints {"status": "feedback-waiting"} when a batch is ready for a poll,
plus counts of unsent comments and edits still in the browser.
What you get
One batch covers every page the user visited, grouped by file or localhost URL.
{
"status": "feedback",
"pages": [
{
"file": "/abs/path/to/page.html",
"edits_saved": true,
"comments": [
{ "id": "c_1", "kind": "selection", "quote": "the exact text they selected",
"anchor": { "prefix": "...", "quote": "...", "suffix": "..." },
"feedback": "what they want changed" }
],
"edits": [
{ "label": "Problem body", "kind": "edited",
"before": "the original wording",
"after": "their exact new wording",
"after_html": "their exact new wording with <strong>formatting</strong>" }
]
}
],
"overall_note": "feedback not tied to any one page"
}
Rules
edits are changes the user already made. after is their exact wording —
carry it across verbatim and never revert it. If the HTML was generated from
something else (MDX, Markdown, a template), apply after to the source too,
or their fix disappears on the next build.
edits_saved: true means those edits are already in the file on disk.
Plain HTML files autosave as the user types, so your copy of the file is
stale. Re-read the file before touching it and make targeted changes only;
never regenerate it from what you wrote earlier, or their work disappears.
edits_saved: false (Markdown, localhost pages, self-rendering HTML) means the
edits exist only in this batch — apply them to the source yourself.
- An edit with
kind: "deleted" means the user removed that whole block:
delete it from the source too, without asking why.
- An edit marked
truncated: true had its text cut at 200k characters; read
the block from the page itself rather than from after_html.
- When
before_html/after_html are present, the user changed formatting, not
just words — bold, italic, underline, links. Use the HTML version to carry the
formatting into the source, translated to its syntax (e.g. <strong> → **
in Markdown/MDX).
- A page with
kind: "url" was edited directly in the review UI. Its file
and url fields name the localhost route, not a writable file. Find the
matching project source (such as MDX, TSX, or a template), apply every edit
and deletion there, then acknowledge so the route reloads. Never write the
rendered HTTP response back into the app.
- When an edit's
after_html contains <img src="assets/...">, the user pasted
an image: the file already exists in an assets/ folder next to the reviewed
file. Keep that relative path — in Markdown, reference it as
. Never regenerate or inline the image.
- On a localhost page, a pasted image arrives under
staged_assets. Copy its
local path into the app's appropriate asset folder, replace the temporary
preview URL in after_html, and preserve the image at the user's insertion
point. Never leave the temporary preview URL in source.
- An edit with
kind: "moved" means the user relocated that whole block.
Reposition it in the source without rewriting its content: it now sits right
after the block whose text starts with moved_after, and right before the
block whose text starts with moved_before (both are clipped to 90
characters and may end in …). An empty moved_after means it is now the
first block in its container.
- Find each comment by its
quote. It is the rendered text the user
selected, so in Markdown or templated HTML it may span formatting syntax or
tags; anchor.prefix and anchor.suffix give the surrounding text to
disambiguate.
kind: "element" points at a whole block, so quote is its label, not body text.
- Copy any
staged_assets files before you ack: --ack deletes them.
- A batch with only an
overall_note has an empty pages array.
- Fix every page in
pages, not just the first.
- Do not write a reply. There is no chat. The user sees your work when the page
reloads, which happens on its own the moment you save the file.
Better edit labels (optional)
Name the sections you author and the user's edit list uses your names instead of
guessing from the DOM:
<p data-block="Problem body">…</p>
<div data-container="Metrics callout">…</div>
data-block names a region for the edit list. data-container also makes the block
clickable as a comment target.
1---2name: human-review3description: Open an HTML file, Markdown file, or localhost page in the browser so the user can edit text directly and leave comments on specific parts, then send all edits and comments back to you. Use after writing or updating something the user will read — specs, plans, reports, newsletter drafts, landing pages, slide decks, and locally running web pages.4metadata:5 source: https://skillmd.com/skills/petergyang/human-review6---78# human-review910The user reviews your HTML, Markdown, or localhost page in a real browser: they fix small things11by typing, select anything to comment on it, and send you the whole batch at once.1213Markdown files open rendered. Their quotes and edits reference the rendered text,14and the file itself is never touched — apply every change to the Markdown source,15keeping its formatting syntax.1617## The loop18191. Write or update the HTML or Markdown file, or start the local page being reviewed.202. Open it for the user:2122 ```sh23 npx -y human-review path/to/file.html24 ```2526 For a page served by a local development server, open the real route instead27 of recreating it as a separate HTML file:2829 ```sh30 npx -y human-review http://localhost:3000/wiki31 ```32333. Wait for feedback. This command blocks until the user hits Send in the34 browser, then prints their batch and exits:3536 ```sh37 npx -y human-review poll path/to/file.html38 ```3940 The command exits only when the user clicks Send or closes the review.41 There is nothing to re-run, no interval to poll on, and no `--timeout` to42 add. It survives the local server restarting, and feedback is saved even43 if the poll dies, so nothing is ever lost. How you wait depends on your44 harness:4546 - **Claude Code:** run it with `run_in_background: true` and end your turn.47 Claude Code wakes you with the output the moment the command exits.48 - **Codex, Cursor, and everything else:** run it in the **foreground**,49 inside your active turn, and stay on it until it prints `feedback` or50 `closed`. Do not detach it or start it as a background session: nothing51 wakes you when a detached command finishes. While the review is active:52 - If the user sends a message, answer it as commentary and immediately53 resume the foreground poll in the same turn. Do not send a final54 response until the poll returns `feedback` or `closed` — a final55 response ends the turn and kills the wait.56 - If your shell tool caps command duration, pass `--timeout` a little57 under the cap and run bounded polls back to back in the same active58 turn until one returns `feedback` or `closed`.5960 Know the limit: this is reliable only while your turn stays active. A61 turn that has already ended is not woken when the user hits Send; the62 user has to message you, and you then run `status` and `poll` to pick63 the batch up. There is no integration that resumes an ended task when64 the poll exits.6566 If it prints `{"status":"closed"}`, the review is over: the user ended it,67 closed the tab, or never had one open (`reason` says which). Stop and do68 not start another poll. `unsent` counts feedback they left behind; if it is69 not zero, tell the user in one line that it is kept and they can restore or70 discard it next time. `{"status":"superseded"}` means a newer poll of71 yours owns the wait — stop this one silently. `{"status":"timeout"}` only72 appears after 12 hours; run `status` and start the wait again if the73 review is still open.74754. Apply what comes back, then start the next background poll. `--ack` clears76 the batch you just handled:7778 ```sh79 npx -y human-review poll path/to/file.html --ack80 ```8182Repeat 3–4 until the user says they are done.8384Not sure whether feedback is already waiting — say, at the start of a new turn85with no poll running? This answers instantly without blocking:8687```sh88npx -y human-review status path/to/file.html89```9091It prints `{"status": "feedback-waiting"}` when a batch is ready for a poll,92plus counts of unsent comments and edits still in the browser.9394## What you get9596One batch covers every page the user visited, grouped by file or localhost URL.9798```json99{100 "status": "feedback",101 "pages": [102 {103 "file": "/abs/path/to/page.html",104 "edits_saved": true,105 "comments": [106 { "id": "c_1", "kind": "selection", "quote": "the exact text they selected",107 "anchor": { "prefix": "...", "quote": "...", "suffix": "..." },108 "feedback": "what they want changed" }109 ],110 "edits": [111 { "label": "Problem body", "kind": "edited",112 "before": "the original wording",113 "after": "their exact new wording",114 "after_html": "their exact new wording with <strong>formatting</strong>" }115 ]116 }117 ],118 "overall_note": "feedback not tied to any one page"119}120```121122## Rules123124- **`edits` are changes the user already made.** `after` is their exact wording —125 carry it across verbatim and never revert it. If the HTML was generated from126 something else (MDX, Markdown, a template), apply `after` to the **source** too,127 or their fix disappears on the next build.128- **`edits_saved: true` means those edits are already in the file on disk.**129 Plain HTML files autosave as the user types, so your copy of the file is130 stale. Re-read the file before touching it and make targeted changes only;131 never regenerate it from what you wrote earlier, or their work disappears.132 `edits_saved: false` (Markdown, localhost pages, self-rendering HTML) means the133 edits exist only in this batch — apply them to the source yourself.134- An edit with `kind: "deleted"` means the user removed that whole block:135 delete it from the source too, without asking why.136- An edit marked `truncated: true` had its text cut at 200k characters; read137 the block from the page itself rather than from `after_html`.138- When `before_html`/`after_html` are present, the user changed formatting, not139 just words — bold, italic, underline, links. Use the HTML version to carry the140 formatting into the source, translated to its syntax (e.g. `<strong>` → `**`141 in Markdown/MDX).142- A page with `kind: "url"` was edited directly in the review UI. Its `file`143 and `url` fields name the localhost route, not a writable file. Find the144 matching project source (such as MDX, TSX, or a template), apply every edit145 and deletion there, then acknowledge so the route reloads. Never write the146 rendered HTTP response back into the app.147- When an edit's `after_html` contains `<img src="assets/...">`, the user pasted148 an image: the file already exists in an `assets/` folder next to the reviewed149 file. Keep that relative path — in Markdown, reference it as150 ``. Never regenerate or inline the image.151- On a localhost page, a pasted image arrives under `staged_assets`. Copy its152 local `path` into the app's appropriate asset folder, replace the temporary153 preview URL in `after_html`, and preserve the image at the user's insertion154 point. Never leave the temporary preview URL in source.155- An edit with `kind: "moved"` means the user relocated that whole block.156 Reposition it in the source without rewriting its content: it now sits right157 after the block whose text starts with `moved_after`, and right before the158 block whose text starts with `moved_before` (both are clipped to 90159 characters and may end in `…`). An empty `moved_after` means it is now the160 first block in its container.161- Find each comment by its `quote`. It is the **rendered** text the user162 selected, so in Markdown or templated HTML it may span formatting syntax or163 tags; `anchor.prefix` and `anchor.suffix` give the surrounding text to164 disambiguate.165- `kind: "element"` points at a whole block, so `quote` is its label, not body text.166- Copy any `staged_assets` files before you ack: `--ack` deletes them.167- A batch with only an `overall_note` has an empty `pages` array.168- Fix every page in `pages`, not just the first.169- **Do not write a reply.** There is no chat. The user sees your work when the page170 reloads, which happens on its own the moment you save the file.171172## Better edit labels (optional)173174Name the sections you author and the user's edit list uses your names instead of175guessing from the DOM:176177```html178<p data-block="Problem body">…</p>179<div data-container="Metrics callout">…</div>180```181182`data-block` names a region for the edit list. `data-container` also makes the block183clickable as a comment target.