Skip to content
Get packs

Guide · Agent skill

How to use the Git Workflow and Versioning agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The git-workflow-and-versioning skill is a set of instructions that tells an AI agent how to handle version control the way experienced engineers do. Once it is installed, the agent saves work in small commits, keeps each commit focused on one change, writes messages that explain why a change was made, and keeps branches short-lived. This guide explains what the skill does, how to install it, how to ask for it, and what to watch for.

Git Workflow and Versioningaddyosmani/agent-skills · MIT

Quick start

  1. 1Download the skill. Download the git-workflow-and-versioning ZIP from this page. It contains SKILL.md.
  2. 2Install it. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
  3. 3Confirm git is available. Make sure git is installed where the agent works and that your project is a git repository.
  4. 4Make a request. Ask for a git task in plain language, such as committing your changes or splitting a messy working tree into clean commits.
  5. 5Review the commits. Check the commit history and messages the agent produced, and confirm each commit contains one logical change.
  6. 6Keep pull requests small. Aim for roughly 100 lines per pull request and split anything much larger before opening it for review.

What does the git-workflow-and-versioning skill make the agent do?

The skill is guidance only. It does not run git commands itself and contains no scripts. It shapes how the agent works when it touches a git repository, covering commits, branches, pull requests, splitting messy changes, parallel work with worktrees, and releases.

The core ideas are that commits are save points, branches are sandboxes, and history serves as documentation. Agents generate code quickly, so the skill's goal is to keep changes manageable, reviewable and easy to reverse.

  • Commit after each successful increment instead of accumulating large uncommitted changes.
  • Keep each commit to one logical change, and keep refactors separate from features.
  • Write commit messages that explain the why, using types such as feat, fix, refactor, test, docs and chore.
  • Prefer trunk-based development with short-lived feature branches that merge within 1-3 days.
  • Target about 100 lines per commit or pull request, and split changes over about 1000 lines.
  • Use git worktrees so several agents can work on different branches at once.
  • Provide a structured change summary after each modification, including what was intentionally left untouched.

How do you install the skill?

Download the skill ZIP from the page you are reading. The download contains a single file, SKILL.md. Choose one of the following install options depending on how you use your agent.

For Claude Code, unzip the folder into your personal skills directory at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal use across all projects: unzip into ~/.claude/skills/.
  • Single project only: unzip into the project's .claude/skills/ folder.
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills.
~/.claude/skills/git-workflow-and-versioning/SKILL.md

What does the environment need before the skill works?

The skill requires git to be installed in the environment where the agent works. It is most useful when you are working inside a git repository, since most of its guidance concerns commits, branches and history.

The skill does not run scripts and does not use the network. It does not install packages or contact remote servers on its own. Any git actions, such as pushing to a remote, come from the agent running commands in your environment, so you control what it can access.

  • git must be installed where the agent runs.
  • A git repository is needed for the commit and branch guidance to apply.
  • The skill itself runs no scripts and makes no network calls.

How do you trigger the skill with a natural request?

You do not need special syntax. The skill's description lists the situations it covers, so an agent will usually use it when your request involves those tasks. You can also name it directly to make sure it is used.

Requests that match the skill include committing changes, creating a branch, resolving a conflict, splitting uncommitted work into clean commits, opening or reviewing a pull request, pushing, organising parallel work, cutting a release, choosing a version bump, tagging, or writing a changelog.

  • Use git-workflow-and-versioning to split my uncommitted changes into clean atomic commits.
  • Commit this work with good messages, using the git workflow skill.
  • Set up two git worktrees so separate agents can work on different features.
  • Open a pull request for this branch and keep it small and focused.
  • Use the git workflow skill to choose the semantic version bump for this release and write the changelog entry.

What does a typical session look like?

Suppose you ask an agent to add a task-creation feature. With the skill active, the agent works in increments: it implements one slice, runs your tests, and commits when they pass. If a change breaks something, it reverts to the last good commit and investigates rather than piling more changes on top.

Before each commit the skill suggests checking the staged diff, scanning for secrets, and running your tests, linter and type checker. Note that the skill's examples use npm and TypeScript, so adapt those commands to your own project.

  • Check what is staged before committing.
  • Scan the staged diff for passwords, secrets, API keys or tokens.
  • Run tests, linting and type checking for your project.
  • If a step fails, reset to the last successful state with git reset --hard HEAD and investigate.
git diff --staged git diff --staged | grep -i "password\|secret\|api_key\|token" npm test npm run lint npx tsc --noEmit

How do you run parallel agents with worktrees?

For parallel work, the skill recommends git worktrees. Each worktree is a separate directory with its own branch, so agents can work on different features without switching branches in the same folder. Changes stay isolated until you merge them.

If an experiment fails, you can delete its worktree without losing anything in the main branch. When the work is done, merge the branch and remove the worktree.

  • Multiple agents can work on different features at the same time.
  • No branch switching is needed because each directory has its own branch.
  • A failed experiment can be discarded by deleting its worktree.
  • Changes remain isolated until they are explicitly merged.
git worktree add ../project-feature-a feature/task-creation git worktree add ../project-feature-b feature/user-settings git worktree remove ../project-feature-a

What people use it for

  • Splitting a large, messy set of uncommitted edits into focused commits that are easier to review.
  • Running two or more agents in parallel on separate feature branches using git worktrees.
  • Opening small pull requests with descriptive commit messages that explain the reasoning behind each change.
  • Reviewing an agent's change summary to confirm which files were changed and which were intentionally left alone.
  • Organising work for a release, including choosing a semantic version bump and writing a changelog.

Frequently asked questions

How do I install the git workflow and versioning agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

What does the git-workflow-and-versioning skill require?

It requires git to be installed in the environment where the agent works. It runs no scripts and uses no network access, and it is most useful inside a git repository.

Is the git workflow and versioning skill free to use?

The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms.

Does the skill run git commands for me?

No. The skill is guidance only and does not itself run git commands or contain scripts. The agent runs git commands in your environment as part of following the guidance.

Does this skill work with gitflow or long-lived branches?

The skill recommends trunk-based development with short-lived branches. Teams using gitflow or long-lived branches can still apply its commit discipline, such as atomic commits and descriptive messages, but the branching guidance only partly fits those models.

How is this different from just asking an agent to commit my code?

Without a skill, an agent may create one large commit with vague messages. This skill sets rules for commit size, message format, separating refactors from features, short-lived branches, worktrees for parallel work, and a structured change summary.

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

This skill suits developers who use AI agents to write a lot of code and want a clean, reviewable git history, and teams that want consistent commit messages and small pull requests. It is less suited to teams with a strict gitflow or long-lived branch model, or to people who do not work with git repositories at all.

Download the skill