YourAKShaw/conventional-commits-framework

Complete, atomic, co-authored commits from every AI agent, every time.
An agent skill that turns the Conventional Commits spec into commit messages people want to read and release tools can trust.
Explore the skill · Commit protocol · Examples · Contribute · Get help
## Commits are the record your project keeps
AI agents now write a large share of commits, and they tend to write them in a hurry: fix: update, no body, an invented type, a breaking change nobody flagged, and an attribution line that changes from one session to the next. Each one costs a reviewer time, hides a reason that someone will need later, or ships the wrong version.
Conventional Commits Framework gives your agent one clear standard and the tools to meet it. Every commit is complete, sized to one logical change, and credits both you and the agent in exactly the same way across the whole repository.
text
fix(auth): reject expired refresh tokens before rotation
Refresh tokens were rotated before their expiry was checked, so a
stolen expired token could still mint a new session. Validate expiry
first and return 401 without touching the token store.
Breaking: none
Refs: #318
Co-Authored-By: Claude Code
## ✨ Four rules, no exceptions
| | Rule | What your agent does |
| 🧾 | Complete | Fills every field (type, scope, subject, body, breaking declaration, co-author) on every commit. Nothing is left blank. |
| 📏 | Standard length | Writes 10-50 character subjects, 2-6 line bodies that explain why, and one-line trailers. No stubs, no essays. |
| 🤝 | Co-authored | Keeps you as author and committer, and credits itself through one fixed Co-Authored-By trailer that never varies. |
| ⚛️ | Atomic | Plans large work as a sequence of small commits, each one logical change that builds, reverts, and changelogs cleanly. |
## 🧠 What the skill knows
| Capability | In practice |
| Type and scope judgment | An ordered decision procedure and tie-breakers for the confusions behind most convention failures (fix or feat, refactor or perf, build or chore). |
| Breaking-change safety | Detection across code, HTTP, CLI, config, data, and runtime surfaces, plus migration notes that tell consumers what to do. |
| Verified format traps | Why BREAKING CHANGE: none publishes a major version, and why the spaced token hides your co-author trailer from git. |
| Repository awareness | Reads AGENTS.md, contributing guides, commitlint config, and history before the first commit, and follows the project's conventions. |
| Validation and review | Explains all 38 commitlint rules and reports errors separately from style suggestions, each with a corrected message. |
| Enforcement setup | Ready-made commitlint config, commit template, hooks, CI workflows, monorepo scope presets, and release tooling. |
## 🔍 Verified, not assumed
The format rules in this skill were checked against real tooling, not copied from blog posts:
| Claim | Verified with |
| BREAKING CHANGE: none and Breaking-Change: none create breaking notes | conventional-commits-parser 7.1.3 |
| A spaced BREAKING CHANGE: footer hides Co-Authored-By from git | git interpret-trailers --parse |
| BREAKING-CHANGE: with indented continuation lines keeps every trailer | git, the parser, and @commitlint/cli 21.2.4 |