Agent skill

conventional-comments

Format code review comments using Conventional Comments labels and decorations. Use when writing inline review comments on a PR diff. Not for creating PRs — use pr for that. Not for complexity analysis — use code-critic for that.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/hairihou/dotfiles/tree/main/src/.config/claude/skills/conventional-comments

SKILL.md

Conventional Comments

Workflow

  1. Read the full diff before writing any comments.
  2. Identify blocking issues (issue!, suggestion!) first — these gate approval.
  3. Add non-blocking feedback (suggestion, todo, question, note) after.

Format

<label>[!] [(decorations)]: <subject>

[discussion]
Part Required Description
label Yes Comment type (see labels below)
! No Blocking indicator—must resolve before approval
(decoration) No Comma-separated context tags (e.g., (security))
subject Yes Main message (1 line)
discussion No Additional reasoning or suggested fix (1-3 lines)

Labels

Label Description When to use
issue Identifies a problem that needs to be addressed. Bugs, logic errors, broken contracts. Will cause failures if left.
suggestion Proposes an improvement with an explicit change. Better approaches exist. Always include the concrete alternative.
todo Small, necessary change. Less severe than an issue. Missing null checks, missing edge cases, incomplete cleanup.
question Seeks clarification or investigation. Intent is unclear from the code alone. Not rhetorical.
note Information for the reader. Does not require action. Related code elsewhere, upcoming changes, context the author lacks.
typo Points out a typographical error. Misspelled identifiers, comments, or strings.

Do NOT use: praise, nitpick, quibble — focus on actionable feedback only.

Label boundaries

  • issue vs. todo: issue breaks correctness or contracts. todo is a gap that should be closed but is not immediately harmful.
  • suggestion vs. todo: suggestion offers a better approach (include the alternative). todo points out something missing (no alternative needed).
  • question vs. note: question expects a response. note does not.

Anti-patterns

  • Restating the diff. "This adds a new function" — the reviewer can see that. State the consequence or concern instead.
  • Suggestion without alternative. "This could be improved" — how? Always include the concrete change.
  • Rhetorical question. "Do we really need this?" — if you know the answer, use suggestion or issue instead.
  • Commenting on the obvious. If the code is self-explanatory and correct, no comment is needed. Silence is a valid review output.

Decorations

Decoration Use when
(a11y) Comment relates to accessibility.
(performance) Comment relates to performance impact.
(security) Comment relates to security vulnerabilities.
(ux) Comment relates to user experience.

Examples

Basic suggestion

suggestion: Consider using optional chaining here.

`user && user.profile && user.profile.name` can be simplified to `user?.profile?.name`.

Blocking issue

issue!: This function silently swallows exceptions.

Either log the error or propagate it to the caller.

With security decoration

suggestion! (security): User input should not be directly embedded in SQL.

Use prepared statements to prevent SQL injection.

With performance decoration

issue (performance): This query runs inside a loop causing N+1 problem.

Batch the IDs and fetch all records in a single query.

Simple todo

todo: Add null check before accessing `user.email`.

Question

question: Is this timeout value intentional?

300ms seems short for API calls that may span regions.

Note (informational)

note: This pattern is also used in `auth-service.ts:45`.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

hairihou/dotfiles

retrospect

Guided personal reflection that separates fact, interpretation, and emotion through structured inquiry. Use when "something feels off", "need to process this", "had a conflict", or decisions feel unclear. Not for technical decision analysis — use devils-advocate for that.

0 0
Explore
hairihou/dotfiles

1on1-prep

Prepare for 1on1 meetings using a Psychological Safety x Responsibility framework. Use when preparing for a 1on1, noticing behavioral changes, or planning a difficult conversation with a report.

0 0
Explore
hairihou/dotfiles

bonsai

Maintain and groom config files in the current repository. Use when "bonsai", "tidy up", "prune configs", "clean up", "spring cleaning", or reviewing config health. Not for code quality review — use code-critic for that.

0 0
Explore
hairihou/dotfiles

npm-update-report

Dependency update workflow with vulnerability assessment and verification. Use when asked to check outdated packages, bump dependencies, run audit, do periodic dependency maintenance, or when security vulnerabilities are reported.

0 0
Explore
hairihou/dotfiles

session-insights

Analyze the current conversation for inefficiencies and improvement opportunities. Use when "how did this session go", "what went wrong", "what could I have done better", or reviewing session quality. Not for personal reflection — use retrospect. Not for logging work — use diary.

0 0
Explore
hairihou/dotfiles

pr

Create or update a GitHub pull request. Use when asked to create a PR, submit for review, or push changes as a PR. Not for code review comments — use conventional-comments for that.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results