diff --git a/git-commit/SKILL.md b/git-commit/SKILL.md new file mode 100644 index 0000000..514e569 --- /dev/null +++ b/git-commit/SKILL.md @@ -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 +(): + +- +- +``` + +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. +```