Skip to content
Skills Library
Programming · Writing

code-review-guide

/code-review-guide

Use when writing, structuring, or labelling code-review feedback on a pull or merge request: Conventional Comments labels (praise / nitpick / suggestion / issue / question / thought / chore / todo), the blocking vs non-blocking vs if-minor decorations, pairing one top-level summary with line-anchored inline comments, cross-linking the summary to its details instead of 'see comment 3', and verifying each claim against an authoritative source before asserting it. Platform-independent review craft. Triggers on PR / MR review, leaving review comments, blocking / non-blocking, nit, severity, reques

Repository
platform ↗
Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing, structuring, or labelling code-review feedback on a pull or merge request: Conventional Comments labels (praise / nitpick / suggestion / issue / question / thought / chore / todo), the blocking vs non-blocking vs if-minor decorations, pairing one top-level summary with line-anchored inline comments, cross-linking the summary to its details instead of 'see comment 3', and verifying each claim against an authoritative source before asserting it. Platform-independent review craft. Triggers on PR / MR review, leaving review comments, blocking / non-blocking, nit, severity, reques

Triggers from the description

see comment 3
Original author description

Use when writing, structuring, or labelling code-review feedback on a pull or merge request: Conventional Comments labels (praise / nitpick / suggestion / issue / question / thought / chore / todo), the blocking vs non-blocking vs if-minor decorations, pairing one top-level summary with line-anchored inline comments, cross-linking the summary to its details instead of 'see comment 3', and verifying each claim against an authoritative source before asserting it. Platform-independent review craft. Triggers on PR / MR review, leaving review comments, blocking / non-blocking, nit, severity, reques

How it works

  1. Essentials
  2. Gotchas
  3. Example: a labelled inline comment, and a summary that links to it
  4. Progressive Disclosure
Original SKILL.md headings · 58 lines, 725 words
SKILL.md preview
---
name: code-review-guide
description: "Use when writing, structuring, or labelling code-review feedback on a pull or merge request: Conventional Comments labels (praise / nitpick / suggestion / issue / question / thought / chore / todo), the blocking vs non-blocking vs if-minor decorations, pairing one top-level summary with line-anchored inline comments, cross-linking the summary to its details instead of 'see comment 3', and verifying each claim against an authoritative source before asserting it. Platform-independent review craft. Triggers on PR / MR review, leaving review comments, blocking / non-blocking, nit, severity, request-changes vs approve, or a review summary, even when the user doesn't say 'code review'."
---

# Code-review feedback: quick reference

Host-independent review-comment craft. **Every comment states its type and its urgency: a reader must never guess whether it blocks the merge.** Review operations return findings inline and never post, edit, resolve, or persist them. A separate Publish operation may select a matching host skill for delivery.

## Essentials

- **Label every comment** - Conventional Comments format `label (decoration): subject`; the label categorizes (issue / suggestion / nitpick / question / praise / ...), see [references/conventional-comments.md](references/conventional-comments.md)
- **Set urgency with a decoration** - `(blocking)` must be fixed before merge, `(non-blocking)` is the author's discretion, `(if-minor)` resolve only if the change is small; absence = ambiguity, see [references/conventional-comments.md](references/conventional-comments.md)
- **One summary plus anchored inline comments** - a top-level summary carries the verdict and the headline issues; the detail and suggested code go inline on the exact line, see [references/review-structure.md](references/review-structure.md)
- **Cross-link, never cross-reference by number** - link the summary to its inline threads; a reader does not see your "comment 3" numbering, see [references/review-structure.md](references/review-structure.md)
- **Verify before you assert** - check each claim against the branch code / API / design-system source and cite `file:line`; never review from memory, see [references/review-structure.md](references/review-structure.md)
- **Lead with what works, then be specific** - praise is a label too; for every issue show the fix, not just the problem, see [references/review-structure.md](references/review-structure.md)
- **Carry findings in a shared contract** - analyze and refine return one canonical findings shape, anchored to new-file lines; later Publish or Execute operations may pass it to a host skill, see [references/findings-schema.md](references/findings-schema.md), [references/review-analyze.md](references/review-analyze.md), [references/review-refine.md](references/review-refine.md)

## Gotchas

- Referencing another comment by ordinal ("see comment 3") is meaningless to the reader. They see no numbering. Link to it, or restate the point. If your host cannot link, keep each comment self-contained.
- Marking everything `(blocking)` dilutes the signal until nothing reads as urgent. Reserve blocking for genuine merge gates; most feedback is non-blocking.
- `question` and `thought` are inherently non-blocking and rarely need a decoration; adding `(blocking)` to a question is a contradiction.
- A "before merge" verdict belongs once in the summary, not repeated in every inline comment.
- Keep each comment self-contained, especially if you may edit it later. If comment A says "see comment B" and B is reworded or removed, A is left dangling.
- Suggested-code blocks must compile against the real APIs. A confidently wrong snippet is worse than prose; verify component / function signatures first (this is where a framework skill, e.g. a design-system guide, composes in).
- AI-generated findings and AI-written code are not self-verifying. The human reviewer must actively evaluate each, not rubber-stamp; adversarial AI review complements, never replaces, human judgement on the merge decision.
- Loading a host skill during Review to post or resolve findings silently changes the operation and is out of scope.

## Example: a labelled inline comment, and a summary that links to it

Inline, on the exact line:

> **issue (blocking)**
>
> This overlay also fires on background auto-refresh, so it covers content the user is reading. The existing indicator already signals refresh, so drop the overlay:
>
> ```diff
> - if (isRefreshing && state is Success) { Box(...) { Loader() } }
> ```

Top-level summary, pointing at the detail rather than renumbering it:

> **Review summary**
>
> Direction is good. One thing before merge:
>
> 1. The reload overlay fires on background refresh and covers content. ([details](https://example.com/reviews/123#comment-1))
>
> Remaining notes are inline and non-blocking.

## Progressive Disclosure

Each reference is a trigger: read it only when the user's intent matches; do not preload everything.

- Read [references/conventional-comments.md](references/conventional-comments.md) - Load when choosing a label or decoration, mapping severity to whether it gates merge, or wanting the full label list and the machine-parseable shape.
- Read [references/review-structure.md](references/review-structure.md) - Load when structuring a whole review (summary vs inline), ordering by priority, cross-linking comments, verifying claims before posting, or setting tone and matching a repo's writing style.
- Read [references/findings-schema.md](references/findings-schema.md) - Load when producing or refining structured findings: the canonical findings JSON contract and new-file line anchoring.
- Read [references/review-analyze.md](references/review-analyze.md) - Load when turning a branch diff into structured findings (correctness then quality, anchoring, the effort dial, comparing against prior findings).
- Read [references/review-refine.md](references/review-refine.md) - Load when refining findings before posting (keep / reword / relabel / re-anchor / merge / split / drop, label discipline, stop-after-each-pass).
Files in this package (10)
  • SKILL.md 6 KB
  • SOURCES.md 2 KB
  • eval-queries.json 3 KB
  • evals.json 3 KB
  • moon.yml 1 KB
  • references/conventional-comments.md 2 KB
  • references/findings-schema.md 2 KB
  • references/review-analyze.md 2 KB
  • references/review-refine.md 1 KB
  • references/review-structure.md 1 KB

Versions

The database has no other skills named code-review-guide.

Database snapshot: 13.11.2026 · package version b3b4e433eb4d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100review-pr
    PR review using parallel specialized agents for code quality, security, testing, architecture, and performance analysis. Synthesizes findings into a review report with conventional comments (praise/issue/suggestion/nitpick) and approve or request-changes verdict. Use when…
  • 100mr-comments
    Use when writing a merge request or pull request review finding, the review's summary note, or a reply on a review thread (from /mr-review or the mr-fix process). Severity labels, comment shape, suggestions, the summary format and the reply style. Platform-neutral; a repo's own…
  • 87t3-leaving-pr-comments
    Use whenever leaving comments on GitHub.
  • 90comments
    Draft, refine, or respond to pull-request review comments. Use when a user asks to "write a review comment", "address review feedback", or "reply to a reviewer".
  • 100inline-pr-comments
    Post a single consolidated PR review with summary and inline comments. Use this skill to deliver code review feedback as one unified review per run.
  • 100github-pr-workflow
    Working with GitHub Pull Requests using the gh CLI. Use for fetching PR details, review comments, CI status, and understanding the difference between PR-level comments vs inline code review comments.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.