home / skills / softaworks / agent-toolkit / commit-work

commit-work skill

safe

This skill helps you manage commits with conventional messages, selective staging, and clear descriptions to improve reviewability and ship safely.

npx playbooks add skill softaworks/agent-toolkit --skill commit-work

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.4 KB

---
name: commit-work
description: "Create high-quality git commits: review/stage intended changes, split into logical commits, and write clear commit messages (including Conventional Commits). Use when the user asks to commit, craft a commit message, stage changes, or split work into multiple commits."
---

# Commit work

## Goal
Make commits that are easy to review and safe to ship:
- only intended changes are included
- commits are logically scoped (split when needed)
- commit messages describe what changed and why

## Inputs to ask for (if missing)
- Single commit or multiple commits? (If unsure: default to multiple small commits when there are unrelated changes.)
- Commit style: Conventional Commits are required.
- Any rules: max subject length, required scopes.

## Workflow (checklist)
1) Inspect the working tree before staging
   - `git status`
   - `git diff` (unstaged)
   - If many changes: `git diff --stat`
2) Decide commit boundaries (split if needed)
   - Split by: feature vs refactor, backend vs frontend, formatting vs logic, tests vs prod code, dependency bumps vs behavior changes.
   - If changes are mixed in one file, plan to use patch staging.
3) Stage only what belongs in the next commit
   - Prefer patch staging for mixed changes: `git add -p`
   - To unstage a hunk/file: `git restore --staged -p` or `git restore --staged <path>`
4) Review what will actually be committed
   - `git diff --cached`
   - Sanity checks:
     - no secrets or tokens
     - no accidental debug logging
     - no unrelated formatting churn
5) Describe the staged change in 1-2 sentences (before writing the message)
   - "What changed?" + "Why?"
   - If you cannot describe it cleanly, the commit is probably too big or mixed; go back to step 2.
6) Write the commit message
   - Use Conventional Commits (required):
     - `type(scope): short summary`
     - blank line
     - body (what/why, not implementation diary)
     - footer (BREAKING CHANGE) if needed
   - Prefer an editor for multi-line messages: `git commit -v`
   - Use `references/commit-message-template.md` if helpful.
7) Run the smallest relevant verification
   - Run the repo's fastest meaningful check (unit tests, lint, or build) before moving on.
8) Repeat for the next commit until the working tree is clean

## Deliverable
Provide:
- the final commit message(s)
- a short summary per commit (what/why)
- the commands used to stage/review (at minimum: `git diff --cached`, plus any tests run)

Overview

This skill helps you create high-quality git commits by reviewing changes, staging only intended hunks, splitting unrelated work into logical commits, and writing clear Conventional Commit messages. It guides the commit process end-to-end so commits are easy to review and safe to ship. The skill returns final commit messages, short summaries, and the staging/review commands used.

How this skill works

Inspect the working tree and unstaged diffs to identify logical commit boundaries. Stage only the hunks that belong to the next commit (prefer patch staging) and review the index before committing. Compose Conventional Commit messages with a concise subject, optional scope, descriptive body explaining what and why, and any footers for breaking changes or references.

When to use it

When you ask the agent to commit changes or craft commit messages.
When a working tree contains mixed or unrelated changes and needs splitting.
When you want Conventional Commits for CI, changelogs, or policy compliance.
Before pushing to shared branches to ensure commits are reviewable and clean.
When you need a reproducible sequence of small, verifiable commits.

Best practices

Inspect unstaged and staged diffs first: git status, git diff, git diff --stat.
Default to multiple small commits for unrelated changes; combine only truly cohesive changes.
Use git add -p for mixed files and git restore --staged <path> to unstage mistakes.
Describe the staged change in 1–2 sentences (what and why) before writing the message.
Follow Conventional Commits: type(scope): short summary, blank line, body, footer.
Run the fastest meaningful verification (unit tests or linter) after staging and before committing.

Example use cases

Split a branch that contains formatting, a bugfix, and a dependency upgrade into three commits with clear messages.
Stage only the bugfix hunks from several files using patch staging and commit with feat(parser): fix tokenization bug.
Convert an ambiguous large change into multiple focused commits by grouping by purpose (tests, refactor, feature).
Generate Conventional Commit messages for CI-driven changelog generation before a release.

FAQ

Should I always split into multiple commits?

Prefer multiple small commits for unrelated changes. If changes are tightly related and self-contained, a single commit is fine.

What if a file has both formatting and logic changes?

Use git add -p to stage formatting and logic separately, or revert formatting and reapply after logic is finalized.