agentleFS
IlyaSemenovIlyaSemenov/agent-review-skill/AGENTS.md

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.

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
  1. Distinctive:

    If another round is useful, the same reviewer conversation receives the host's response, relevant changes, and any new scope instead of the …

    line 14
  2. Distinctive:

    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 …

    line 15
  3. Distinctive:

    When the reviewed subject is a plan that the host then implements, the same reviewer conversation continues with each implemented part …

    line 18
  4. Very specific:

    Keep scripts/agent_review.ts as a thin executable entrypoint.

    line 23
  5. Very specific:

    Keep the implementation and its colocated tests in scripts/agent_review/.

    line 24
  6. Distinctive:

    Use these role names consistently while editing the skill:

    line 27
  7. Very specific:

    Keep developer instructions in this file and its linked development documents.

    line 34
  8. Very specific:

    Keep runtime instructions for the host agent in skills/agent-review/SKILL.md and its linked runtime documents.

    line 35
  9. Distinctive:

    Do not place instructions addressed to a running host or reviewer in developer documentation.

    line 36
  10. Very specific:

    Never edit skills/agent-review/review-method.md here.

    line 47
  11. Distinctive:

    Read every listed document when a task spans multiple areas.

    line 49
  12. Very specific:

    Keep the concrete reviewer list only in skills/agent-review/SKILL.md and README.md.

    line 62
  13. Very specific:

    Keep common guidance for review via CLI and review via user relay in separate documents next to SKILL.md.

    line 63
  14. Very specific:

    Keep host-specific runtime guidance in skills/agent-review/hosts/ and reviewer-specific runtime guidance in skills/agent-review/reviewers/.

    line 64
  15. Very specific:

    Keep SKILL.md as the runtime router and move detailed instructions into its linked runtime documents.

    line 65
  16. Very specific:

    Write project names in prose as Claude Code, Codex, and OpenCode.

    line 66
  17. Very specific:

    Use … only for genuinely open sets, not for the concrete reviewer list.

    line 67

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:

  1. The user asks a host agent to obtain a peer review.
  2. The host identifies the review subject and selects whether the review runs via CLI or user relay according to skills/agent-review/SKILL.md.
  3. The reviewer receives the full subject and review instructions in the first round.
  4. The reviewer returns feedback to the host through a CLI or through the user relay.
  5. The host judges the feedback and changes the reviewed artifact when appropriate.
  6. 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.
  7. 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.
  8. 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.md and read the development document for the behavior being documented.
  • Changes to review criteria, finding verification, or severity: change skills/top-down-review/review-method.md in top-down-review, then run bun run sync-review-method. Never edit skills/agent-review/review-method.md here.

Read every listed document when a task spans multiple areas.

Commands

bun run types
bun run lint
bun test
bun run sync-review-method

Documentation rules

  • Keep the concrete reviewer list only in skills/agent-review/SKILL.md and README.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 in skills/agent-review/reviewers/.
  • Keep SKILL.md as 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 --agent identifiers.
  • Use … only for genuinely open sets, not for the concrete reviewer list.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.