review-usability
Skill1 starsChanged 3 months agoMITView on GitHub
Judge whether a newcomer and a program can use a tool. Use as a required review, or as /review-usability. Not for visual design.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- pydantic/montytheir own version, first seen Sep 4, 2026
- cjohnhanson/tisketword for word, first seen Aug 20, 2026
Other versions2 projects use a version of this.
Word for word · 1
- cjohnhanson/tisket★ 1100% same
Edited · 0
None found.
Wrote their own version · 1
- pydantic/monty★ 8.9ksame 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 repository5 other files it gives its agents.
- review-codeSkill
- review-depsSkill
- review-docsSkill
- review-testsSkill
- signoff-driverSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
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 18
Run the tool before reading its source.
- Very specific: line 28
If qa-cli is installed, load it.
- Very specific: line 35
Run it cold: Start from --help alone. Record every point where you guessed and were wrong.
- Distinctive: line 66
Blocking: when two words for one concept appear in one workflow,
- Distinctive: line 67
minor: when they sit in different documents.
- Distinctive: line 74
Take a wrong turn on purpose: Run what a confused user runs.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review: usability
You are one independent check on a change you did not write. Judge whether
the tool can be used. Read signoff-driver for the sign-off line, the two
severity bands, and the not-applicable case.
Method
Run the tool before reading its source. Your wrong guesses are the findings, because a newcomer makes the same ones, and reading the source destroys your ability to make them.
Then three named lenses. Time to first success counts the steps from first contact to one useful result. Error recovery, from Nielsen's heuristics, asks whether a user who takes a wrong turn is told how to get back. The product oracle asks whether the tool agrees with itself across its help, its errors, and its documentation.
If qa-cli is installed, load it. Its phases cover criteria 1, 3, 4, and
6. Map its bands as signoff-driver states. If agent-interaction-design
is installed, load it for criterion 3. If api-design-eval is installed,
load it when the change touches a contract another program calls.
Criteria
- Run it cold. Start from
--helpalone. Record every point where you guessed and were wrong. A wrong guess that loses data or reaches the wrong target is blocking; one that wastes a minute is minor. Measure time to first success. Count the steps from first contact to one useful result. Count separately the steps needing something the help text did not supply. More than three of that second kind is blocking, and one to three is minor. A tool nobody can start is not usable.
Then judge what the tool says when it acts. Silence on success is a convention many tools follow, and it is right where the effect is visible. Silence is blocking where a user cannot confirm what happened without a second command. A write to a path the user did not name, a partial success, a no-op resembling success, and any destructive act are each of that kind. So is a run long enough to resemble a hang.
- Grade the surface a program sees. Output a caller must guess at, rather than parse, is blocking. Is it parseable without a heuristic? Does every refusal name its cause and its fix? Is the exit code meaningful and distinct? A program cannot ask a follow-up question. A refusal stating only the fault is blocking where the message names no flag, file, or value to change. It is minor where it names one. Two states that a caller cannot tell apart from output and exit code together are blocking.
- Hold one term to one concept. The help, the errors, the documentation, and the flag names must use one word for one thing. Blocking when two words for one concept appear in one workflow, minor when they sit in different documents.
- Judge documentation as part of the tool. The documentation may explain a step the tool could make unnecessary. Say which change would delete that paragraph. Minor, unless the step is required for correct use and easy to miss.
- Take a wrong turn on purpose. Run what a confused user runs. Try a missing argument, a wrong order, an absent flag, and the command in the wrong directory. Judge each refusal by criterion 3.
Worked examples
Two states one caller cannot separate
A change adds a command printing a configured list.
A weak review runs it where the list is configured, sees the right output, and passes.
This skill takes the wrong turns: it runs the command where no config exists and where the config declares an empty list. Both print nothing and exit zero. A caller cannot tell "no policy here" from "policy exists and is empty", so a gate reading that output requires nothing in both cases.
signoff[review-usability] FAIL 0f00b85 blocking: an absent config
and an empty list are indistinguishable on stdout and exit codeThe same command, after the split
signoff[review-usability] PASS 62628cd ran it cold from --help in
six states including no config and a truncated one; each exit code
is distinct and each refusal names its fix; first success took one
step; minor: the error says "repo" where the docs say "repository"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.

