conventional-commits

Original source / Raw SKILL.md

---
name: conventional-commits
description: This skill should be used when the user asks to "create a commit", "follow conventional commits", "analyze commit history", "check commit format", or mentions "Conventional Commits specification". Provides expertise in creating conventional commits following the Commitizen (cz) style and v1.0.0 specification.
version: 0.2.1
---

## Core Rules

**Format**:
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Title Requirements**:
- ALL LOWERCASE (no capitalization in description)
- <50 characters
- Imperative mood (e.g., "add" not "added")
- No period at end
- Add "!" before ":" for breaking changes (e.g., `feat!:`, `feat(api)!:`)

**Common Types**: `feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `test:`, `chore:`, `build:`, `ci:`, `style:`

**Body** (optional but recommended): Blank line after title, ≤72 chars/line
- **Bullet list**: What changed (start with verb: Add, Remove, Update, Fix)
- **Blank line**
- **Explanation paragraph**: Why it matters, what impact it has

Example body structure:
```
- Add new user authentication endpoint
- Update middleware to validate JWT tokens
- Remove legacy session handling code

Modernizes the authentication system and improves security
by using industry-standard JWT tokens instead of sessions.
```

**IMPORTANT - Body Requirements** (enforced by git plugin hook):
- **Body is mandatory** - all commits must include a body with bullet points
- **Bullet points required** - use `- ` prefix for each change item
- **Imperative verbs** - start each bullet with a verb (Add, Remove, Update, Fix, Implement, etc.)
- **Optional paragraphs**:
  - Context paragraph before bullets (to explain background)
  - Explanation paragraph after bullets (to explain why/impact)

**Valid body formats**:
```
# Simple: Just bullet points
- Add feature X
- Update component Y

# With explanation:
- Add feature X
- Update component Y

This improves performance by 50%.

# With context and explanation:
Previous implementation caused memory leaks.

- Refactor memory management
- Add cleanup handlers

Resolves memory issues in production.
```

**Footer** (optional): Blank line after body
- Issue references: `Closes #123`, `Fixes #456`
- Breaking changes: `BREAKING CHANGE: <description>`

## Reference Files

Load only when needed:
- `references/basic-examples.md` - Common scenarios
- `references/types-reference.md` - All types and footer tokens
- `references/breaking-changes.md` - Breaking change examples
- `references/advanced-examples.md` - Complex scenarios


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/basic-examples.md

```markdown
# Basic Commit Examples

Common conventional commit message examples.

## Feature

```
feat(auth): add google oauth login flow

- Add Google OAuth 2.0 configuration and client setup
- Implement backend callback endpoint `/auth/google/callback`
- Create OAuth button component in login UI
- Update user session management to support OAuth tokens

Provides a new authentication option that improves cross-platform
sign-in experience.

Closes #42
```

## Bug Fix

```
fix(api): handle null response in user endpoint

- Add null check before accessing user.data property
- Return 404 status code instead of 500 for missing users
- Add error logging for null user data cases

Prevents server crashes when user data is missing from the database.

Fixes #89
```

## Documentation

```
docs(api): update authentication guide

- Add OAuth 2.0 flow diagrams
- Update code examples to use current SDK version
- Fix outdated endpoint URLs

Improves clarity for developers integrating with the authentication API.
```

## Refactor

```
refactor(auth): extract token validation logic

- Create new TokenValidationService class
- Move JWT validation logic from AuthController to service
- Update AuthController to use new service

Improves testability and reduces coupling. No functional changes.
```

## Performance

```
perf(db): optimize user query with index

- Add composite index on (email, status) columns
- Update user lookup query to utilize new index

Reduces query time from 500ms to 50ms.
```

## Simple Commit

```
feat(lang): add polish language support

- Add Polish translation files (pl.json)
- Update language selector dropdown to include Polish

Expands accessibility for Polish-speaking users.
```

```

### references/types-reference.md

```markdown
# Commit Types and Footer Tokens

## Commit Types

- **`feat:`** - New feature
- **`fix:`** - Bug fix
- **`docs:`** - Documentation changes
- **`refactor:`** - Code change that neither fixes bug nor adds feature
- **`perf:`** - Performance improvement
- **`test:`** - Adding or correcting tests
- **`build:`** - Build system or dependencies
- **`ci:`** - CI configuration
- **`chore:`** - Other changes (not src/test)
- **`style:`** - Formatting, white-space (no code meaning change)

## SemVer

- `fix:` → PATCH
- `feat:` → MINOR
- BREAKING CHANGE → MAJOR

## Footer Tokens

**Issue References:**
- `Closes #123` - Closes issue
- `Fixes #456` - Fixes bug issue
- `Refs: #789` - Related but doesn't close

**Breaking Changes:**
- `BREAKING CHANGE: <description>` - Must be uppercase

**Other:**
- `Reviewed-by: Name`
- `Co-authored-by: Name <email>`
- `Signed-off-by: Name <email>`

**Format:** Token followed by `:` and space, or space and `#`. Multiple footers separated by blank lines.

```

### references/breaking-changes.md

```markdown
# Breaking Changes Examples

## Using "!" in Title

```
feat(api)!: migrate to oauth 2.0

- Remove basic authentication support
- Add OAuth 2.0 client credentials flow
- Update authentication middleware to validate OAuth tokens
- Add token refresh endpoint `/auth/refresh`

Improves security and enables single sign-on capabilities.
All clients must migrate to OAuth 2.0 as basic auth is no longer
supported.
```

## Using BREAKING CHANGE Footer

```
feat(api): migrate to oauth 2.0

- Remove basic authentication support from all endpoints
- Add OAuth 2.0 client credentials flow
- Update authentication middleware to validate OAuth tokens

Improves security posture and enables single sign-on capabilities.

BREAKING CHANGE: Authentication API now requires OAuth 2.0 tokens.
Basic auth is no longer supported. All clients must migrate to
OAuth 2.0 flow. See migration guide at /docs/oauth-migration.

Closes #120
```

## Using Both

```
feat(api)!: migrate to oauth 2.0

- Remove basic authentication support
- Add OAuth 2.0 client credentials flow
- Update authentication middleware

Improves security and enables enterprise SSO integration.

BREAKING CHANGE: Authentication API now requires OAuth 2.0 tokens.
Basic auth is no longer supported. Migration guide at /docs/oauth-migration.

Closes #120
Refs: #115, #122
```

```

### references/advanced-examples.md

```markdown
# Advanced Commit Examples

## Revert

```
revert: let us never again speak of the noodle incident

- Revert commit 676104e implementing feature X
- Revert commit a215868 updating component Y

The original implementation caused critical production issues.

Refs: 676104e, a215868
```

## Multiple Footers

```
fix: prevent racing of requests

- Add unique request ID generation for each API call
- Track latest request ID in component state
- Dismiss responses that don't match latest request ID

Prevents race conditions when rapid requests are made, ensuring
only the most recent response is processed.

Reviewed-by: Z
Refs: #123
Closes #456
```

## Without Scope

```
feat: add polish language support

- Add Polish translation files (pl.json)
- Update language selector dropdown to include Polish

Expands accessibility for Polish-speaking users.
```

```