Conventional commits

Skill stealth-engine/skills/skills/conventional-commits

Agent skills we use daily in the studio — reusable, on-demand context for Claude Code, Cursor & other skills.sh-compatible AI agents. Install: npx skills add stealth-engine/skills

Install

npx -y skills add stealth-engine/skills --skill conventional-commits

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 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 Commits format — also called "semantic commits" / semantic commit messages — a `type(scope): description` header (`feat`, `fix`, …) plus an optional `BREAKING CHANGE` footer, and how it makes history machine-readable to drive automated version bumps and changelogs. Use when writing a commit message or PR title, deciding the type/scope/bump for a change, setting up or fixing a repo's commit convention, making commits parseable by semantic-release / changelog tooling, validating PR titles, or when a release didn't bump or the changelog came out blank because a commit wasn't conventional. Covers the type→semver mapping, breaking changes, scopes, monorepo scopes, and squash-merge PR titles.

SKILL.md

8.3 KB, as published. Nobody here has run it

Conventional Commits (a.k.a. semantic commit messages)

A commit convention that makes history machine-readable: a parser reads each message, decides the next semver version, and builds the changelog from it. "Semantic commits" is the common nickname for the same thing. It's the foundation the release automation stands on — semantic-release-automation covers the tooling that consumes these messages.

The format

<type>[(<scope>)][!]: <description>

<optional body — the "why", wrapped>

<optional footer(s) — BREAKING CHANGE:, Closes #123, Refs: ABC-12>

type / scope: lowercase by convention — the spec is case-insensitive, except BREAKING CHANGE, which MUST be uppercase. scope is an optional noun in parens for the area touched.
! before the colon or a BREAKING CHANGE: footer marks a breaking change (BREAKING-CHANGE: with a hyphen is an accepted synonym).
description: concise; by convention imperative mood, lowercase, no trailing period (Angular/commitlint style — the spec itself mandates none of these).
Blank line before any body/footer.

feat(auth): add passkey sign-in
fix(parser): handle empty input without throwing
feat(api)!: drop the v1 token endpoint
docs: fix typo in install steps

Types → meaning → version bump

These are the semantic-release defaults (the angular preset plus commit-analyzer's built-in release rules). They're configurable via releaseRules, but treat them as the contract.

Type	Use for	Default release
`feat`	a new feature	minor (`x.Y.0`)
`fix`	a bug fix	patch (`x.y.Z`)
`perf`	performance improvement	patch
`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`	maintenance, no user-facing behaviour change	no release on their own
`revert`	revert a previous commit	patch (the change is being undone)
any type with `!` / `BREAKING CHANGE:`	incompatible change	major (`X.0.0`)

The "no release" types still belong in history — the tooling just won't cut a version for them alone. A release containing only chore/docs commits produces no new version, which is usually correct.

Breaking changes

Either form triggers a major bump and a highlighted changelog section:

feat(api)!: require auth on all routes

…or via a footer (works on any type, and lets you explain the migration):

refactor(db): rename users.email column

BREAKING CHANGE: `users.email` is now `users.email_address`; update queries.

Scopes

Optional, but meaningful: a noun naming the area (fix(toggle): …). In a monorepo the scope is how releases/changelogs are routed per package — repos often require it (e.g. feat(web-app): …, feat(react-typed-form-kit): …). Keep a scope vocabulary documented so it stays consistent.

Squash merges: the PR title is the commit

With squash merging (the common modern setup), the PR title becomes the single commit message on main — so the PR title must be a valid Conventional Commit, or the release/changelog step sees a non-conventional message and skips it. Put the individual semantic commits in the squash body for detail. git-trunk-branch-and-pr-automation covers the CI that enforces this.

Caveat: the title only becomes the commit when the repo's squash setting is "Default to pull request title". With GitHub's out-of-the-box "Default message", a single-commit PR reuses that commit's message instead of the title — so a non-conventional lone commit still skips the release even though the PR title looks fine. Set the repo to default to the PR title, or keep the single commit conventional too.

Single-package repo: the title's scope is optional.
Monorepo: scope the title to the package, and keep a PR to one package where practical — a squash collapses everything to one type+scope, so a multi-package PR applies the same bump to all and muddies per-package changelogs.

Writing good ones

Imperative mood: "add", not "added"/"adds" (it completes "this commit will…").
Keep the subject short: the spec sets no limit; commitlint defaults to 100 chars and Git display favours ~72 — match the project's commitlint config. The body explains why, not what.
One logical change per commit. If a change is genuinely both a feature and a fix, split it; if you can't, the type reflects the highest-impact change (a feat that also fixes something is feat).
Reference issues in the footer: Closes #123, Refs: ABC-12.

Gotchas

Non-conventional → silently no release. A typo'd type or a prose subject is ignored by the analyzer: no bump, no changelog entry. This is the #1 "why didn't it release / why is the changelog blank?" cause — check the merge commit / PR title first.
Don't hand-write chore(release): … commits. Those are produced by the release bot; writing one yourself can confuse tooling (and such commits are often CI-skipped deliberately).
Issue IDs in the subject can misbehave. A Linear/Jira key like ABC-123 in the subject may auto-transition the ticket or render oddly in changelog links; some setups keep IDs in the footer or de-link them (ABC-123 → ABC - 123) in the generated changelog.
Revert format: a header revert: <subject of the reverted commit> plus a body line This reverts commit <sha>. — that body line is what the parser keys on. The semantic-release parser is case-insensitive and also matches git's default Revert "<subject>" header, so an untouched git revert commit is recognised — but commitlint / PR-title validators reject Revert as a type, so lowercase the header to revert: to pass those. Reverts default to a patch release.

Verify

Lint locally or in CI with commitlint (@commitlint/config-conventional), or validate PR titles with a PR-title action (see git-trunk-branch-and-pr-automation).
Confirm the intended bump with a semantic-release dry run (npx semantic-release --dry-run) — it prints the next version and release notes without publishing.

Sources

Conventional Commits 1.0.0 — grammar, the ! / BREAKING CHANGE rules, the BREAKING-CHANGE hyphen synonym, and case-insensitivity (except BREAKING CHANGE, which must be uppercase): https://www.conventionalcommits.org/en/v1.0.0/
semantic-release commit-analyzer default release rules (angular preset) — feat→minor, fix/perf→patch, breaking→major, revert→patch, every other type → no release: https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-rules.js
The type list and per-package scope rules also match conventions enforced in production repos (a production app's PR-title validator allows feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert; a production monorepo requires per-package scopes).