naive-reader-review
Skill301 starsChanged 12 days agoApache-2.0View on GitHub
Pressure-test a docs page for clarity by having a naive sub-agent read it cold. A Sonnet sub-agent with no prior context reports what the tool seems to do, gaps between what's promised and what the commands deliver, passages that needed a re-read, and terms it couldn't define. The supervisor then revises the doc from that feedback.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- js/AGENTS.mdAGENTS.md
- sandbox-image/AGENTS.mdAGENTS.md
- amika-annotationsSkill
- amika-cliSkill
- create-cli-release-commitSkill
- create-sdk-release-commitSkill
- distill-sessionSkill
- make-stacked-prsSkill
- new-specSkill
- release-commit-sandbox-imageSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
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 8
Use when you want to know whether a docs page (a file under docs/, a README section, a tutorial) actually lands with a developer who has no …
- Distinctive: line 36
Ask it to keep the answer short.
- Distinctive: line 40
Read the sub-agent's answers.
- Distinctive: line 42
If it misread what the tool does or the value, the value prop isn't leading clearly enough.
- Distinctive: line 43
If it found a gap between the promise and what the commands actually do, show the mechanism or state the boundary honestly.
- Distinctive: line 44
If it flagged an undefined term, define it in context or cut it.
- Distinctive: line 51
Run the reader on one representative page when several are near-identical.
≈ “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
Naive reader review
Use when you want to know whether a docs page (a file under docs/, a README
section, a tutorial) actually lands with a developer who has no prior context
on this product.
Usage: /naive-reader-review <path to the doc>
Phase 1: Spawn the naive reader
Spawn a sub-agent with the Agent tool:
subagent_type: general-purposemodel: sonnet- Point it at exactly one file. Tell it to read only that file: no exploring the repo, no outside knowledge about this product or company, no charitable assumptions. It should answer only from the literal words in the doc.
Brief it as a blunt, impatient developer landing on the page cold (from a link or search). It has the audience's baseline knowledge — it vaguely knows what AI coding agents like Claude Code are — but knows nothing about amika or this repo, and will not fill in gaps. Have it answer:
- What does this tool do?
- What problem does it claim to solve, and did the problem feel real and concrete?
- What value would the reader get, specifically? Could they tell what they'd actually do with the tool after following the doc?
- Does the solution deliver on the problem, or is there a gap between what's promised and what the commands let you do?
- Was everything understandable on one read? List every spot that needed a re-read or felt like a logical leap.
- List every term or phrase it can't define from the text alone (jargon, product names used without introduction, references that assume context it doesn't have).
Ask it to keep the answer short.
Phase 2: Revise
Read the sub-agent's answers. Each point of confusion is a fix:
- If it misread what the tool does or the value, the value prop isn't leading clearly enough.
- If it found a gap between the promise and what the commands actually do, show the mechanism or state the boundary honestly; don't paper over it with bigger claims.
- If it flagged an undefined term, define it in context or cut it.
Apply the fixes in the main agent so the user sees the diff. Skip changes that would lose something the user explicitly asked for.
Notes
- Run the reader on one representative page when several are near-identical; apply the resulting fixes to all of them.
- The point is clarity to a cold reader, not polish. Don't let the revision get longer or more hedged.
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.

