# Conventional Commits

> Write Conventional Commits messages (v1.0.0) — type(scope): subject format for changelogs and semver. Use when drafting commit messages, PR titles, or release notes.

- Skill: `knoopx/conventional-commits` (Agent Skill)
- Install (CLI): `npx skillmds@latest add knoopx/conventional-commits`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knoopx/conventional-commits/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: knoopx (https://skillmd.com/u/knoopx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/knoopx/conventional-commits

---


# Conventional Commits (v1.0.0)

Produce consistent commit messages that parse into changelogs and drive semantic versioning.

## Format

```
type(scope): description

[optional body]

[optional footers]
```

Rules: header on one line, scope is always included, separate sections with blank lines. Add `!` before `:` for breaking changes (e.g., `feat(api)!: remove v1`).

## Choosing the Type

**User-facing changes:**

- `feat`: new user-visible behavior — new CLI flags, UI components, API endpoints
- `fix`: corrected behavior — fixes crashes, handles edge cases, corrects output

**Maintenance:**

- `refactor`: structure change without behavior change — renaming, extracting utilities
- `perf`: performance improvement — faster algorithms, reduced allocations
- `chore`: general maintenance — dead code removal, tooling updates
- `style`: formatting only — whitespace, semicolons, no logic changes
- `test`: test-only changes — `.test.ts`, `.spec.ts` files
- `build`: build system — package.json, Cargo.toml, bundler config
- `ci`: CI/CD pipelines — GitHub Actions, deployment scripts
- `docs`: documentation files only — `.md`, `.txt`. Code comments use the type matching the actual code change.

**Reverts:**

- `revert`: undo a previous commit — `revert: <original-message>`

When unsure: new user behavior → `feat`, corrected behavior → `fix`, otherwise → `chore` or a more specific maintenance type.

## Writing the Description

Use imperative mood, be specific, avoid generic words like "stuff" or "changes".

```
✅ feat(auth): add passwordless login
✅ fix(api): handle empty pagination cursor
❌ docs(agent): add behavioral guidelines and core principles  (too vague)
✅ docs(agent): add rules for dead code removal, build verification, security  (specific)
```

## Breaking Changes

Mark in the header with `!`:

```
feat(api)!: remove deprecated v1 endpoints
```

Or add a `BREAKING CHANGE:` footer when you need an explanation:

```
feat(api): remove deprecated v1 endpoints

BREAKING CHANGE: /v1/* endpoints are removed; migrate to /v2/*.
```

## Semantic Versioning Mapping

- `fix` → patch
- `feat` → minor
- Any breaking change (`!` or `BREAKING CHANGE:`) → major

## Rules

- Subject line must be imperative mood ("add" not "added" or "adds")
- No period at end of subject line
- Keep subject under 72 characters
- Use `BREAKING CHANGE:` footer for breaking changes
- Map types to semver: fix→patch, feat→minor, breaking→major

## When Asked to Write a Commit Message

Collect what changed, the scope/module, whether it's user-facing, and any issue IDs. Then produce a conventional header with optional body and footers.