review-docs
Skill1 starsChanged 3 months agoMITView on GitHub
Judge every piece of prose a repository ships. Use as a required review, or as /review-docs. Not for writing docs: doc-editing covers that.
23 other projects use a version of this.
Adopted by
Most recently taken up by
- heypinchy/pinchytheir own version, first seen Nov 12, 2026
- opensanctions/opensanctionstheir own version, first seen Nov 1, 2026
- desbma/agent-skillstheir own version, first seen Oct 27, 2026
- FranciscoMoretti/chat-jstheir own version, first seen Oct 19, 2026
- Kaggle/kaggle-environmentstheir own version, first seen Oct 9, 2026
- app-dev-panel/app-dev-paneltheir own version, first seen Oct 8, 2026
Used with
Projects with it also use create-vercel-ai-issue, dev-auth-bypass and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FranciscoMorettiSkillcreate-vercel-ai-issue
Create a well-formed GitHub issue in vercel/ai using the gh CLI. Use when reporting an AI SDK bug or preparing an issue body that contains logs, code blocks, versions, reproduction steps, and shell-sensitive text.
Also in 3 projects that use this
FranciscoMorettiSkilldev-auth-bypass
Authenticate a browser against a local ChatJS app without OAuth. Use for development login, local auth bypass, authenticated browser or Playwright testing, and the /api/dev-login route.
Also in 3 projects that use this
- +10 more from FranciscoMoretti
Other versions23 projects use a version of this.
Word for word · 1
- cjohnhanson/almanac★ 1100% same
Edited · 0
None found.
Wrote their own version · 22
- tldraw/tldraw★ 51ksame name
- videojs/video.js★ 40ksame name
- reactjs/react.dev★ 12ksame name
- hashicorp/terraform-provider-aws★ 11ksame name
- JamieMason/syncpack★ 2.1ksame name
- OpenAEV-Platform/openaev★ 1.8ksame name
- FranciscoMoretti/chat-js★ 1.2ksame name
- FranciscoMoretti/chatjs★ 1.2ksame name
- FranciscoMoretti/sparka★ 1.2ksame name
- opensanctions/opensanctions★ 870same name
12 more not listed
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 repository5 other files it gives its agents.
- review-codeSkill
- review-depsSkill
- review-testsSkill
- review-usabilitySkill
- signoff-driverSkill
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 20 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
If writing-docs-eval is installed, load it for the full Diátaxis and IBM catalogs.
- Distinctive: line 55
Commit titles, commit bodies, and pull-request text are prose too, and they are the surface most often written from inside the work.
- Distinctive: line 74
Humanize, and hold the standard: Remove AI-writing patterns.
- Distinctive: line 77
Check the prose against the code: Run the commands the documentation shows and confirm the output it claims.
- Distinctive: line 81
blocking: only when a documented workflow depends on it.
- Distinctive: line 101
Check invented compounds, capitalized phrases, and any word used in a private sense.
“Common” is measured: kept by at least 6 in 10 of the 20 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
Review: documentation
You are one independent check on a change you did not write. Judge the
prose. Read signoff-driver for the sign-off line, the two severity
bands, and the not-applicable case.
Method
Three named standards carry this skill.
Diátaxis (Procida) splits documentation into tutorial, how-to, reference, and explanation, and holds that mixing two in one document serves neither.
ASD-STE100 (Simplified Technical English) bounds a sentence. An instruction holds at most 20 words. A description holds at most 25. Both use the active voice and the simple present, with one term for one concept.
IBM's documentation quality characteristics include accuracy: a command in the documentation produces the output the documentation shows.
If writing-docs-eval is installed, load it for the full Diátaxis and IBM
catalogs; criteria 3 and 6 come from there. If writing-sentence-level is
installed, load it for the sentence tests. This skill adds the numeric
limits as a countable rule. If humanizer is installed, load it for the
catalog of AI-writing patterns.
Criteria
- Sweep the repository, not the diff. "This is unrelated to the change" is not a defense. Documentation rots by the change that did not touch it, so a diff-scoped review never catches it. Severity follows the criterion the finding lands under.
Cover every prose surface. The README, agent-instruction files, the contributing guide, bundled documentation, published skills, help text, error messages, and code comments. Error messages and comments are prose that ships. An agent-instruction file is the file a coding agent reads on entering a repository: AGENTS.md, CLAUDE.md, or the equivalent the repository names.
A surface you did not sweep is blocking when it holds an instruction, and minor otherwise. Say which surfaces you swept.
Commit titles, commit bodies, and pull-request text are prose too, and they are the surface most often written from inside the work. Judge them by criterion 8. A title reaches a reader who has none of the author's context: a list of commits, a release note, a blame view. "Fix the layers" names nothing there.
- Judge documentation types and their purity. Does the repository carry a tutorial, a how-to, a reference, and an explanation? Does each document stay in one type? A missing type is minor unless a reader cannot start without it. Drift between types is minor for a paragraph and blocking when a reference no longer answers a lookup.
- Judge each sentence against ASD-STE100. An instruction holds at most 20 words, and a description holds at most 25. Use the active voice and name the actor. Use the simple present. Use one term for one concept. Choose the simple word. Put the condition before the instruction. Use no idioms. A breach is minor on its own, and blocking where it makes an instruction ambiguous.
- Humanize, and hold the standard. Remove AI-writing patterns. Removing them must not break ASD-STE100. Minor.
- Check the prose against the code. Run the commands the documentation shows and confirm the output it claims. A documented thing that does not exist is blocking: a reader who follows it gets an error and no recovery. An undocumented flag is minor, and blocking only when a documented workflow depends on it.
- Check internal consistency. Two documents may state different rules for one behavior. That is blocking when a reader must obey one of them, and minor for an example value. A reader cannot tell which document is current.
Read it as a stranger, and hunt session residue. Take every noun phrase that reads like an established term. Ask where a fresh reader learns it. A term the repository never defines is a finding, however natural it reads to the author.
The common source is the work that produced the text. A correction, a debate, or a passing metaphor from the writing session hardens into vocabulary, and the author cannot see it because they were there. "The trifold gate matrix check" reads as a real thing to the person who coined it that afternoon, and as noise to everyone else. The tell is a definite article in front of a term the document never introduced: "the" says the reader already knows.
Check invented compounds, capitalized phrases, and any word used in a private sense. Blocking when the reader must know the term to follow an instruction, minor otherwise.
A definite article is the cheapest test. Read each "the X". Ask whether the repository names X, or whether the author named it this afternoon. Name it rather than pointing at it: write "config layers" where the work called them "the layers".
Worked examples
A rename leaves prose behind
A change renames a skill, and the diff applies the rename everywhere it touches.
A weak review reads the diff and passes.
This skill greps the whole repository for the old name and finds it in a script's error text, which the diff never touched. A reader following that error looks for something that no longer exists.
signoff[review-docs] FAIL 83bb8dd blocking: merge-gate.sh still
names review-driver in its error text after the renameSession residue reads as vocabulary
Documentation says a list names "a review skill that the repository vendors", and elsewhere refers to "the vendored library".
A weak review reads both sentences, follows them, and passes.
This skill greps for where "vendor" and "vendored library" are defined and finds nothing. The term arrived from a conversation about distribution. A reader who was not in it meets a definite article with no antecedent.
signoff[review-docs] FAIL 0f00b85 blocking: "the vendored library"
is required to follow the install instruction and is defined nowhereThe sweep comes back clean
signoff[review-docs] PASS 7c2d9ab swept 14 prose surfaces including
error text and comments; ran every documented command and matched
its output; no undefined term survives a grep; minor: two sentences
in the tutorial run to 27 wordsDoes 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.

