martinffx Conventional Commit Skill
Create coherent, reviewable commits that follow the Conventional Commits specification. Message syntax matters, but the selected changes must tell one clear story too.
Message Format
Every generated commit has a title and body:
<type>(<scope>): <imperative title>
<1-5 lines describing the change and, when useful, its reason or effect>
Use a lowercase scope that identifies the affected component. The title is concise, imperative, lowercase, and has no trailing period. The body is concrete: explain the behavior, motivation, or important implementation decision rather than restating the title.
| Type | Use for |
|---|---|
feat |
New user-facing capability |
fix |
Corrected behavior |
docs |
Documentation only |
style |
Formatting only |
refactor |
Restructuring without behavior change |
test |
Tests only |
chore |
Maintenance or tooling |
perf |
Performance improvement |
ci |
Continuous integration configuration |
build |
Build system or dependencies |
revert |
Reverting a prior commit |
Breaking changes may use ! after the type or scope, a BREAKING CHANGE: footer, or both.
Include issue footers such as Closes #123 only when the issue is known.
Create a Commit
When the user asks to commit, first inspect the complete worktree:
- Run
git status --short. - Read both
git diff --cachedandgit diffso pre-staged work is not mistaken for the entire change. - List untracked files with
git ls-files --others --exclude-standardand inspect relevant ones. - Read recent subjects with
git log --oneline -10to match established scopes and wording. - Flag likely secrets, credentials, local configuration, or generated output. Do not stage them without explicit direction.
Decide Whether to Split
Default to one commit containing all intended, related changes. Look for an obvious file-level split only when changes are independent and each group can stand alone.
Keep these together:
- Implementation and its tests.
- Documentation that describes the same change.
- Dependency manifests and their lockfiles.
Do not invent a split for adjacent work, use hunk-level staging, or force the user to reorganize a coherent change. If an obvious split exists, propose each commit with its files and full message, then ask once for approval. If not, propose one commit.
Approve, Stage, Commit
Before making any write, show:
- The files in each proposed commit.
- The full title and 1-5 line body for each commit.
- Any excluded files and why they are excluded.
Ask for approval unless the user explicitly authorizes committing immediately. After
approval, stage only the files for the approved commit with git add -- <paths> and
inspect git diff --cached --name-status and git diff --cached again. If the staged snapshot
contains any unapproved file, stop and ask how to handle it. Then commit with the proposed title
and body. Do not amend, rebase, push, or include unapproved files.
Repository commit hooks are the final message validation when configured. Never bypass a failing hook. Report the commit hash on success; report the error and leave changes intact on failure.
Validate a Commit Message
When the user asks to validate a message, check:
- It follows
type(scope): imperative title. - The type is listed above and the scope is lowercase.
- The title is lowercase, imperative, concise, and has no trailing period.
- A body follows after a blank line and contains 1-5 meaningful lines.
- Breaking changes use both
!and aBREAKING CHANGE:footer.
Return specific corrections and a revised message. When the repository configures commitlint, use it as the authoritative validation rule.
Delegated: Pull Request Creation
If the user wants to create a PR after committing, invoke the
code-pull-request skill. It detects the platform
(GitHub/GitLab), finds a template, generates the body, and opens the PR via gh
or glab.
Input Methods
| Input | Action |
|---|---|
| User says "commit" or "git commit" | Inspect the worktree, propose coherent commit(s), then commit after approval |
| User says "validate commit" | Check the commit message format |
| User pastes commit message | Validate the provided message |
Error Handling
- If there are no changes: report that there is nothing to commit.
- If Git is not initialized: report it; do not initialize a repository unless asked.
- If a commit fails: show the error, preserve the worktree, and do not bypass hooks.
Examples
Input: "I fixed the login bug" Output:
fix(auth): resolve login timeout issue
Correct token expiry calculation so active users are not logged out after five minutes.
Input: "I added a new API endpoint for users" Output:
feat(api): add user profile endpoint
Expose name, email, and avatar URL from `GET /users/:id`.
Closes #89
Input: "I changed the auth API, this breaks old clients" Output:
feat(auth)!: change token validation endpoint
Require a Bearer token on `/auth/verify` instead of a query parameter.
BREAKING CHANGE: Clients must update to send
Authorization header with Bearer token.