feat(git-commit): add commit message protocol
- Require scoped Conventional Commit headers and semantic bodies that explain behavior and compatibility changes. - Allow known changes or sufficient summaries to replace redundant worktree and staged diff reviews.
This commit is contained in:
parent
2ac55231d1
commit
46d47f9047
1 changed files with 109 additions and 0 deletions
109
git-commit/SKILL.md
Normal file
109
git-commit/SKILL.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
name: git-commit
|
||||
description: Use whenever preparing, reviewing, amending, rewording, or executing a git commit. Enforces Conventional Commits with a scoped header and a semantic diff-backed body.
|
||||
---
|
||||
|
||||
# Git commit message protocol
|
||||
|
||||
Use this skill before staging files or drafting a commit message. Override the
|
||||
default preference for brief commit messages. The message must explain the
|
||||
change well enough to understand the commit without opening its diff.
|
||||
|
||||
## Inspect before staging
|
||||
|
||||
Always run the following before `git add`:
|
||||
|
||||
```sh
|
||||
git status --short --branch
|
||||
git diff --check
|
||||
git log --oneline -10
|
||||
```
|
||||
|
||||
If the current context does not already describe every worktree change well
|
||||
enough to prepare the commit, also run `git diff --stat` and `git diff`.
|
||||
`git diff` does not include untracked files, so read every untracked path shown
|
||||
by `git status`. A summary may substitute for the actual changes when it
|
||||
provides enough context to prepare the commit. Do not re-read changes that are
|
||||
already known from the current context.
|
||||
|
||||
Treat this inspection as a semantic diff check. Identify:
|
||||
|
||||
- The user-visible or operational behavior that changed.
|
||||
- The reason the old behavior was unsafe, incorrect, or insufficient.
|
||||
- The formats, protocols, persistent data, or external interfaces affected.
|
||||
- Tests and compatibility handling that define the new contract.
|
||||
- Unrelated changes that require a separate commit, unless the user explicitly
|
||||
requests one commit containing everything.
|
||||
|
||||
Do not stage until this check is complete. Never infer the commit body from
|
||||
the task description alone.
|
||||
|
||||
## Message structure
|
||||
|
||||
Use this exact shape:
|
||||
|
||||
```text
|
||||
<type>(<scope>): <imperative description>
|
||||
|
||||
- <why this change is needed and what behavior now differs>
|
||||
- <another concrete behavior, contract, or compatibility detail>
|
||||
```
|
||||
|
||||
The header is mandatory and follows Conventional Commits:
|
||||
|
||||
- `type` is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`,
|
||||
`ci`, `chore`, or `revert`.
|
||||
- `scope` is mandatory. Use the narrowest stable subsystem that describes the
|
||||
whole commit, such as `mirror`, `server`, `config`, or `release`. Use a
|
||||
project-level scope only when no subsystem is honest.
|
||||
- The description uses imperative mood, starts lowercase, has no trailing
|
||||
period, and names the behavior rather than the files.
|
||||
- Keep the header at 72 characters or fewer when practical. Never make it
|
||||
vague to satisfy the limit.
|
||||
|
||||
The body is mandatory:
|
||||
|
||||
- Insert one blank line after the header.
|
||||
- Use `- ` bullets.
|
||||
- State WHY the change exists and WHAT behavior or contract changed.
|
||||
- Name affected repository formats, protocols, configuration keys, failure
|
||||
modes, or persisted state when they matter.
|
||||
- Do not narrate implementation steps or list filenames.
|
||||
- Do not add a generic test-results bullet. Include tests only when a fixture,
|
||||
regression, or external compatibility case defines the behavior.
|
||||
- Avoid vague text such as "update files", "fix bugs", "improve handling",
|
||||
or "add support" without naming the exact support.
|
||||
|
||||
Use a `BREAKING CHANGE:` footer when the commit breaks a public contract. Add
|
||||
issue footers only when an issue or ticket is known.
|
||||
|
||||
## Verify after staging
|
||||
|
||||
After staging, always run:
|
||||
|
||||
```sh
|
||||
git status --short
|
||||
git diff --cached --check
|
||||
```
|
||||
|
||||
If the current context does not already describe the staged changes well
|
||||
enough to verify the commit message, also run `git diff --cached --stat` and
|
||||
`git diff --cached`.
|
||||
|
||||
Confirm that the staged semantic diff matches every claim in the message and
|
||||
that every significant staged behavior appears in the body. Rewrite the
|
||||
message when the staged diff and draft disagree.
|
||||
|
||||
Before committing, check recent history for repository-specific scope and
|
||||
wording conventions. Repository convention may refine type or scope names,
|
||||
but it does not remove the scoped header or body requirements in this skill.
|
||||
|
||||
## Example
|
||||
|
||||
```text
|
||||
feat(mirror): verify repository OpenPGP signatures
|
||||
|
||||
- Reject RPM, Debian, and Arch metadata that fails the configured signature policy before its checksums or package paths are trusted.
|
||||
- Preserve the last verified repository generation when signatures rotate inconsistently or required package files remain unavailable.
|
||||
- Allow operators to pin signer keyrings or retrieve unknown issuers from configured keyservers, including archived GnuPG v1 RSA signatures.
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue