/commit: Conventional Commits, changesets and changelogs for your coding agent
An agent skill that writes Conventional Commits in your repo's own dialect, authors changesets automatically, and turns changelogs into release notes anyone can read.
Commits that fit in
Every repository has its own dialect. The skill reads the types, scopes and language yours already uses — from commitlint config, git history and workspace layout — and caches the result so it never has to derive them twice.
fix(ui-button): default missing label and expose aria-disabled
Changesets on autopilot
If the repo versions with changesets, every releasable change gets one in the same commit: right package names from the workspace map, bump level from the commit type, consumer-facing wording. Ignored and private packages are skipped.
Changelogs for humans
Turn any release into plain-language notes grouped by impact, in any language, under one strict rule: every line traces to a real entry. Nothing is invented to sound friendly.
Install
Two ways in: the skills CLI for any agent, or the Claude Code plugin. Pick one — they install the same skill.
Any agent: the skills CLI
One command through the open agent-skills ecosystem. It detects the agents you have and wires the skill into each one.
# Install for this project (Claude Code, Cursor, Codex, +70 agents)
npx skills add EduardoLopes/commit-skill
# Or globally — available in every project
npx skills add EduardoLopes/commit-skill --global
# See what's inside before installing
npx skills add EduardoLopes/commit-skill --listClaude Code: the plugin
Claude Code only, but it updates itself from git and its commands are
namespaced — so /commit keeps working even when another skill on the machine
claims the same name.
# Register the marketplace, then install
/plugin marketplace add EduardoLopes/commit-skill
/plugin install commit@commit-skill
# Pull the newest catalog from git — no re-install needed
/plugin marketplace update commit-skillTo give a whole team the skill with no setup at all, commit this to the repo’s
.claude/settings.json. Every contributor gets /commit on their next launch,
already pointed at your conventions.
{
"extraKnownMarketplaces": {
"commit-skill": {
"source": { "source": "github", "repo": "EduardoLopes/commit-skill" }
}
},
"enabledPlugins": { "commit@commit-skill": true }
}Requirements
Node 18+ for the installer, git, and any supported coding agent (Claude
Code, Cursor, Codex, …). For changeset features your repo needs a package
manager — /commit init sets the rest up for you, installing
changesets v3 when your runtime allows it (Node 22.11+, pnpm 10+, npm 10.9+
or yarn 4.5+) and falling back to v2 otherwise.
Quick start
Stage what you want to ship, then let the skill do the reading:
# Analyze staged changes and commit
/commit
# Validate a message you already wrote (fast path)
/commit -m "feat(auth): add passwordless login"
# Multiple unrelated changes? Split them into atomic commits
/commit --split
# Stage everything and commit, skipping the changeset for once
/commit --all --no-changeset
# Just show me the message, don't commit
/commit --dry-runThe first run in a repository detects your conventions, shows you what it found and offers to cache them. Press Enter to accept — every later run skips detection entirely.
Commands
| Command | What it does |
|---|---|
/commit | Analyze staged changes, write a Conventional Commit, author the changeset if the repo needs one, commit. |
/commit init | Set a repo up for changesets and conventional commits: install @changesets/cli, tailor config, add scripts, cache conventions. Migrates an existing v2 setup to v3. |
/commit changeset | Create or verify changeset files for pending changes without committing anything. Verification runs changeset status --since <base>. |
/commit changelog [version] | Generate, rewrite or translate a changelog or standalone release notes for a version or range. |
Flags for commit
| Flag | What it does |
|---|---|
-m "message" | Validate and format a message you provide — skips file analysis. |
--split | Split unrelated concerns into multiple atomic commits, in dependency order. |
--all | Stage everything before analyzing (the default is staged changes only). |
--no-changeset | Skip changeset handling for this one commit. |
--dry-run | Print the message and changeset preview without committing. |
Flags for changelog
| Flag | What it does |
|---|---|
--plain | Rewrite entries for non-technical readers, grouped by impact: New / Improved / Fixed. |
--lang <code> | Write the output in another language (pt-BR, es, …). Composes with --plain. |
--notes [file] | Emit a standalone release-notes document instead of editing any CHANGELOG. |
How it works
Every repo has its own dialect of Conventional Commits. The skill derives it once and stores it where every future session can see it.
Detection runs in priority order:
- Tooling config. commitlint’s
type-enumandscope-enum, commitizen,CONTRIBUTING.md. These are law — if they exist, they win. - Git history. The last 200 subjects reveal the types actually in use, the rule that generates scopes, and the language your team writes in.
- Workspace layout. pnpm and npm workspaces, turbo and nx config, to map paths onto package names.
<!-- commit-conventions:start -->
## Commit conventions (cached by /commit)
- **Format**: Conventional Commits 1.0.0,
descriptions in English, lowercase
imperative, subject ≤ 72 chars
- **Types**: feat, fix, docs, refactor,
perf, test, build, ci, chore
- **Scope rule**: path under packages/
minus the ui/ segment
- **Versioning**: changesets; patch =
fix, minor = feat, major = breaking
<!-- commit-conventions:end -->The cache lives in CLAUDE.md, so it is committed, reviewable and shared. Edit
it freely — the skill reads what you wrote. Delete the block and it re-detects
from scratch.
Examples
Real outputs from the skill’s test suite: a monorepo bug fix, a repository bootstrap, and customer-facing release notes.
A fix, its commit and its changeset
$ /commit
Analyzing staged changes… 1 file in packages/ui-button
fix(ui-button): default missing label and expose aria-disabled
Created .changeset/ui-button-aria-disabled.md (@acme/ui-button: patch)
and staged it with the commit.---
"@acme/ui-button": patch
---
Buttons no longer render the text "undefined" when created without a
label, and now expose `aria-disabled` so assistive technology announces
the disabled state correctly.The changeset names the real package, takes patch from the commit type, and is
written for the package’s consumers — not for reviewers of the diff.
Bootstrapping a repository
$ /commit init
✓ Installed @changesets/cli
✓ Scaffolded .changeset/config.json (baseBranch: main)
✓ Added scripts: changeset, version-packages, release
✓ Detected conventions from 200 commits — free-form history found,
adopting Conventional Commits 1.0.0 going forward
✓ Cached conventions in CLAUDE.md
✓ Committed: build: set up changesets and conventional commitsRelease notes anyone can read
## 3.2.0
### Minor Changes
- a41f2c9: feat(uploader): add chunked multipart upload with resumable
state persisted to IndexedDB
- 77c01ab: feat(gallery): virtualize grid rendering via IntersectionObserver
### Patch Changes
- 09d11fe: fix(exif): guard against null GPSInfo IFD when parsing orientation
- bb3e802: refactor(store): migrate selectors to memoized createSelector# Photo App — Novidades da versão 3.2.0
## Novidades
- **Envios que continuam de onde pararam.** Se a internet cair ou você
fechar a página no meio de um envio, ele retoma de onde parou.
- **Galeria mais rápida com muitas fotos.** A galeria carrega apenas as
fotos visíveis na tela, conforme você rola a página.
## Correções
- **Fotos sem dados de localização não causam mais erro.**Note what is missing: the internal refactor(store) entry. Changes with no
user-visible effect are dropped, never dressed up as improvements.
Use cases
Every /commit checks whether the staged files touch a published package.
If they do, the changeset is authored and staged in the same commit — right
package names from the workspace map, bump level from the commit type,
ignore, linked and fixed honored. Release PRs stop being archaeology.
History full of "WIP" and "fixed the bug"? Run /commit init: it sets
up changesets, adopts Conventional Commits going forward, and caches the
conventions in CLAUDE.md so every teammate’s agent writes the same style
from day one — no commitlint ceremony required, though if you have
commitlint, its config wins.
/commit changelog 3.2.0 --plain --lang pt-BR --notes produces a
self-contained document you can paste into an email or Slack: grouped by
what’s new, improved and fixed, breaking changes called out with what the
reader must do, and zero invented claims. Product names stay; IndexedDB
goes.
/commit --split groups pending changes into the smallest self-contained
commits — different types, unrelated scopes, independently revertible
chunks — announces the plan, then commits in dependency order with one
changeset per group. A function and its test stay together; a drive-by docs
fix doesn’t ride along with your feature.
FAQ
No. Without .changeset/config.json the skill is a conventions-aware commit
writer. If your repo publishes packages, it will mention /commit init
once — and never nag again.
Fine. For changes that touch a published package but shouldn’t release —
tests, tooling, internal refactors — the skill adds an empty changeset
(changeset add --empty) so changeset status --since main passes without
inventing a release note.
Detection notices free-form history and asks whether to adopt Conventional Commits going forward. If you say no, your existing style is what gets cached — the skill matches the repo, not the other way around.
The skill reports the exact error and stops. It never re-runs a failed hook
blindly, never bypasses with --no-verify, and never partially stages
fixes — hook stash and restore cycles can destroy unstaged work.
No. No Co-Authored-By, no “Generated with…” — unless your repo’s own
conventions require a trailer.
Every line must trace to a real changelog entry, changeset or commit. If an entry is too cryptic to translate confidently, the skill reads the commit it references; if it is still unclear, it keeps the technical wording and flags it rather than inventing a friendly story.