code/skills/builtins/commit-workflow/SKILL.md

metadata

name: commit-workflow
description: >-
  Guided git commit workflow. Use before committing changes — generates a clean
  commit message from the diff.
language: any
tags: git, commit, version-control

Commit Workflow

When the user asks to commit changes, follow this workflow.

Step 1: Inspect the changes

Run via bash:

• git status — see what's modified/staged/untracked
• git diff HEAD — full diff of staged and unstaged changes
• git branch --show-current — current branch
• git log --oneline -10 — recent commits (to match style)

Step 2: Analyze

Determine:

• What's the single logical change being committed?
• Are there multiple unrelated changes? If so, suggest splitting into multiple commits.
• What's the conventional commit type?
  • feat: new feature
  • fix: bug fix
  • docs: documentation only
  • style: formatting, no code change
  • refactor: code change that neither fixes a bug nor adds a feature
  • perf: code change that improves performance
  • test: adding tests
  • chore: build process, tooling, deps

Step 3: Write the message

Format:

<type>(<optional scope>): <imperative subject under 72 chars>

<optional body explaining why, wrapped at 72 chars>

<optional footer like "Fixes #123">

Rules:

• Subject in imperative mood: "Add" not "Added" or "Adds"
• Subject lowercase, no period
• Body explains why, not what (the diff shows what)
• Reference issues in footer

Step 4: Stage and commit

If specific files should be staged, run git add <files> explicitly. Otherwise git add -A is fine.

Commit with a heredoc to preserve formatting:

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 login flow

Implements the login button, callback handler, and session
persistence using JWT in httpOnly cookies.

Fixes #142
EOF
)"

Step 5: Verify

• git log -1 --stat to confirm the commit looks right
• git status to confirm clean working tree (or remaining unrelated changes)

Anti-patterns

• ❌ git commit -m "fix" — too vague
• ❌ git commit -m "Update file.py" — describes what, not why
• ❌ Mixing unrelated changes in one commit
• ❌ Committing node_modules/, .env, build artifacts
• ❌ Using --no-verify to skip hooks without explanation