# Conventional Comments

> Write structured code review comments using Conventional Comments format. Use when reviewing PRs, writing code review feedback, or asked to "comment on this code" or "review this PR".

- Skill: `majiayu000/conventional-comments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/conventional-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/conventional-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/conventional-comments

---


# Conventional Comments

Write code review comments in Conventional Comments format (<https://conventionalcomments.org>).

## 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                                          |
| ------------ | ---------------------------------------------------- |
| `issue`      | Identifies a problem that needs to be addressed.     |
| `suggestion` | Proposes an improvement with an explicit change.     |
| `todo`       | Small, necessary change. Less severe than an issue.  |
| `question`   | Seeks clarification or investigation.                |
| `note`       | Information for the reader. Does not require action. |
| `typo`       | Points out a typographical error.                    |

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

## Decorations

| Decoration      | Use when                                     |
| --------------- | -------------------------------------------- |
| `(security)`    | Comment relates to security vulnerabilities. |
| `(performance)` | Comment relates to performance impact.       |
| `(a11y)`        | Comment relates to accessibility.            |
| `(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`.
```