Guide · Agent skill
How to use the Work-Unit Commit Planner agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The work-unit-commits skill is a set of instructions that tells an AI coding agent how to split a code change into commits and pull requests that each deliver one clear piece of behavior, fix, or documentation update. It is for developers who have a large feature or refactor and want reviewable history rather than commits grouped by file type. After this guide you will know how to install the skill, how to ask for it, and what the agent will check before it commits.
Work-Unit Commit PlannerGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Download the ZIP. Download the work-unit-commits ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill.
- 4Make your change. Write or stage the code, tests, and docs for one feature, fix, or refactor.
- 5Ask for a commit plan. Describe the change in plain language and ask the agent to split it into work-unit commits with tests and docs included.
- 6Review with git. Run git diff --stat and git diff --cached --stat, and git log --oneline -5 to match commit style.
- 7Commit or chain PRs. Commit each unit with a Conventional Commit message, and promote commits into chained PRs if the change nears 400 changed lines.
What the skill makes the agent do
Agent skills are folders of instructions that an AI agent loads when a task matches the skill's description. This one is named work-unit-commits and its description says it plans commits as reviewable work units. It applies when the task involves implementation, commit splitting, chained PRs, or keeping tests and docs with code.
Under this skill, a commit represents a deliverable behavior, fix, migration, or docs unit. The agent avoids splitting by file type, such as one commit for models, then one for services, then one for tests, when none of those pieces works alone. Tests go in the same commit as the behavior they verify, and docs go with the user-visible change they explain.
- Each commit should have one clear purpose and leave the repo in a sensible state.
- Each commit message should explain the outcome, not list the files changed.
- Commits use Conventional Commit messages, for example feat(auth): wire token validation into login flow.
- When a change grows past about 400 changed lines, commits can be promoted into chained PRs.
Install the skill on Claude Code or in the Claude apps
Download the ZIP for this skill from this page. The skill is a single file, SKILL.md, so the ZIP contains that one file inside a skill folder.
For Claude Code, unzip it into your personal skills folder at ~/.claude/skills/ so it is available in every project. To limit it to one repository, unzip it into that project's .claude/skills/ folder instead.
In the Claude apps, open Settings, go to Capabilities, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: the .claude/skills/ folder inside your repository
Trigger the skill with natural requests
You do not need a special command. The agent loads the skill when your request matches its trigger topics, so describe the job in plain language. Mention commits, PRs, splitting, or keeping tests with code.
Good requests name the change and the outcome you want, for example asking the agent to split a branch's uncommitted work into reviewable commits, or to plan a chain of PRs for a large refactor. Mentioning that you want tests and docs kept with the code helps the agent apply the right rules from the start.
- Split my uncommitted changes into reviewable commits with tests included.
- This refactor is 900 lines. Plan it as chained PRs under 400 changed lines each.
- Before I commit, check whether this change is one work unit or should be split.
Review the change with git before committing
The skill suggests checking the story of your change with git before you commit. Run the diff summary for unstaged changes, the staged summary, and the recent commit style so your message matches the history already in the repo.
These are the commands the skill suggests. They only read repository state. The skill itself runs no scripts.
# Review the story before committing
git diff --stat
git diff --cached --stat
# Check recent commit style
git log --oneline -5Check each commit against the work-unit checklist
Before a commit is made, the skill asks the agent to confirm a short checklist. The commit must have one clear purpose, and the repo must still make sense after applying only that commit. Tests or docs for the unit should be included when relevant, and rollback should be reasonable without reverting unrelated work.
The checklist also asks for the focused test command and its exact result, plus a runtime harness command or an explicit N/A with a reason. It asks for the rollback boundary, meaning the exact files or behavior that could be removed without touching unrelated work.
- One clear purpose per commit
- Repo still works after only this commit
- Tests or docs for this unit included when relevant
- Rollback possible without reverting unrelated work
- Focused test command and exact result recorded
- Commit message explains the outcome, not the file list
Turn a large change into chained PRs
When a change approaches 400 changed lines, the skill has the agent promote commits or groups of commits into chained PRs. The workflow is to build the smallest independent work unit, include its verification, commit it with a Conventional Commit message, and repeat. For SDD tasks, the skill asks the agent to group commits into chained PR slices before implementation if the forecast is over 400 lines.
The skill also describes an ODD (Organic Driven Development) workflow in which each substantial task closes with a work-unit commit on a feature branch. Counting authored additions plus deletions is used for the 400-line threshold, and generated goldens are excluded from that count.
- Use the smallest independent unit as the first commit.
- Keep verification in the same unit as the change.
- Promote commits into chained PRs when the PR nears 400 changed lines.
What people use it for
- Splitting a large feature branch into a sequence of commits, each with its own tests.
- Planning a big refactor as chained PRs that each stay under about 400 changed lines.
- Writing Conventional Commit messages that describe what changed for users rather than which files were touched.
- Checking whether a small change should be one commit or several before opening a PR.
- Keeping user-facing documentation in the same commit as the behavior it describes.
Frequently asked questions
How do I install the work-unit-commits skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one repository. In the Claude apps, you can instead open Settings, go to Capabilities, and upload the skill.
Is the work-unit-commits skill free and what licence does it use?
The source for this skill is listed under the MIT licence on this page. The SKILL.md file itself states Apache-2.0 in its metadata, so check the licence details on the source repository before reuse.
What do I need to use this skill?
You need git, because the suggested commands are git diff and git log. The skill runs no scripts and uses no network access, according to its listing.
Does the skill work with commit conventions other than Conventional Commits?
Not as written. The skill assumes Conventional Commit messages and a 400-line guideline, so projects with different conventions will need to adapt the instructions or pick another approach.
Why does the agent split my changes by behavior instead of by file type?
The skill's critical rules say not to commit by file type, because a models-then-services-then-tests split often produces commits that do not work alone. Each commit should be a deliverable unit with its tests and docs included.
When is this skill not worth using?
It adds overhead for quick one-line fixes. It is also not suited to non-developers who do not use git, since the guidance is about git history and PR review.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a developer or team preparing commits or chained PRs from a large feature or refactor and want tests and docs kept with the code. Skip it for quick one-line fixes, projects with different commit conventions, or work that does not involve git.
Download the skill