Conventional comments
Drive a feature from idea to PR with a team of Claude Code agents.
npx -y skills add bostonaholic/team --skill conventional-commentsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 8 stars8 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.
What its author says it does
Copied from the file, not written here
The Conventional Comments format for review findings — label and decoration syntax, code-directed comment style, and the issue/suggestion/nitpick comment types with literal examples. Load when writing, formatting, or labeling review comments, PR feedback, or reviewer findings.
SKILL.md
2.5 KB, as published. Nobody here has run it
Conventional Comments
Review comments from the code, security, and docs reviewers use the
Conventional Comments format (https://conventionalcomments.org) — the
ux-reviewer's live-verification report uses its own Working/Broken/Could
Improve format instead. Every comment MUST include a specific file:line
reference.
Comment Style
Critique the code, not the coder. Assume competence. The same finding can read as collaborative or hostile depending on phrasing:
| Avoid (person-directed) | Prefer (code-directed) |
|---|---|
| "Your approach is adding unnecessary complexity." | "The complexity this adds isn't worth the result." |
| "You're not handling the null case." | "The null case isn't handled here." |
| "This doesn't make any sense." | "I can't follow what this branch is doing — clarify?" |
- Explain why the change is requested. A finding without a reason loses the rationale for the next reader of the diff.
- Reserve
issue:for findings that materially affect correctness, security, or maintainability. Usesuggestion:ornitpick:for preferences. - A high comment density on a single change is a design signal, not just a style problem. When the count climbs past ~10 substantive comments, propose splitting the change or escalating the design conversation out of the review tool.
Comment Types
Every comment body MUST begin with the label and decoration wrapped in
**...** so GitHub renders it bold. Copy the format in the examples below
literally — including the asterisks — into the comment body you emit.
issue (blocking): Identifies a defect that must be fixed before approval.
**issue (blocking):** This query interpolates user input without parameterization.
file: src/api/users.ts:42
suggestion (non-blocking): Proposes an improvement. The author may accept or decline.
**suggestion (non-blocking):** Consider extracting this validation into a shared utility.
file: src/handlers/create.ts:18
nitpick (non-blocking): Minor style or naming observation. Never blocks approval.
**nitpick (non-blocking):** "data" is too vague — consider "userProfile" to match the domain.
file: src/models/types.ts:7