snowfluke/engineering-skills

git-commit

Use after completing a task when all verifications pass, to commit the work, or when cutting a GitHub release.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/snowfluke/engineering-skills --skill git-commit

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Skill: git-commit

When to Use

You have completed a task, all verifications have passed, and you need to commit the changes.

Steps

  1. Run final verification. All checks must pass. Use the project's own gate: type-check (if the language has one), tests, lint, and format. Read the project manifest / task runner for the exact commands (e.g. package.json scripts, Makefile, justfile, cargo, go, mix, pytest).

Example (bun + TypeScript):

bash
   bun run type-check
   bun test
   bun run lint
   bun run fmt

If any fails, stop and fix the issue before committing.

  1. Check what will be staged:
bash
   git status
   git diff --stat
  1. Split into logical commits. Before staging, scan the diff and group changes by intent. Do not put unrelated changes into one commit. A commit should answer a single "why."

Common splits:

  • Bug fix vs version bump -> two commits
  • Source code change vs test additions for an unrelated module -> two commits
  • Refactor vs new feature -> two commits
  • Code change vs docs/CHANGELOG update for that same code -> can be one commit
  • Code change vs unrelated formatting noise -> two commits (or revert the noise)

If the working tree has multiple intents, commit them in sequence:

bash
   # Commit 1: the fix
   git add src/auth/session.ts tests/auth/session.test.ts
   git commit -m "fix(auth): handle expired refresh token gracefully"

   # Commit 2: the version bump (separate intent)
   git add package.json jsr.json
   git commit -m "chore: bump version to 5.4.2"

When uncertain whether two changes belong together, the test is: "Could someone want to revert one without the other?" If yes, split.

  1. Stage the relevant files for the current commit. Be explicit. Do not use git add -A blindly:
bash
   git add apps/api/src/modules/projects/
   git add apps/api/src/db/migrations/0003_add_project_archive.sql
   # etc.

Never stage:

  • .env files
  • *.pem key files
  • Lockfile changes for unrelated packages (e.g. bun.lock, package-lock.json, Cargo.lock, go.sum, poetry.lock)
  • Build output (e.g. dist/, .next/, target/, build/, __pycache__/)
  1. Compose the commit message. First check the project's own convention: CONTRIBUTING.md, a commitlint.config.* file, a commit-msg hook, and the style of git log --oneline -20. The project's convention wins. Where it says nothing, use Conventional Commits:

Format: <type>(<scope>): <subject>

TypeUse when
featNew feature or behavior
fixBug fix
refactorCode change with no behavior change
testAdding or fixing tests
docsDocumentation changes only
choreBuild config, tooling, dependency updates
perfPerformance improvement

Scope: the module or layer changed (e.g., auth, tasks, gantt, db, ci)

Subject rules:

  • Imperative mood: "add", "fix", "refactor", not "added" or "fixing"
  • Max 80 characters for the entire first line (type(scope): subject [ID] combined). A commit-msg hook (e.g. husky/commitlint) often enforces this for the subject line.
  • No period at end
  • Reference task ID when applicable: [BE-S2-02]
  • Never write `@<name>` or `@<digit>` anywhere in the message. GitHub renders @something as a user mention and notifies whoever owns that handle. For version pins, write v4 / v5, major 4, or wrap in backticks (` @4 `). The same rule applies to commit bodies, PR titles, PR bodies, issue comments, and release notes.

Body rules (for multi-line commits):

  • Every line in the body is also capped at 80 characters. Hard-wrap long sentences manually.
  • One blank line between subject and body.
  • One blank line between paragraphs in the body.

Before committing, write the message to a file and check every line:

bash
   awk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt
   git commit -F /tmp/commit-msg.txt

No output from awk means every line fits.

For quick subject-only checks:

bash
   echo -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c
   # must be 80 or fewer
  1. Create the commit:
bash
   git commit -m "feat(projects): add project creation endpoint [BE-S2-02]"

For multi-line commits (when the "why" is non-obvious):

bash
   git commit -m "feat(tasks): enforce finish-to-start dependency [BE-S3-03]

   Task B's checkbox is disabled when its prerequisite (Task A) is
   not yet in completed status. Auto-unlock triggers after Task A
   completes, changing Task B from locked to ready."

Do NOT add `Co-Authored-By` trailers. Commits are authored solely by the developer. No AI attribution lines.

  1. Repeat for the next logical commit if the working tree still has unstaged changes from a different intent. Return to step 3.
  1. Verify the commits:
bash
   git log --oneline -5
  1. Report to the user: commit hashes and messages for every commit you made.

Creating a GitHub Release

When the commit is a release (chore: release vX.Y.Z) and the version bump has landed on the default branch, cut the release.

  1. Create the tag and release. For most repos, the one-liner is fine: it

creates the tag at the branch tip:

bash
   gh release create vX.Y.Z --target main --title "vX.Y.Z" --notes-file notes.md

Only if the project requires signed tags (OpenSSF Best Practices Gold `version_tags_signed`, or an org supply-chain policy): `gh release create --target` makes an unsigned* server-side tag, and tag.gpgSign=true does NOT help, because gh creates the tag server-side, bypassing local git signing. You must tag locally (which signs per config), push it, then create the release from the existing tag (no --target):

bash
   git tag -s vX.Y.Z <commit> -m "vX.Y.Z"   # signed (gpg or ssh-format key)
   git push origin vX.Y.Z
   gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md   # no --target
   git verify-tag vX.Y.Z
  1. The title is the version and nothing else: vX.Y.Z. No tagline, no

emoji, no "Release", no emoji, no summary. The body carries the detail.

  1. The body is written by the `release-notes` skill. Invoke it rather

than pasting the CHANGELOG section in: the changelog is the complete record for existing users, the notes are for someone deciding whether to adopt. State facts only: no marketing, no filler ("we're excited to", "huge improvements"), no slop. The @<name>/@<digit> rule applies there too: never in release notes (use v4 or backticks).

  1. Verify after publish: the publish workflow run is green and the registry

shows the new version (npm view <pkg> version, JSR meta.json); signed release artifacts are attached if the project signs them.

Checklist Before Done

  • [ ] Type-check passed (if the language has one)
  • [ ] Tests passed
  • [ ] Lint passed
  • [ ] Format passed
  • [ ] No .env files staged
  • [ ] No *.pem key files staged
  • [ ] Unrelated changes split into separate commits (one intent per commit)
  • [ ] Commit message follows Conventional Commits format
  • [ ] Scope matches the affected module
  • [ ] Subject uses imperative mood
  • [ ] Subject line is 80 characters or fewer (verified with echo -n "..." | wc -c)
  • [ ] Every body line is 80 characters or fewer
  • [ ] No @<name> or @<digit> anywhere in subject or body (use v5 or backticks for version pins)
  • [ ] Task ID referenced in subject when applicable

Examples

bash
# Good
feat(tasks): add dependency enforcement on task completion [BE-S3-03]
fix(auth): handle expired refresh token gracefully
test(projects): add service unit tests for template change [BE-S2-11]
chore(ci): add coverage threshold check to CI workflow
docs(onboarding): update setup steps for Docker dev environment
chore: bump demo CDN pin from v4 to v5

# Bad
update code
fix bug
WIP
added the task thing
chore: bump demo CDN pin from @4 to @5     # `@4`/`@5` become user mentions
fix: do thing and also bump version         # two intents: split into two commits
来自同一仓库

更多 Skills

全部 Skills