# Commit

> Creates atomic git commits with terse, exact Conventional Commits messages, splitting changes by concern and staging files individually.

- Skill: `samuelpatro/commit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add samuelpatro/commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samuelpatro/commit/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Dev Tooling
- Tags: Commit, Conventional Commits, Git, Version Control
- Author: samuelpatro (https://skillmd.com/u/samuelpatro)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/samuelpatro/commit

---


## Context

- Current git status: !`git status --short`
- Diff summary (file + line counts): !`git diff HEAD --stat`
- Current branch: !`git branch --show-current`
- Recent commits (for style matching): !`git log --oneline -10`

The full diff is intentionally NOT loaded above. Read hunks on demand with `git diff HEAD -- <file>` for only the files you need to inspect to write the message and decide splits. Do not run `git diff HEAD` with no path filter.

## Your task

Create atomic, self-contained commits with terse, exact messages. Conventional Commits format. No fluff. Why over what.

### Commit Splitting

Split into multiple commits when changes involve:

- **Different concerns** — unrelated parts of the codebase
- **Different types** — mixing feat/fix/refactor/tests/docs/config
- **Different file patterns** — source vs docs vs config
- **Large changesets** — break down for reviewability

Each commit must build and make sense on its own. If all changes relate to one concern, a single commit is fine.

### Message Rules

**Subject line:**
- `<type>(<scope>): <imperative summary>` — `<scope>` optional
- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
- ≤50 chars when possible, hard cap 72
- No trailing period
- Match project convention for capitalization after the colon (check recent commits above)

**Body (only if needed):**
- Skip entirely when the subject is self-explanatory
- Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues
- Wrap at 72 chars
- Bullets `-` not `*`
- Reference issues/PRs at end: `Closes #42`, `Refs #17`

**Auto-clarity — always include body for:** breaking changes, security fixes, data migrations, revert commits. Never compress these into subject-only; future debuggers need the context.

**Breaking changes:** mark subject with `!` and add a `BREAKING CHANGE:` footer explaining the migration.

```
feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026-06-01. Old route returns 410 after that date.
```

**What NEVER goes in:**
- "This commit does X", "I", "we", "now", "currently" — the diff says what
- "As requested by..." — use `Co-authored-by:` trailer instead
- AI attribution: "Generated with Claude Code", co-authorship footers, 🤖 emoji
- Emoji unless project convention requires
- Restating the filename when the scope already covers it

### Examples

Trivial change, no body needed:
```
fix(auth): handle expired refresh token
```

Non-obvious why — body explains motivation:
```
feat(api): add GET /users/:id/profile

Mobile client needs profile data without the full user payload
to reduce LTE bandwidth on cold-launch screens.

Closes #128
```

Breaking change:
```
feat(api)!: rename /v1/orders to /v1/checkout

BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
before 2026-06-01. Old route returns 410 after that date.
```

### HEREDOC Format

```
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body if needed>
EOF
)"
```

### Staging Rules

- Stage specific files by name — do NOT use `git add -A` or `git add .`
- NEVER stage files that may contain secrets: `.env`, `.env.*`, `credentials.json`, `*.key`, `*.pem`, `*.p12`, `id_rsa*`, `token.json`, `secret*`. Warn the user and skip them.
- If all changes are already staged, do not re-stage them.

### Edge Cases

- No changes (nothing staged, nothing modified): say so and stop. Do not create an empty commit.
- Only untracked files that look like generated artifacts (`dist/`, `node_modules/`, `*.log`): warn the user instead of committing them.
- If the user says "normal mode" or "verbose commit": allow a longer, descriptive style for this commit only.