agentsclimarketplace

Ebert

Skill samrith-s/ebert/skills/ebert

Open Ebert's review UI for a PR, branch, or diff the user asked you to review, then act on their comments. Use only when the user explicitly asks for a code review, PR review, or `/ebert:review` — never as a routine end-of-task step.From its SKILL.md

Install
npx -y skills add samrith-s/ebert --skill ebert

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

16.9 KB, as published. Nobody here has run it

Ebert

Ebert turns a review you write into a real diff interface, waits for the human, and hands their comments back to you.

Do not open a review on your own. Ordinary implementation, fixes, refactors, and chats do not need Ebert. Run this skill only when the user explicitly asks to review a PR, a branch, a diff, or invokes /ebert:review. Collecting unread feedback with ebert pending is separate and fine.

you write review.json  →  ebert review --json  →  human comments  →  markdown on stdout  →  you act

The command blocks while the human reads. That is the point: their reply is the return value.

Every command below is written as ebert. If your shell cannot find that name, use ~/.ebert/bin/ebert — the plugin repoints it at the binary on every hook run.

The loop

# 1. See what changed. Read the code, not just the +/- lines.
git --no-pager diff --stat main...HEAD

# 2. Write your review (format below) to a file.

# 3. Open it and wait. Prints the human's feedback on stdout.
ebert review --json /tmp/review.json

# Other useful forms:
ebert review                      # no JSON — just the diff, for a human to annotate alone
ebert review --base main          # explicit base; default is an auto merge-base
cat review.json | ebert review --json -
ebert schema --example            # a filled-in example to copy
ebert pending                     # feedback you have not read yet

You supply only the review. Ebert collects the diff, mints the ULID, resolves the repo and base ref, timestamps everything, and runs the repo's gates from .ebert.toml if it has any.

That last part matters for what you write: do not hand-author a gates array for checks the repo already declares. Ebert runs those itself and the results will be truthful. Supply gates only when you ran something Ebert cannot — an external CI result, a one-off measurement. Anything you put there replaces the run entirely.

The format

Every field except title is optional. Ids, timestamps, and comments[] wrappers are filled in for you — write body and move on.

{
  "title": "Credentials path writes undefined into the audit event",
  "summary": "Two gates fail, and one cause explains both.\n\nThe rename dropped the default source. `source` is undefined when the audit event is built.",
  "verdict": "request-changes",

  "author": { "name": "claude", "role": "agent", "model": "claude-opus-5" },

  "gates": [
    { "id": "security/no-eval", "group": "security", "status": "pass", "blocking": true, "duration": 412 },
    { "id": "docs/public-api", "group": "docs", "status": "fail", "blocking": false,
      "detail": "greet() throws but has no doc comment", "files": ["src/greet.ts"] }
  ],

  "threads": [
    {
      "file": "src/auth/credentials.ts",
      "line": 42,
      "endLine": 45,
      "side": "additions",
      "severity": "critical",
      "category": "correctness",
      "gates": ["docs/public-api"],
      "body": "The audit event records `undefined` for every call that omits `src`.\n\nThe rename left `source` unset, and nothing narrows it before the event is built.\n\nGive it a default, or make `src` required.",
      "suggestion": {
        "old": "const source = opts.src;",
        "new": "const source = opts.src ?? 'default';"
      }
    }
  ],

  "files": [
    { "path": "src/auth/credentials.ts", "attention": "high",
      "note": "The only file that changes behaviour." }
  ]
}

Fields that matter

FieldValuesNotes
verdictapprove, request-changes, commentYour proposal. The human may overrule it.
severitycritical, high, medium, lowHow bad it is, not how sure you are.
kindissue (default), praisePraise has no criticality — set kind, leave severity at low.
sideadditions, deletionsWhich side of the diff line counts on. Defaults to additions.
line / endLineline numbersOmit both for a comment on the file as a whole.
status (gate)pass, fail, warn, skip, running, queued
attention (file)high, normal, lowhigh tags the file "read this" in the UI.
suggestion{ old, new }Enables "Accept fix". old must match the file exactly.
fixproseThe remedy when no diff can express it — "add a contract test pinning these three together".
anchors[]{ repo, file, line, endLine, side, note }Every place one finding touches. See below.
files[]Only needed to add note or attention; Ebert fills in paths and patches.

Anchor a thread to a line that exists in the diff. side: "additions" numbers are new-file numbers; deletions are old-file numbers.

Findings that live in more than one place

file/line is the short form for the ordinary case, and it stays correct. But the findings worth the most in a multi-repo change are the ones in the seam, and forcing those onto one line throws away the part that matters. Use anchors[]:

{
  "severity": "critical",
  "body": "Two bugs cancel out: the zero TTL is ignored and the cache never expires.",
  "anchors": [
    { "repo": "vault-web", "file": "src/client.ts", "line": 9,
      "note": "asks for an uncached credential with ttlSeconds: 0" },
    { "repo": "vault-api", "file": "src/auth/credentials.ts", "line": 13,
      "note": "reads it with || so zero becomes an hour" },
    { "repo": "vault-web", "file": "src/client.ts", "line": 6,
      "note": "caches anyway, never reading expiresAt" }
  ],
  "fix": "Read expiresAt on the client, and use ?? on the API so a zero TTL survives."
}

Rules that make this readable rather than a riddle:

  • Order the anchors the way the bug flows, not by file name. The reader follows them top to bottom as an argument.
  • Give every anchor a note. A list of three files without notes is worse than prose. Each note says what that location contributes.
  • The first anchor is the primary: it is where the finding appears in the file index, and it should be the place you would start reading. Ebert fills file/line from it.
  • Anchors in two or more repos mark the finding cross-repo in the UI. Anchors in one repo just mean "three places, one bug" — also worth saying.
  • Omit anchors entirely for a systemic finding: a claim about the change as a whole with no line to hang it on. A missing contract test, deploy ordering, a description that contradicts its diff. Give it a fix, since there is no line to suggest against.

Do not split one bug into three findings so each gets a line. Three findings get three verdicts, and the reader has to reassemble the argument you already had.

How to write the review

Read before you write. Read the changed files and their callers. A review that only reads the diff misses the thing the diff broke.

One idea per comment, anchored to a line. A comment covering three problems gets one accept/reject, so two of them go unanswered.

Numbers, not adjectives. "adds 40ms to every request" beats "may impact performance". "118 of 120 gates green" beats "mostly passing".

Criticality is a budget, and critical is the scarcest line in it.

levelmeans
criticalMust change before this lands. Data loss, a leaked secret, a security hole, a crash on a normal path.
highShould change. Wrong output, a silent failure, a real bug that is not catastrophic.
mediumWorth considering. A robustness gap, a sharp edge, a maintenance cost.
lowOptional. Naming, style, a note for later.

If everything is critical, nothing is. A reviewer with twenty criticals reads none of them; a reviewer with two reads both.

Suggest the fix when you know it. A suggestion turns a paragraph of explanation into one click.

Say what is good, once, where it is true. kind: "praise" on the thing that was actually hard. Not on every file.

Never say a file is fine if you did not open it. Ebert reports unopened files as unreviewed; do the same.

Tone: an unhurried senior engineer who has already read the diff. Declarative, specific, slightly dry. Sentence case. No emoji, anywhere.

How to write the prose

These rules apply to every string a human reads: summary, a thread body, a fix, an anchors[].note, and every Docs page. A reviewer reads a page of your prose and rules on it. Prose that is hard to read is prose that gets skimmed, and a skimmed finding is a wasted one.

Short paragraphs, always

One idea per paragraph. A blank line between paragraphs. Ebert sets them with space between them and the first one one size larger, so the shape of your text is part of the interface.

The first paragraph is the claim, in one sentence of 20 words or less. The reader decides from that line alone. Everything after it is support.

Then one short paragraph for each of these, in this order, and only when you have it:

  • what breaks, and the input that breaks it
  • why it happens
  • what to do instead

Three sentences is the limit for one paragraph. Two is better. Three short paragraphs beat one long one. A wall of text is not a style choice — it is the one failure this format cannot absorb.

Do not reach for a bulleted list where two sentences work. Use a list when you have three or more items of the same kind.

Write it in Simple English

Write every review with the rules of Simplified Technical English (ASD-STE100). The reader is tired, is often not a native English speaker, and must not have to read a sentence twice. If the simple-english skill is available, invoke it. These are the rules that matter most here:

RuleDo this
Sentence length25 words maximum. 20 words for an instruction.
One ideaOne instruction per sentence.
VoiceActive. "The rename dropped the default", not "the default was dropped".
TenseSimple present, simple past, or simple future. No present perfect.
ModalsUse must, can, and will. Never should, may, might, or could.
ConditionsPut the condition first: "If src is unset, the audit event records undefined."
TermsOne name for one thing. Do not write "config" here and "settings" there.
PunctuationNo semicolons. Write two sentences instead.
LatinWrite "for example" for e.g., and "that is" for i.e. Name the items instead of "etc".

Delete these words: simply, just, easily, seamlessly, robust, powerful, comprehensive, it is worth noting that, it is important to. Replace these: use for "leverage" and "utilize", to for "in order to", before for "prior to", because for "due to the fact that", you can for "allows you to", internally for "under the hood", by default for "out of the box".

Identifiers are exact. Never simplify a path, a flag, a command, a symbol, or a quoted error. Put each one in backticks: Ebert renders inline code with a warm amber glow, so opts.src stays findable in the middle of a paragraph. A long identifier in backticks counts as one word against the sentence limit.

Check it before you open the review

  1. Read your three longest sentences. Split every one over 25 words.
  2. Search your text for should, may, might, could, ;, has been, and have been. Remove every hit.
  3. Find every if and when. Move each one to the start of its sentence.
  4. Count the sentences in each paragraph. Split every paragraph over three.
  5. Read the first sentence of each finding on its own. If it does not state the claim, rewrite it.

Reading the reply

ebert review prints markdown with these sections:

  • Accepted — instructions. Make these changes.
  • Rejected — settled. Do not re-argue or re-raise them.
  • Deferred — leave alone for now.
  • New comments from the human — these outrank anything you proposed.
  • Not reviewed — files they never opened. Unreviewed, not approved.

Exit code is 0 whether they submitted, dismissed, skipped with Ctrl-C, or timed out. The text says which happened; a dismissal is a decision, so ask what they want rather than proceeding as if approved.

Several repositories

If the change spans more than one repo, review them together — it is one decision:

ebert review --repo ../api --repo ../web --json review.json

Anchor a finding with the plain repo-relative path; Ebert resolves which repo it is in from the file list. The first --repo is the primary. Name the repo explicitly (in anchors[].repo, matching the directory name) when the same path exists in both — and always when a finding spans them.

The reason to review them together is the findings you can only see from both sides at once. Look for these before anything else:

  • Two halves of one contract disagreeing — one side emits disconnected, the other matches not_connected, and nothing pins them together.
  • A default on one side cancelling an argument from the other — the caller passes 0, the callee reads it with ||.
  • A change that is only safe in a particular deploy order, where neither diff says so.

Each of those is one finding with anchors in both repos, not two findings.

Docs

Some things do not belong on a line of code: the order a migration has to happen in, why you chose an approach, what you deliberately left alone, how an unfamiliar subsystem fits together. Put those on the Docs screen rather than swelling the summary. Each document is a page the reader opens one at a time.

How to write a document

# After `ebert review` is open (or before — either works):
ebert doc set --title "Closing the token leak" --body-file plan.md --kind plan --pin
ebert doc set --title "Why I left the retry alone" --body - --kind decision < note.md
ebert doc set --title "How the repos feed each other" --body-file walk.md --kind walkthrough

Or include documents[] in the review JSON you pass to ebert review --json:

{
  "title": "…",
  "summary": "…",
  "documents": [
    {
      "title": "Closing the token leak",
      "kind": "plan",
      "pinned": true,
      "body": "The token is readable in three places.\n\nClose them in this order…"
    }
  ],
  "threads": []
}

--kind is note, plan, walkthrough, risk, or decision. --pin marks "start here" and sorts that document first — spend it on at most one.

Documents are matched on title, so writing the same title again revises that page instead of adding a second one. You do not need to remember an id.

You can revise a document while the review is open and the reader sees the page update without reloading. If triage reveals your plan was wrong, fix the plan.

Write these for a person who has not read the diff. A document that only makes sense after you have read the code is a comment in the wrong place.

The prose rules above apply here too, and they matter more: a document is longer than a finding, so short paragraphs and short sentences are the only thing that keeps it read to the end. Use a heading every few paragraphs. Use a vertical list for steps.

Diagrams

Documents are markdown, and a ```mermaid fence is rendered as a diagram in Ebert's palette. Use one when what you are describing is a graph — how three services hand a request along, which repo depends on which — because prose is the wrong medium for a graph:

```mermaid
flowchart LR
  subgraph web
    caller --> getSecret --> cached{cached?}
  end
  subgraph api
    resolveCredentials --> vault[(vault.internal)]
  end
  cached -- no --> resolveCredentials
```

flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, classDiagram, gitGraph, and timeline all work. Mermaid is loaded on first use, so a review with no diagram pays nothing for this.

Keep them small — a dozen nodes, not fifty. A diagram that needs its own legend has the same problem as a comment covering three bugs. Label edges with the condition (-- 0 is falsy -->), since that is usually where the bug is. If a diagram fails to parse, Ebert shows the source rather than losing it, but the reader still cannot see it.

Reference

ebert list                 # reviews on this machine, newest first
ebert doc list             # documents on the Docs screen
ebert show <id>            # print one as text (--raw for the JSON)
ebert open <id>            # reopen and wait; id may be a prefix, suffix, or "latest"
ebert config              # ~/.ebert/config.toml
ebert doctor               # check the install
ebert install --all        # wire into Claude Code, Codex, and Cursor

Reviews are stored as ~/.ebert/reviews/<ULID>.json. ULIDs sort chronologically, so the newest review is the last one in ls.

Keep looking

Skills are one crate of 608,352. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.