65 added, 47 removed. Audit A to A.
---
name: commit-message
description: >-
- Create commit messages following the Conventional Commits specification based on the actual diff and staged files. Use only when you are asked to create a commit message. Do not use this skill for any other purpose.
+ Create Conventional Commits from the real git status and diff. Use when asked to commit, write a commit message, or split changes into commits. Default: one atomic commit per concern; a single commit only when the user explicitly asks for one.
metadata:
- version: 0.1.0
+ version: 0.2.0
author: "Diego Oliveira"
tags:
- git
- commit
- conventional commits
- commit message
---
# Git Commit with Conventional Commits
- Operate in "Low Reasoning Effort" mode: focus on generating the commit message from the diff and staged files. Terse and exact — no fluff. Why over what.
+ Terse and exact. Why over what. Prefer **atomic** commits — one concern each.
- ## Format
+ ## Workflow
- ```text
- <type>[scope]: <description>
+ ### 1. Survey
- [optional body]
+ Run in parallel:
- [optional footer(s)]
+ ```bash
+ git status --porcelain
+ git diff --staged
+ git diff
+ git log --format=%B -5
```
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
-
- - Subject ≤72 chars, imperative mood ("add" not "added"), no trailing period.
- - Body only when the why is non-obvious, or for breaking changes / migrations.
- Wrap at 72 chars, bullets with `-`.
- - Footers: `Closes #123`, `Refs #456`, `BREAKING CHANGE: ...`.
- - Breaking change: `feat!:` or `BREAKING CHANGE:` footer.
- - Match the project's language and style — determine by checking `git log --format=%B -5`.
+ Completion: every path in status is known, and recent commit language/style is known.
- ## Workflow
+ ### 2. Partition
- ### 1. Analyze the diff
+ **Default — atomic:** Group every path from status into concerns. A concern is a distinct Conventional Commits `type`, `scope`, or intent (e.g. `feat` vs `fix` vs `docs`; two unrelated features; a refactor that only enables a feat). One group → one commit.
- ```bash
- git diff --staged # prefer staged; fall back to working tree
- git diff
- git status --porcelain
- ```
+ **Single-commit branch:** Collapse all safe paths into one group only when the user explicitly asks for a single commit (e.g. "one commit", "single commit", "só um commit"). Silence means atomic.
- ### 2. Stage (if needed)
+ Exclude secrets and sensitive files from every group (`.env`, keys, credentials).
- ```bash
- git add -A # or stage specific files/patterns/hunks
- ```
+ Completion: every path in status is in exactly one group, or excluded as secret/sensitive with that exclusion noted.
- Never stage secrets (`.env`, keys, credentials).
+ ### 3. Stage, message, commit — once per group
- ### 3. Execute the commit — use heredoc
+ For each group, in a sensible order (deps/infrastructure before dependents when it matters):
- Heredoc avoids shell escaping issues and works across zsh/bash:
+ 1. Stage **only** that group's paths (`git add -- path…`). Never `git add -A` while splitting.
+ 2. Draft the message from that group's diff only — see Format.
+ 3. Commit with heredoc:
```bash
git commit -F <(cat << 'EOF'
<type>[scope]: <description>
- why this change, if not obvious.
- - additional context.
- Closes #123, Refs #456
+ Closes #123
EOF
)
```
- Single-line fallback: `git commit -m "<type>[scope]: <description>"`. Avoid `dquote>` interactive prompts and never use `-i`.
+ Single-line fallback when no body: `git commit -m "<type>[scope]: <description>"`. Never use `-i`.
- ## What never goes in
+ On hook rejection: fix the issue and create a **new** commit for that group — do not amend on the first attempt.
- - "This commit does X", "I", "we", "now", "currently" — the diff says what.
- - AI attribution ("Generated with Claude", "Co-authored-by Claude") unless the project's own rule requires an AI-attribution trailer.
- - Restating the filename when scope already says it.
- - Emoji (unless project convention requires).
- - Trailing notes like "All changes committed locally; no push performed."
+ Completion: every group has a successful commit; remaining status is empty or only the excluded secrets.
- ## Safety protocol
+ ## Format
- - NEVER update git config, force push, or run destructive commands (`--force`, hard reset) without explicit request.
- - NEVER skip hooks (`--no-verify`) unless the user asks.
- - NEVER push or offer to push / open a PR — create the commit locally for review.
- - NEVER commit secrets or sensitive files.
- - If a commit fails (hook rejection, etc.), fix the issue and create a NEW commit — do not amend on the first attempt.
+ ```text
+ <type>[scope]: <description>
- ## Auto-Clarity
+ [optional body]
- Always include a body for: breaking changes, security fixes, data migrations, or reverts of prior commits. Never compress these into subject-only.
+ [optional footer(s)]
+ ```
+ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
+
+ - Subject ≤72 chars, imperative mood ("add" not "added"), no trailing period.
+ - Body only when the why is non-obvious, or for breaking changes / migrations. Wrap body at 72 chars; bullets with `-`.
+ - Footers: `Closes #123`, `Refs #456`, `BREAKING CHANGE: ...`.
+ - Breaking change: `feat!:` or `BREAKING CHANGE:` footer.
+ - Match the project's language and style from `git log --format=%B -5`.
+
+ Always include a body for: breaking changes, security fixes, data migrations, or reverts of prior commits.
+
+ ## Message content
+
+ Write the why, not a restatement of the diff. Subject carries the change; body carries non-obvious motive, migration notes, or breaking detail. Scope names the area — omit the filename when scope already covers it. Use emoji only when the project's log already does. Add AI attribution trailers only when the project's own rule requires them.
+
+ ## Safety
+
+ Hard guardrails — pair each with the target behavior:
+
+ - Leave git config untouched; create the commit locally for review (no push, no PR offer, no force-push, no hard reset) unless the user explicitly requests that action.
+ - Run hooks normally; skip (`--no-verify`) only when the user asks.
+ - Keep secrets out of the index and the commit.
+ - On failure, fix and create a new commit — amend only when the user explicitly asks and amend rules in the user rules allow it.
+
## Examples
```text
feat(api): add GET /users/:id/profile
Mobile client needs profile data without the full user payload to
reduce bandwidth on cold-launch screens.
Closes #128
```
```text
feat(api)!: rename /v1/orders to /v1/checkout
BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026-06-01. Old route returns 410 after that date.
```
```text
fix(auth): validate session before token refresh
+ ```
+
+ Atomic split from one dirty tree (illustrative grouping):
+
+ ```text
+ # group A — auth fix
+ fix(auth): validate session before token refresh
+
+ # group B — unrelated docs
+ docs(readme): document session refresh flow
```