I Taught Claude Code to Enforce Gitflow — Here's the Skill I Built

The Problem

AI coding assistants are great at writing code, but they're terrible at git discipline. Ask Claude Code to commit your changes and you'll get whatever commit message it feels like. Ask it to create a branch and it'll pick a random name. There's no structure, no traceability, no workflow.

For teams that care about clean git history, this is a dealbreaker.

The Solution: A Claude Code Skill

Claude Code has a feature called skills — Markdown files that teach it specific behaviors. I built one that enforces a complete Gitflow workflow:

~/.claude/skills/git-workflow/SKILL.md

One file. No dependencies. Just drop it in and Claude Code starts following the rules.

What It Enforces

Rule	What Claude Does
Gitflow branching	Creates feature/*, fix/*, hotfix/*, release/* from the correct base
Conventional Commits	feat:, fix:, docs:, chore: — always imperative, always lowercase
Issue-driven workflow	Every branch traces back to a GitHub Issue
Semantic Versioning	Proper MAJOR.MINOR.PATCH bumps based on commit types
--no-ff merges	Preserves branch topology in the git graph
No AI signatures	No "Co-Authored-By: Claude" cluttering your history

How It Works in Practice

Say you tell Claude: "I need to fix the broken login flow, there's an issue for it"

Claude will:

1. Check the GitHub issue (e.g., #42)
2. Run git checkout develop && git pull origin develop
3. Create fix/42-broken-login
4. Make atomic commits: fix(auth): resolve login redirect loop
5. Open a PR with title fix(auth): resolve login redirect loop (#42) and Closes #42 in the body
6. After merge, clean up the branch

No prompting gymnastics. No reminding it every time. The skill handles it.

Installation (30 seconds)

git clone https://github.com/qubernetic-org/git-workflow-agent-skill.git
cd git-workflow-agent-skill
./scripts/install_linux.sh   # or install_macos.sh / install_windows.ps1

The install script creates a symlink, so the skill auto-updates when you git pull.

What's Inside

The skill is a single 670-line Markdown file that covers:

• Branch model — 6 branch types with naming conventions
• Commit format — 11 Conventional Commit types with semver impact
• Release process — Standard and hotfix flows with CHANGELOG and tagging
• 10 troubleshooting scenarios — "I accidentally committed to main", "I force-pushed a shared branch", etc.
• Decision guides — Quick-reference tables for "which branch?", "which commit type?", "do I bump the version?"
• Forbidden operations — 14 things Claude will refuse to do (direct commits to main, squash merges, skipping version bumps)

The Repo Also Includes

• Automated linter (scripts/lint.sh) — validates SKILL.md structure and version consistency
• CI/CD — lint runs on every PR via GitHub Actions
• Auto-close workflow — closes issues when PRs merge to non-default branches (solves a real GitHub limitation with Gitflow)
• Cross-platform install scripts — Linux, macOS, Windows
• Integration guide — commitlint + husky configs that match the skill's rules

Why Not Just Use commitlint/husky?

Those tools validate commit messages mechanically. This skill operates at a higher level:

• It knows which branch to create from which base
• It knows when to bump versions and by how much
• It traces issues to branches to PRs to changelogs
• It handles the entire release ceremony (branch, bump, changelog, tag, GitHub Release, back-merge)

The best setup is both: the skill for workflow intelligence, commitlint/husky for mechanical safety nets.

Built With Its Own Rules

The repo itself follows the exact workflow the skill defines. Every commit is conventional, every branch is issue-driven, every merge is --no-ff. Check the git history — it's the proof that the system works.

Try It

GitHub: qubernetic-org/git-workflow-agent-skill

MIT licensed. Zero dependencies. Works with any project that uses git.

If you've been frustrated by AI assistants that treat git like an afterthought, give it a shot. And if you find an edge case the skill doesn't handle — open an issue. That's how the troubleshooting section got to 10 scenarios.