diff --git a/.claude/skills/creating-commits/SKILL.md b/.claude/skills/creating-commits/SKILL.md new file mode 100644 index 0000000..564919b --- /dev/null +++ b/.claude/skills/creating-commits/SKILL.md @@ -0,0 +1,115 @@ +--- +name: creating-commits +description: Create well-structured git commits with clear, conventional commit messages. Use this skill whenever the user asks to commit changes, "commit this", "save my work", "make a commit", "write a commit message", or after completing a coding task when changes need to be committed. Also use when the user asks to split changes into multiple commits, amend a commit, or improve an existing commit message. +--- + +# Creating Commits + +A skill for producing clean, atomic commits with high-quality messages. + +## Workflow + +Always follow these steps in order: + +### 1. Inspect before committing + +Run these in parallel to understand the state of the repo: + +```bash +git status # what's staged, unstaged, untracked +git diff # unstaged changes +git diff --staged # staged changes +git log --oneline -10 # recent messages, to match repo style +``` + +Never commit blind. Read the actual diff — the commit message must describe what changed, not what you think you changed. + +### 2. Decide what belongs in the commit + +- **One logical change per commit.** If the diff contains unrelated changes (e.g., a bug fix AND a refactor AND a config tweak), propose splitting into separate commits. Use `git add -p` or stage files selectively. +- **Never use `git add .` or `git add -A` reflexively.** Stage files explicitly by path so unrelated or accidental files (logs, `.env`, build artifacts, editor files) don't slip in. +- Check for files that should not be committed: secrets, credentials, large binaries, generated output. Warn the user if any appear in the diff. +- Do not commit commented-out code or leftover debug statements without flagging them first. + +### 3. Write the message + +Detect the repo's convention from `git log`. If the repo uses Conventional Commits, follow it. Otherwise use the standard format below. + +**Format:** + +``` +(): + + +``` + +**Types** (Conventional Commits): `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `revert`. + +**Subject line rules:** +- Imperative mood: "add validation", not "added" or "adds". Test: the line should complete "If applied, this commit will ___". +- ≤50 characters, no trailing period, lowercase after the type prefix. +- Be specific: `fix: prevent race condition in session refresh` — not `fix: bug fix` or `update code`. + +**Body rules (when needed):** +- Explain *why* the change was made and any non-obvious consequences; the diff already shows *what*. +- Mention alternatives considered or constraints if relevant. +- Skip the body only for genuinely trivial changes (typo fixes, version bumps). + +**Never:** +- Vague messages: "fixes", "wip", "updates", "misc changes". +- Restating the diff line-by-line. +- Bundling "and also..." — that's a sign the commit should be split. +- Adding footer and information about co-author like Claude etc. + +### 4. Commit + +Use a heredoc for multi-line messages: + +```bash +git commit -m "$(cat <<'EOF' +fix(auth): prevent race condition in token refresh + +Two concurrent requests could both detect an expired token and +trigger duplicate refresh calls, invalidating each other's sessions. +Serialize refresh behind a per-user mutex. + +Fixes #482 +EOF +)" +``` + +### 5. Verify + +Run `git status` and `git log -1 --stat` after committing to confirm the commit contains exactly what was intended. + +## Special cases + +- **Amending**: only `git commit --amend` when the commit has NOT been pushed, and confirm with the user first. +- **Empty diff**: if there is nothing to commit, say so — do not create empty commits. +- **Pre-commit hooks**: if a hook fails, fix the underlying issue rather than using `--no-verify`. Only bypass hooks if the user explicitly asks. If a hook modifies files (e.g., a formatter), re-stage and retry once. +- **Never push, force-push, or rewrite history** unless the user explicitly asks. +- **Breaking changes**: mark with `!` after the type (`feat!:`) and a `BREAKING CHANGE:` footer explaining migration. + +## Examples + +Good: + +``` +feat(api): add cursor-based pagination to /orders endpoint + +Offset pagination degraded past ~100k rows. Cursor pagination keeps +response times flat and matches the pattern used in /customers. +``` + +``` +chore: bump lodash to 4.17.21 +``` + +Bad: + +``` +update stuff +fixed the thing we talked about +WIP +feat: changes to api and also fixed tests and updated readme +```