Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/snowfluke/engineering-skills --skill git-commitAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
Skill: git-commit
When to Use
You have completed a task, all verifications have passed, and you need to commit the changes.
Steps
- 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.jsonscripts,Makefile,justfile,cargo,go,mix,pytest).
Example (bun + TypeScript):
bun run type-check
bun test
bun run lint
bun run fmtIf any fails, stop and fix the issue before committing.
- Check what will be staged:
git status
git diff --stat- 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:
# 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.
- Stage the relevant files for the current commit. Be explicit. Do not use
git add -Ablindly:
git add apps/api/src/modules/projects/
git add apps/api/src/db/migrations/0003_add_project_archive.sql
# etc.Never stage:
.envfiles*.pemkey 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__/)
- Compose the commit message. First check the project's own convention:
CONTRIBUTING.md, acommitlint.config.*file, a commit-msg hook, and the style ofgit log --oneline -20. The project's convention wins. Where it says nothing, use Conventional Commits:
Format: <type>(<scope>): <subject>
| Type | Use when |
|---|---|
feat | New feature or behavior |
fix | Bug fix |
refactor | Code change with no behavior change |
test | Adding or fixing tests |
docs | Documentation changes only |
chore | Build config, tooling, dependency updates |
perf | Performance 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
@somethingas a user mention and notifies whoever owns that handle. For version pins, writev4/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:
awk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt
git commit -F /tmp/commit-msg.txtNo output from awk means every line fits.
For quick subject-only checks:
echo -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c
# must be 80 or fewer- Create the commit:
git commit -m "feat(projects): add project creation endpoint [BE-S2-02]"For multi-line commits (when the "why" is non-obvious):
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.
- Repeat for the next logical commit if the working tree still has unstaged changes from a different intent. Return to step 3.
- Verify the commits:
git log --oneline -5- 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.
- Create the tag and release. For most repos, the one-liner is fine: it
creates the tag at the branch tip:
gh release create vX.Y.Z --target main --title "vX.Y.Z" --notes-file notes.mdOnly 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):
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- 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.
- 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).
- 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
.envfiles staged - [ ] No
*.pemkey 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 (usev5or backticks for version pins) - [ ] Task ID referenced in subject when applicable
Examples
# 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