agent-review-skill
AGENTS.md4 starsChanged 15 days agoMITView on GitHub
You are developing the agent-review skill in skills/agent-review/, not running a review as its host or reviewer. One review is a sequence of rounds controlled by the host agent: When the reviewed subject is a plan that the host then implements, the same reviewer conversation continues with each implemented part before the host commits it. scripts/agent_review.ts implements one round of this process. In this documentation, core means its transport-independent behavior, while agentex transport means the shared CLI-review execution path. Keep…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-reviewSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
17 rules. About 0 are common, 6 are distinctive, and 11 are 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.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
If another round is useful, the same reviewer conversation receives the host's response, relevant changes, and any new scope instead of the …
- Distinctive: line 15
When the subject is a change to project files, a prose round checks how the change reads, such as its texts, names, and the order of its …
- Distinctive: line 18
When the reviewed subject is a plan that the host then implements, the same reviewer conversation continues with each implemented part …
- Very specific: line 23
Keep scripts/agent_review.ts as a thin executable entrypoint.
- Very specific: line 24
Keep the implementation and its colocated tests in scripts/agent_review/.
- Distinctive: line 27
Use these role names consistently while editing the skill:
- Very specific: line 34
Keep developer instructions in this file and its linked development documents.
- Very specific: line 35
Keep runtime instructions for the host agent in skills/agent-review/SKILL.md and its linked runtime documents.
- Distinctive: line 36
Do not place instructions addressed to a running host or reviewer in developer documentation.
- Very specific: line 47
Never edit skills/agent-review/review-method.md here.
- Distinctive: line 49
Read every listed document when a task spans multiple areas.
- Very specific: line 62
Keep the concrete reviewer list only in skills/agent-review/SKILL.md and README.md.
- Very specific: line 63
Keep common guidance for review via CLI and review via user relay in separate documents next to SKILL.md.
- Very specific: line 64
Keep host-specific runtime guidance in skills/agent-review/hosts/ and reviewer-specific runtime guidance in skills/agent-review/reviewers/.
- Very specific: line 65
Keep SKILL.md as the runtime router and move detailed instructions into its linked runtime documents.
- Very specific: line 66
Write project names in prose as Claude Code, Codex, and OpenCode.
- Very specific: line 67
Use … only for genuinely open sets, not for the concrete reviewer list.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md 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
Agent Review Development
You are developing the agent-review skill in skills/agent-review/, not running a review as its host or reviewer.
How a review runs
One review is a sequence of rounds controlled by the host agent:
- The user asks a host agent to obtain a peer review.
- The host identifies the review subject and selects whether the review runs via CLI or user relay according to
skills/agent-review/SKILL.md. - The reviewer receives the full subject and review instructions in the first round.
- The reviewer returns feedback to the host through a CLI or through the user relay.
- The host judges the feedback and changes the reviewed artifact when appropriate.
- If another round is useful, the same reviewer conversation receives the host's response, relevant changes, and any new scope instead of the full subject.
- When the subject is a change to project files, a prose round checks how the change reads, such as its texts, names, and the order of its tests.
- The host stops when further review is not useful and reports the outcome to the user.
When the reviewed subject is a plan that the host then implements, the same reviewer conversation continues with each implemented part before the host commits it.
scripts/agent_review.ts implements one round of this process.
In this documentation, core means its transport-independent behavior, while agentex transport means the shared CLI-review execution path.
Keep scripts/agent_review.ts as a thin executable entrypoint.
Keep the implementation and its colocated tests in scripts/agent_review/.
Organize modules around cohesive responsibilities and update the linked development documents when those boundaries change.
Use these role names consistently while editing the skill:
- Developer agent — the agent modifying this repository.
- Host agent — the agent executing the installed skill for a user.
- Reviewer agent — the peer agent evaluating the host agent's artifact.
- User — the person directing the host and, when review runs via user relay, carrying messages between sessions.
Keep developer instructions in this file and its linked development documents.
Keep runtime instructions for the host agent in skills/agent-review/SKILL.md and its linked runtime documents.
Do not place instructions addressed to a running host or reviewer in developer documentation.
Where to make changes
Classify the requested change by where it acts in the review flow, then read the matching document before editing:
- Changes to helper input, prompt construction shared by both review paths, round behavior, response fields, normalization, retries, timeout, or helper output: read Core development.
- Changes to
--agent manual, user relay, relay prompts, or lenient interpretation of pasted reviewer responses: read both User-relay development and Core development. - Changes to how a named reviewer is invoked, resumed, parsed, registered, or diagnosed, or to the helper's runtime dependencies: read agentex development.
- Changes to instructions followed by a host running the installed skill: edit the matching runtime document selected by
skills/agent-review/SKILL.mdand read the development document for the behavior being documented. - Changes to review criteria, finding verification, or severity: change
skills/top-down-review/review-method.mdin top-down-review, then runbun run sync-review-method. Never editskills/agent-review/review-method.mdhere.
Read every listed document when a task spans multiple areas.
Commands
bun run types
bun run lint
bun test
bun run sync-review-methodDocumentation rules
- Keep the concrete reviewer list only in
skills/agent-review/SKILL.mdandREADME.md. - Keep common guidance for review via CLI and review via user relay in separate documents next to
SKILL.md. - Keep host-specific runtime guidance in
skills/agent-review/hosts/and reviewer-specific runtime guidance inskills/agent-review/reviewers/. - Keep
SKILL.mdas the runtime router and move detailed instructions into its linked runtime documents. - Write project names in prose as Claude Code, Codex, and OpenCode; use lowercase only for CLI commands and
--agentidentifiers. - Use
…only for genuinely open sets, not for the concrete reviewer list.
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.

