human-review
Skill3 starsChanged 22 days agoApache-2.0View on GitHub
Put a draft in front of the person you are working for and get their markup back in one batch: they retype text, comment on any selection, and circle or scribble on images and PDF pages with a note per mark. Use before anything they will read, print or publish: post, spec, plan, report, newsletter, landing page, deck, invitation, poster, chart, rendered design, screenshot.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- facebookresearch/autoform-bottheir own version, first seen Nov 12, 2026
- neeldas1209/GTM-Strategy-Enginetheir own version, first seen Oct 20, 2026
- yuhua99/skillstheir own version, first seen Oct 14, 2026
- jngme/claude-skillstheir own version, first seen Oct 13, 2026
- victorrentea/human-reviewtheir own version, first seen Sep 30, 2026
- petergyang/human-reviewtheir own version, first seen Aug 3, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- petergyang/human-review★ 1.3ksame name
- facebookresearch/autoform-bot★ 143same name
- victorrentea/human-review★ 46same name
- IrtezaAsadRizvi/claude-human-review★ 15same name
- yuhua99/skills★ 2same name
- arkan/skills★ 1same name
- jngme/claude-skills★ 0same name
- neeldas1209/GTM-Strategy-Engine★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- blockkit-forgeSkill
- comb-pdf-form-fillingSkill
- din5008-letterSkill
- drive-auditSkill
- excalidrawSkill
- qr-codeSkill
- screenshot-calloutsSkill
- screenshot-overlaysSkill
- video-to-readingsSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 8 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 52
Write or render the draft.
- Very specific: line 56
Wait for poll. It blocks until Send, then prints the batch as JSON.
- Distinctive: line 72
Every item lands in one numbered list.
- Very specific: line 197
A comment with
blocksspans several paragraphs: Read parts: one {block, quote} per paragraph, in order. - Distinctive: line 213
An edit is their wording, not a suggestion: Never revert it, and never improve it.
- Distinctive: line 215
A mark with an empty note means "look here": Ask what is wrong. Do not invent a reason.
- Distinctive: line 218
Keep their numbering when you report back: "1 done, 2 done, 3 needs a decision".
- Distinctive: line 234
You implement a comment you do not understand: Ask. One question now is cheaper than a round on the wrong fix.
- Distinctive: line 241
Run the machine checks first: types, tests, linters, and any automated review you have.
- Distinctive: line 247
Python 3.9 or newer, standard library only: No pip, no npm, no Node. It works offline.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
human-review
An agent that asks "does this look right?" in chat gets "looks good" back. Prose about a draft is not the draft. This skill puts the draft itself in a browser. The reviewer edits the words, selects any phrase and comments on it, and circles the part of the image that is wrong. One Send button returns the whole batch.
Text and pictures sit on the same page on purpose. A draft is rarely only prose or only an image. An invitation is a rendered card and its copy. A post is text and its hero image. Two surfaces split the reviewer's attention. They also cost a round every time an item crosses the boundary.
Image: The review page: a launch card with a circled date badge numbered 1 and an arrow numbered 2, the draft below it with a highlighted edited heading, and a sidebar listing all four items with a typed note under each
One card, one draft, four items back. Everything in the picture is invented, and
scripts/make_example_inputs.py rebuilds the two files behind it.
The loop
skills/human-review/bin/review open draft.md card.png form.pdf # opens the page, returns at once
skills/human-review/bin/review poll --session <id> # blocks until they hit Send
skills/human-review/bin/review poll --ack # clears the batch you handled
skills/human-review/bin/review status # is a batch waiting
skills/human-review/bin/review close # stop a review nobody sends
skills/human-review/bin/review selftest [--browser] # 51 offline cases, 119 more in Chrome (wide and phone)- Write or render the draft.
- Open it with
open. The command prints a session id and a127.0.0.1URL. It also copies the URL to the clipboard and opens a browser. Nothing leaves the machine. The server is local, the page is local, and no account is involved. - Wait for
poll. It blocks until Send, then prints the batch as JSON. Do not busy-wait, and do not add a timeout loop. Some harnesses can run a command in the background and wake you when it exits. Use that, and end your turn. Otherwise keep the foreground poll alive inside the turn. - Apply the batch, render again, and offer the next round on the new file. Two or three tight rounds beat one long round.
What the reviewer can do
| On | How | What you get back |
| An image or a PDF page | circle, box, freehand or arrow, one note per mark | the picture with the marks rendered into it, plus one padded crop per mark |
| A PDF page | select the words themselves, click Comment | the same, plus the exact quote, its anchor and one rectangle per line |
| A Markdown, HTML or text draft | select any text, across paragraphs too, click Comment (or Ctrl+Alt+M), type the note | the quote with a prefix and suffix anchor, and the block it sits in. A selection over several paragraphs also lists them in blocks |
| The same draft | type straight into it | a before and after per block |
| The same draft | circle, box, freehand or arrow, one note per mark | the tool, the marked words as quote, their block and a box. No crop, and an empty anchor |
Every item lands in one numbered list. Their "2" is your "2", on a picture and in a paragraph alike.
A PDF is drawn page by page by PDF.js, at the pixel ratio of the screen, so it is as sharp as a PDF viewer and its text behaves like text: selectable, copyable, and findable with the browser's own Ctrl+F across every page of the session. Every crop of a PDF page is re-rendered from the file at up to eight times page size, so six-point type in a footnote is legible in the crop.
Finding the way around a long session
A session of ten documents and eighty pages is 100,000 pixels of scroll. From two documents on (or one document with two pages or two headings) a contents list appears at the top left: every document with its kind, its page count and how much feedback sits on it, one chip per page, and the headings of a draft. The entry you are reading is marked, and the counts move as notes are written, so the list is also a map of where the feedback is.
jandkgo to the next and previous stop,oshows and hides the list,Esccloses a drawer. None of them fires while the caret is in a note or in an editable block.- In a draft, Shift+Arrow carries a selection on past the end of a paragraph, and Ctrl+Alt+M (Cmd+Option+M on a Mac) comments on it, so a comment over several paragraphs needs no mouse.
- Inside the list: arrow keys, Home, End, Enter.
- No jump touches the browser history, because a page may only close its own tab while that tab has one history entry, and Send closes the tab.
- Below 1200 px the list is a drawer behind a Contents button. Below 760 px the feedback list is a
drawer too, the document gets the whole width, and a bottom bar carries Feedback and Send. That is
the phone layout, and it is checked at 390x844 by
selftest --browser.
The batch
{
"status": "feedback",
"session": "0281f317ca76",
"pages": [
{
"kind": "media",
"name": "card.png",
"source": "/abs/card.png",
"overview": "/…/overview_card.png",
"marks": [
{
"number": 1,
"tool": "ellipse",
"note": "head smaller",
"box": { "x": 0.3, "y": 0.05, "w": 0.4, "h": 0.17 },
"crop": "/…/crops/card_mark_01.png"
}
]
},
{
"kind": "media",
"name": "statement.pdf, page 2",
"source": "/abs/statement.pdf",
"document": "statement.pdf",
"page": 2,
"pages": 3,
"overview": "/…/overview_d2_statement_p02.png",
"marks": [
{
"number": 2,
"tool": "text",
"note": "this total is wrong",
"quote": "1.234,56 EUR",
"anchor": { "prefix": "Interest ", "suffix": " for the period" },
"rects": [{ "x": 0.19, "y": 0.22, "w": 0.09, "h": 0.02 }],
"box": { "x": 0.19, "y": 0.22, "w": 0.09, "h": 0.02 },
"crop": "/…/crops/d2_statement_p02_mark_02.png"
}
]
},
{
"kind": "text",
"name": "draft.md",
"source": "/abs/draft.md",
"edits_saved": false,
"comments": [
{
"number": 2,
"quote": "…",
"anchor": { "prefix": "…", "suffix": "…" },
"block": "draft#4",
"note": "cut this"
},
{
"number": 3,
"quote": "the last sentence of one paragraph\nThe first words of the next",
"anchor": { "prefix": "…", "suffix": "…" },
"block": "draft#5",
"blocks": ["draft#5", "draft#6"],
"parts": [
{ "block": "draft#5", "quote": "the last sentence of one paragraph" },
{ "block": "draft#6", "quote": "The first words of the next" }
],
"note": "merge these"
},
{
"number": 4,
"tool": "ellipse",
"quote": "Second heading",
"anchor": { "prefix": "", "suffix": "" },
"block": "draft#7",
"box": { "x": 0.08, "y": 0.41, "w": 0.35, "h": 0.04 },
"note": "shorter"
}
],
"edits": [
{ "block": "draft#2", "label": "h2", "before": "…", "after": "…" }
]
}
],
"overall_note": "the rest is fine"
}Rules for reading it
- Open every
crop. This is the point of the media path. A box at0.30, 0.05tells you nothing. The crop shows you the eyebrow, the kerning, the seam you got wrong. Look at the images if your model can see them. Say so rather than guess from coordinates if it cannot. - Open the
overviewfirst. It shows what they saw while they wrote the notes. - A page of a PDF carries
document,pageandpages, and itsnameis the label the reviewer saw ("statement.pdf, page 2").sourceis still the PDF itself, so three marked pages of one file give three entries with onesource. A page of a PowerPoint deck also keepsslide. - A mark with
"tool": "text"is a selection, not a drawing. It carries the exactquote, itsanchorand one rectangle per line inrects, withboxas their union. Use the quote to find the words in the source the PDF was made from, and read the crop to see them in place. - A comment with
blocksspans several paragraphs. Readparts: one{block, quote}per paragraph, in order.quotejoins them with newlines for display only, and a code block can hold newlines of its own, so do not split it back. Theprefixcomes from the first block and thesuffixfrom the last. - A comment with a
toolwas drawn on a draft, not selected. Itsquoteis the marked words as the page showed them, from the first marked word to the last in each block, one line per block. Itsanchoris empty, because a shape has no exact character span, so the same phrase twice in one block is ambiguous.boxis where the shape sat, as fractions of the draft. An arrow quotes the word at its head. An emptyquotemeans the shape sat on no words;blockstill names the block nearest to it. Over several paragraphs it hasblocksandpartslike a selection. A mark is read when it is drawn, so later edits do not change its quote. sourceis the original file. Edit that file. The copy in the session directory is a working copy, and a rewrite of it changes nothing.edits_savedis always false. This tool never writes to their files. Applyafterverbatim, and keep the syntax of the source. An edit made in a rendered Markdown block goes back into the Markdown, not as HTML.- An edit is their wording, not a suggestion. Never revert it, and never improve it. Say so and show the evidence if it introduces an error of fact. The wording is still theirs to decide.
- A mark with an empty note means "look here". Ask what is wrong. Do not invent a reason.
- Answer in your own channel, never in the tool. The page has no chat. They see the result when you render again.
- Keep their numbering when you report back: "1 done, 2 done, 3 needs a decision".
marks.md in the session directory carries the same batch as plain text. receipt.json records the
files and the time. A later gate can then treat "a human looked at this" as a fact.
Triage before you implement
A batch is not a task list. Sort every item into one of three buckets, and say which one, before you touch anything:
- do it now,
- defer, and write the item down somewhere durable in the same turn,
- reject, with the reason in one line.
Two failure modes look like diligence:
- You implement a comment you do not understand. Ask. One question now is cheaper than a round on the wrong fix.
- You drop the awkward item in silence. Say that you disagree, then do it anyway. The one exception is an item that is wrong on the facts.
Where it fits
Run the machine checks first: types, tests, linters, and any automated review you have. Then look at the rendered draft yourself, with your own eyes. Only then spend a human's attention. Their time is the most expensive input in the loop. Do not spend it on a defect a tool can find.
Requirements and limits
- Python 3.9 or newer, standard library only. No pip, no npm, no Node. It works offline.
- The browser renders the marked-up overview and cuts the crops, so the tool needs no image library.
- One vendored dependency, and only in the browser: PDF.js 6.3.289 (Apache-2.0), in
assets/vendor/pdfjs. Pinned, checksummed inSHA256SUMS, verified byselftest, served from127.0.0.1, never fetched. The upstream URL, what is deliberately left out, and the update procedure are in its README. No renderer has to be installed any more: poppler andsipsare gone. - What the vendored subset cannot draw. A scan compressed with JPEG 2000 or JBIG2 needs decoders that are shipped as wasm, which this repository does not carry, so such a page comes up blank. A CJK PDF without embedded fonts can show empty glyphs. A PDF that names Helvetica, Times or Courier without embedding them is drawn with the machine's own fonts, as every other viewer does.
- The page is locked down, and that is visible in one place. The server sends
default-src 'none'with a fresh nonce for its two scripts, so a reviewed HTML draft can no longer run anonclick=handler or ajavascript:link, andimg-src 'self'means a remote image inside a reviewed draft does not load. Inline it, or review a screenshot, if you need to see it. - A PowerPoint deck (.pptx) or Word document (.docx) needs LibreOffice (
soffice) to become a PDF first. Password-protected decks and documents are detected and skipped cleanly. - Word (.docx) review limits: Word comments are not rendered, tracked changes show as the document last displayed them, and a Word file is reviewed by marking and commenting, not retyping.
- The Markdown renderer is a deliberate subset: headings, lists, quotes, code, tables, links, emphasis. Anything else stays a paragraph, and nothing disappears. Full CommonMark needs a dependency, and a draft review does not need it.
- The tool reviews files. A page from a development server is out of scope. Screenshot it, or review the template behind it.
- The tool does not support video. Export a frame.
- Send closes the tab. A browser lets a page close its own tab only while the tab has one
history entry. A review opened in a tab that already showed a page cannot close itself. On macOS
the server then closes that tab in Chrome or Edge. It does so only when the app the agent runs in
already has Automation permission for that browser. It never asks for that permission. Without
it, the page says the review is finished, and the tab stays open. The server stops by itself
after Send. Do not run
closethen, or the tab can stay open. - The server answers only requests addressed to
127.0.0.1orlocalhost, and it takes a POST only from its own page. Another web page cannot send a batch or read a draft. A port forward keeps working. - Sessions live in
~/.claude/.review/<id>/. Delete the directory to discard one.
Credit
PDF pages are drawn and made selectable by PDF.js (Apache-2.0),
vendored unmodified. The page carries about twenty lines of its web/pdf_viewer.css, marked as such
in assets/review.html, because its text layer needs them.
Two ideas come from human-review by Peter Yang (MIT). The first anchors a selection by prefix, quote and suffix rather than by offset. The second reports an edit as a before and after on one block, instead of a diff of the whole document. The implementation here is independent, and the two projects share no code.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

