Index of every page on this site: llms.txt
All skills
onmax avatar

/review-document

@aecfada
by Maxonmax/comark-ui43 stars
3
Run it yourself

Turns a review's findings into one short Markdown document a reader can act on, with the verdict first and each finding ranked, located, backed by evidence, and paired with its fix. Use when writing up a code review, a design or QA review, or an audit, where the reader must decide what to do about what you found.

Use this Skill: https://skilld.dev/gh/onmax/comark-ui/review-document

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈83 tokens for metadata: the name and description. ≈881 when used: this file. ≈1k more on demand in 3 files.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈332 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Review document

A review's reader has one question: what do I do now? Answer it in the first two lines, then give each finding just enough evidence that the reader trusts it without redoing your work. This skill organizes findings you already have; finding them is the review itself.

Length is the usual failure. A reader who has to dig through praise, process, and restated findings misses the one that blocks the merge. Every line below the verdict either supports a finding or says what you didn't check.

1. Decide the verdict

Pick one: approve, approve with changes, request changes, or blocked on a named thing. Under it, write the reason in one sentence that names the finding behind it.

Done when someone who reads only the verdict knows what to do.

2. Keep the findings that change the decision

  • Keep a finding when fixing it, or not, changes what the reader should do.
  • Merge findings with one root cause into one, and list every place it appears.
  • Rank each one: blocking (wrong results, lost data, a security hole, broken for users), should fix (a real cost that can wait), or nit, only when the reader asked for them.

Order them blocking first. Done when every finding has a rank and no two share a cause.

3. Back each finding

Each finding is four parts, in this order:

  1. A title that states the consequence, for whom: "Small avatars load the 512px image", not "Cache key issue".
  2. Where: the file and line, linked when there's a URL.
  3. Evidence, the strongest you have: a failing test or command you ran (::tests, a fenced block of output), a screenshot of the wrong state (measured as the before-after-evidence skill describes), the lines that cause it (a fence with the line highlighted), then reasoning. Say which it is: a finding you reproduced reads differently from one you read in the code.
  4. The fix: a ::diff of the smallest change, or one sentence when the fix is a decision for the reader.

Done when every blocking finding has evidence you ran or captured, or says plainly that it comes from reading the code.

4. Say what you checked

End with two short lists: what you checked and how, and what you didn't check. A review that implies more coverage than it had loses the reader's trust in the parts that were real.

5. Write it

Follow references/example.md:

  • The verdict in a callout: > [!CAUTION] for request changes or blocked, > [!WARNING] for approve with changes, > [!TIP] for approve.
  • One ## heading per finding, numbered, with its rank in the heading. About a dozen lines each, evidence included.
  • No summary that repeats the findings, no section for an empty rank, no list of what's good unless the reader asked.

references/blocks.md has the syntax for the callout, ::tests, ::diff, and highlighted lines.

6. Check the render

  1. Lint it, and fix until it reports no problems:

    vp dlx --package comark-linter --package comark-ui comark-lint review.md

    These commands use the global Vite+ CLI. Without it, pnpm dlx takes the same arguments.

  2. Open the rendered page where it will be read and read it top to bottom as the reader would. Each finding's evidence should be visible without expanding anything except a long log, and each ::diff should start at the line its finding names.

Done when the page renders without problems and you've read it once as the reader.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts6d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    This skill facilitates the creation of structured review documents and utilizes vendor-provided tools for linting. It is generally secure but possesses an indirect prompt injection surface from processed review findings.

  • Socket6d

    No alerts

  • Snyk8d

    Risk: LOW · No issues

Signed by skilld at aecfada. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago

README badge

README badge for onmax/comark-ui/review-document