---
name: Human Review
slug: human-review
category: Automation
description: Human Review opens HTML, Markdown, or localhost pages in a browser for direct text edits and comments. Use it after writing specs, drafts, reports, or local pages that need human feedback.
github: "https://github.com/petergyang/human-review/tree/main/src"
language: JavaScript
stars: 1071
forks: 78
install: "npx degit https://github.com/petergyang/human-review/tree/main/src ~/.claude/skills/src"
installs_to: ~/.claude/skills/src
source_path: src/SKILL.md
collection_size: 1
category_size: 1523
added: 2026-08-21T05:13:37.595Z
last_synced: 2026-08-21T05:13:37.595Z
canonical_url: "https://dirskills.com/skills/human-review"
---
# Human Review
Human Review opens HTML, Markdown, or localhost pages in a browser for direct text edits and comments. Use it after writing specs, drafts, reports, or local pages that need human feedback.
**Install:**
```bash
npx degit https://github.com/petergyang/human-review/tree/main/src ~/.claude/skills/src
```
## README
# 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
1. Write or update the HTML or Markdown file, or start the local page being reviewed.
2. Open it for the user:
```sh
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:
```sh
npx -y human-review http://localhost:3000/wiki
```
3. Wait for feedback. This blocks until they hit Send, or the timeout passes:
```sh
npx -y human-review poll path/to/file.html --timeout 600
```
Keep this command in the foreground. Do not end your turn while it is waiting.
If your shell returns a process or session handle, keep waiting on that handle
until the command exits. If it prints `{"status":"timeout"}`, no feedback has
arrived yet — run the same poll command again to keep waiting. Feedback is
saved even if a poll dies, so nothing is ever lost.
If it prints `{"status":"closed"}`, the user ended the review from the
browser — stop polling and do not run the poll command again. Unsent
feedback is kept and ships the next time this target is reviewed.
4. Apply what comes back, then wait again. `--ack` clears the batch you just handled:
```sh
npx -y human-review poll path/to/file.html --ack --timeout 600
```
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?
This answers instantly without blocking:
```sh
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.
```json
{
"status": "feedback",
"pages": [
{
"file": "/abs/path/to/page.html",
"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 formatting" }
]
}
],
"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.
- 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. `` → `**`
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 `
`, 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`. An empty `moved_after` means it
is now the first block in its container.
- Find each comment by its `quote`; that exact string is in the file.
- `kind: "element"` points at a whole block, so `quote` is its label, not body text.
- 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:
```html
…
…
```
`data-block` names a region for the edit list. `data-container` also makes the block
clickable as a comment target.