📜 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.
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 <[email protected]>
✨ 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 |
| An emoji after the colon parses; one before the type does not | conventional-commits-parser 7.1.3 |
@commitlint/rules ships 38 rules | @commitlint/rules 21.2.4 |
| All 22 example messages satisfy the contract | scripts/lint-commit.py and the contract commitlint config |
📥 Get started
Keep SKILL.md, references/, assets/, and scripts/ together so the skill can resolve its resources.
Skills CLI: any supported agent
npx skills add YourAKShaw/conventional-commits-framework
Follow the prompts to choose your agent and scope. To target Claude Code directly, add --agent claude-code, and add --global for a personal installation across projects. See the Skills CLI documentation.
Claude Code: clone
# Personal, across all your projects
git clone https://github.com/YourAKShaw/conventional-commits-framework.git ~/.claude/skills/conventional-commits-framework
# Project only: run from the project root
git clone https://github.com/YourAKShaw/conventional-commits-framework.git .claude/skills/conventional-commits-framework
Then type /conventional-commits-framework in Claude Code, or just ask Claude to commit; it loads the skill for matching tasks. See the Claude Code skills documentation.
Claude apps: upload a ZIP
- Download the repository ZIP, extract it, and rename the folder to
conventional-commits-framework.
- Compress that folder so the archive contains
conventional-commits-framework/SKILL.md.
- Enable Code execution and file creation under Settings → Capabilities, then upload the ZIP under Customize → Skills.
See Claude's skill upload instructions.
💬 Put it to work
Commit as you go
Use the Conventional Commits Framework while you implement this feature. Plan the commits first and commit each step as you finish it.
Draft a message
Write a complete conventional commit for the staged diff.
Review history
Check the commits on this branch against the commit contract and give me corrected messages for any that fail.
Plan a split
These changes are all in my working tree. Propose a sequence of atomic commits with complete messages.
Set up enforcement
Add commitlint and a commit-msg hook that enforce the commit contract in this repository.
📚 Inside the skill
| Reference | Covers |
|---|
| Agent commit protocol | The Complete Commit Contract, field lengths, co-authorship, PRs, the pre-commit checklist |
| Atomic commits | Smallest logical change, splitting seams, planning commit sequences |
| Type and scope catalog | The eleven standard types, the decision procedure, scope selection |
| Breaking changes | Detection, declaration, format traps, migration notes |
| Example library | 22 complete messages and a before-and-after table |
| Rules reference | All 38 commitlint rules with defaults and contract settings |
| Config guide | Discovering conventions, commitlint files, precedence |
| Monorepo patterns | Package scopes, cross-package changes, workspace presets |
Assets and scripts
conventional-commits-framework/
├── SKILL.md # Entry point: the four rules, workflows, traps, routing
├── references/ # Ten focused guides, loaded on demand
├── assets/ # commitlint config and git commit template
├── scripts/ # Contract checker, package validator, tests
├── .github/ # Contributing, support, templates, CI
├── README.md # Project overview
├── SECURITY.md # Supported versions and vulnerability reporting
└── LICENSE # MIT License
✅ Validate
From the repository root, with Python 3.9+:
python3 scripts/validate-skill.py # package structure and links
python3 scripts/test_lint_commit.py # contract checker regression tests
python3 scripts/test_validate_skill.py # validator regression tests
This repository follows its own rules: every commit in its history passes scripts/lint-commit.py.
🤝 Contributing and support
Improvements are welcome, especially real commit-message failures the skill does not yet prevent. Start with the contribution guide, use the issue forms, read the support guide, or report vulnerabilities privately as described in the security policy.
License
Distributed under the MIT License. See LICENSE.
