# Writing Commit Messages

> Use when drafting any commit message — sets format (imperative subject under 72 chars, explanatory body when the why isn't obvious from the diff) and prevents the "Fix X" one-liner reflex for non-trivial fixes

- **Type:** Skill
- **Install:** `agentstack add skill-gg-mo-repo-hygiene-writing-commit-messages`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gg-mo](https://agentstack.voostack.com/s/gg-mo)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gg-mo](https://github.com/gg-mo)
- **Source:** https://github.com/gg-mo/repo-hygiene/tree/main/skills/writing-commit-messages
- **Website:** https://github.com/gg-mo/repo-hygiene

## Install

```sh
agentstack add skill-gg-mo-repo-hygiene-writing-commit-messages
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Writing Commit Messages

## Overview

A commit message is the only place future-you (or future-them) finds out WHY a change happened. The diff shows what; the message has to explain why. The honest agent default is a one-liner subject and no body — fine for trivial changes, lossy for everything else.

**Core principle:** The message answers "why," not "what." The diff already shows what.

## The Format

```

```

## Subject Line

- **Imperative mood:** `Fix login failure for apostrophe usernames` — not `Fixed`, not `Fixes`, not `Fixing`.
- **Under 72 chars** (50 ideal). If you need more, the body should be doing that work.
- **No trailing period.**
- **Capitalize the first letter.**

## When To Write a Body

Write a body when ANY of these are true:

- The change fixes a bug — the body explains the root cause and the failure mode
- The change is non-obvious from the diff alone
- The change has a non-obvious motivation (compliance, perf regression, deprecation)
- The change is part of a larger initiative — link to the spec or parent ticket
- The change has subtle behavior (silent failure, edge case, race-condition fix)

Skip the body for: pure renames, formatting / lint fixes, dep version bumps with no behavior change, typo fixes in non-code files.

## Body Content

Include:

- **Symptom / motivation** — what was wrong, or why this exists
- **Root cause** — why the bug existed (for fixes)
- **Approach** — only if non-obvious (`We chose X over Y because Z`)
- **Caveats / follow-ups** — known limitations, deferred work

Leave out: play-by-play of the diff, redundant restatement of the subject, marketing speak.

## Before / After

❌ **One-liner reflex (loses the why):**
```
Fix login bug
```

❌ **What-not-why (diff already shows this):**
```
Update src/auth/validator.ts

Removed the .replace() call in validator.ts.
```

✅ **Subject + body that explains the why:**
```
Fix silent login failure for usernames with apostrophes

The validator was stripping apostrophes via .replace(/'/g, '') before
the database lookup, so users like "O'Brien" were queried as "OBrien"
and silently never matched. Removing the replacement passes the
username through unchanged.

Fixes #482
```

## Common Mistakes

| Mistake | Fix |
|---|---|
| Past-tense subject (`Fixed apostrophe bug`) | Imperative: `Fix apostrophe bug` |
| Subject longer than 72 chars | Move detail to the body |
| Body that restates the subject | Cut it; explain why instead |
| Body that walks through the diff | Cut it; reader can read the diff |
| No body on a non-trivial bug fix | Add one — what was broken, why, how this fixes it |
| `Misc improvements` / `Various fixes` | One logical change per commit. Split first. |
| Mentioning a ticket number without context | Either explain in the body or just leave the trailer |

## Red Flags — STOP

- Subject starts with a past-tense verb
- Subject is your only content for a non-trivial fix
- Body is a list of what you changed (= what the diff shows)
- Multiple unrelated changes in one commit — split first
- About to commit a bug fix with no body explaining the root cause

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gg-mo](https://github.com/gg-mo)
- **Source:** [gg-mo/repo-hygiene](https://github.com/gg-mo/repo-hygiene)
- **License:** MIT
- **Homepage:** https://github.com/gg-mo/repo-hygiene

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gg-mo-repo-hygiene-writing-commit-messages
- Seller: https://agentstack.voostack.com/s/gg-mo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.