git-commit-helper-guide
A practical guide to crafting atomic commits and clear Conventional-Commit messages — use when committing or standardizing team history.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- git-commit-helper-guide
- category
- git
- description
- A practical guide to crafting atomic commits and clear Conventional-Commit messages — use when committing or standardizing team history.
03 SKILL.md 正文
Overview
Good commits are small, self-explanatory units of change with messages that tell future readers why the change exists. This guide covers the full craft: splitting work into atomic commits, writing messages in the Conventional Commits style, and keeping branch history reviewable — whether you write messages by hand or draft them with AI assistance.
When to use
- Turning a messy working tree into clean, logical commits
- Writing commit messages that explain rationale, not just content
- Adopting Conventional Commits (
feat:,fix:) on a team - Tidying a branch before opening a pull request
- Reviewing commit quality in code review
Core concepts
Atomicity. Each commit should contain one logical change, build cleanly,
and be independently revertable. A commit that "fixes the login bug" shouldn't
also reformat unrelated files. Use git add -p to stage hunks selectively
and split work that grew together.
Conventional Commits format. type(scope): subject — e.g.
fix(auth): handle expired refresh tokens. Common types: feat, fix,
docs, refactor, test, chore, perf. Scopes name the affected area.
A BREAKING CHANGE: footer flags incompatible changes. The format makes
history searchable and changelogs automatable.
Subject line discipline. Imperative mood ("Add", not "Added"), under ~72 characters, no trailing period. It should complete the sentence "This commit will…". Everything else goes in the body.
The body carries the why. Diffs show what changed; bodies explain the reasoning: the bug or requirement, alternatives considered, risks, and links to issues or discussions. A body written today saves an hour of archaeology in six months.
Private history is malleable; public history is not. Rebase, squash, and
reword freely on branches only you use. Once pushed and shared, prefer
git revert over rewriting — your teammates' clones depend on stable history.
Practical workflow
- Inspect before committing:
git statusandgit diff— confirm the staged changes are exactly one logical unit; split withgit add -pif not. - Draft the message: type + scope + imperative subject; body with context, rationale, and issue references; breaking changes in the footer.
- Example:
feat(payments): retry failed webhooks with exponential backoff Webhook delivery failures during the provider outage (INC-118) were dropped silently. Adds a retry queue: 3 attempts, backoff 1m/5m/30m, then dead-letter with an alert. Chose backoff over immediate retry to avoid hammering the provider during partial outages. Fixes #482. - Tidy before sharing:
git rebase -i mainto squash "wip"/"fix typo" commits, reorder logically, and strengthen weak messages. - Verify:
git log --oneline -8should read as a coherent story; each commit message should make sense without opening the diff. - If using AI to draft messages: always review the generated "why" — models write plausible rationale that may not match your actual reasoning; correct it before committing.
Common pitfalls
- Vague subjects ("update", "fix bug", "changes") — permanent noise in
git logandgit blame. - Mega-commits bundling unrelated changes — unreviewable and dangerous to revert; split them.
- Body that restates the diff — "changed X to Y" adds nothing; explain the decision instead.
- Forgetting the issue link — without a reference, the business context behind a fix evaporates.
- Amending or rebasing shared branches — rewrites history others depend on; restrict rewriting to private branches.
- Inconsistent types/scopes across the team — half the history using
feat:and half using freeform defeats the purpose; agree once, lint in CI.
04 同仓库更多 Skills
web-scrape
Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.
design-taste-frontend
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).