AGENT SKILL

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
所属仓库
TanNhatCMS/jarvis
最近更新
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

  1. Inspect before committing: git status and git diff — confirm the staged changes are exactly one logical unit; split with git add -p if not.
  2. Draft the message: type + scope + imperative subject; body with context, rationale, and issue references; breaking changes in the footer.
  3. 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.
    
  4. Tidy before sharing: git rebase -i main to squash "wip"/"fix typo" commits, reorder logically, and strengthen weak messages.
  5. Verify: git log --oneline -8 should read as a coherent story; each commit message should make sense without opening the diff.
  6. 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 log and git 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

TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

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).

★ 0